Adopt "more sound" type annotations

[abravalheri]

Motivated by #486.

This PR just provides more realistic type annotations¹ to improve the type checking soundness of the package.

It does not solve #486: all the limitations are still present, but at least type checkers would help to notify users when they are trying to use new APIs that are not safe (not necessary all the time, but better than now).

It is a bit of a pain, but these annotations should be a bit more sound than they currently are.

This should also prevent future versions of this library from introducing incompatible behaviour (thanks to pytest-mypy).

Footnotes

1. Technically speaking, "a bit more correct". Because importlib_metadata collects 3rd-party implementations via find_distributions everything can happen. ↩

[jaraco]

Thanks for the proposal. I'm going to have to think about this more.

This library is merged back into CPython as importlib.metadata so these annotations won't make sense when that happens. Moreover, this is the first introduction of references to importlib.metadata in this library, so I'm unsure what the implications will be.

Is there any way to achieve the objectives either by:

• adjusting the patch to be universal (so it's meaningful in both importilb_metadata and importlib.metadata), or
• moving the backport-specific concerns to a ./compat/* module that would be omitted downstream in CPython?

[abravalheri]

Thanks @jaraco for the code review.

Is there any way to achieve the objectives either by:

• adjusting the patch to be universal (so it's meaningful in both importilb_metadata and importlib.metadata), or

Unfortunately I don't think so.
importlib_metadata has a backwards compatibility problem that simply disappears when it becomes importlib.metadata.

In this sense only importlib_metadata need these contrived type annotations to inform end-users that they can get back legacy objects when using the API.

• moving the backport-specific concerns to a ./compat/* module that would be omitted downstream in CPython?

I gave it a try... don't know if that is exactly what you had in mind, but I tried to do my best.
Please note that the annotations are not specific to a version of Python, but always will be necessary while importlib_metadata exists in PyPI. In the future I believe they may be useful during development (e.g. by identifying places where legacy objects are retrieved and preventing incompatible methods to be called on them).

I am not good with names, so if you have suggestions regarding names please let me know.