Add type hints to public API

[FFY00]

Hey, would it be possible to add type hints to public API? Thanks.

[layday]

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.

[takluyver]

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.

[layday]

Would you like me to open a PR for the commit above?

[xavfernandez]

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?

[FFY00]

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.

[layday]

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.

[takluyver]

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.

[jdufresne]

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 #131. I think once there is no Python 2 compatibility, there will be fewer hurdles to add type hints.

[pradyunsg]

Once #151 lands, there will be a significantly smaller API surface as well.

[pradyunsg]

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.

[q0w]

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