GeezerVison

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?

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.

As discussed in #486, I believe the direction we're going is to unify the the interfaces (through #505 plus new protocols).