pyproject-hooks
pyproject-hooks copied to clipboard
pypa
Add type hints to public API
I added type hints, mostly as an exercise, here. I don't know whether this would be a welcome addition so I haven't opened a PR.
I'm open to adding type hints where they're not too ugly. I've never worked with the stub files for Python 2 compatible hints, though, so it's entirely possible I'd just overlook them when things changed.
I don't know what pep517 is planning but pip will be dropping python 2 support in January 2021. If pep517 plans to do the same, it might want to wait 2,5 months to add type hints inline vs the stub route?
Why don't we use type hint comments? They are Python 2 compatible and even if we drop Python 2 support we will have to use them if we don't plan on dropping Python 3.5.
Why would you need to use comments in 3.5? As for placing type hints in-line, you'd either have to conditionalise importing typing (how to do this isn't always obvious) and quote annotations, or require typing as a runtime dependency.
As a boring, low-level piece of infrastructure I'd expect pep517 to be generally quite slow to drop old Python versions. If the spec changes (like it did for backend-path), the library will need to change. And tools using the library probably want the spec to be covered on all versions of Python those tools still support.
That said, I think pip is also pretty conservative, so unless someone comes to say they need Python 2 support for another few months, I'm OK with dropping it not long after pip does.
That said, I think pip is also pretty conservative, so unless someone comes to say they need Python 2 support for another few months, I'm OK with dropping it not long after pip does.
I started this process in https://github.com/pypa/pep517/pull/131. I think once there is no Python 2 compatibility, there will be fewer hurdles to add type hints.
Once #151 lands, there will be a significantly smaller API surface as well.
FWIW, if someone does tackle this, it'd be awesome to also expose the type information in the Sphinx documentation as well.
See https://installer.readthedocs.io/en/stable/api/init/ for an example, and https://github.com/pypa/installer/blob/0b72640fcdd95c80a73bb94eaa3377381ef5b8e0/docs/conf.py#L30-L41 for the API documentation configuration that generates documentation with that structure.
There's a few manual docs-only type annotations which would likely make the actual work here easier too.
Should it be in .pyi files because it requires custom protocols from typing_extensions like SupportsKeysAndGetItem, StrOrBytesPath, etc and lots of sys.version checks for a compatibility
I've filed #167 for this.
@q0w I don't think this needs to be in .pyi files, since most of the logic can expect a dictionary, rather than going all the way down to the specific operations in play.