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 topytest-mypy).

Footnotes

Technically speaking, "a bit more correct". Becauseimportlib_metadata collects 3rd-party implementations viafind_distributions everything can happen.↩

abravalheri changed the title~~Adopt more realistic type annotations~~Adopt "more sound" type annotations

May 2, 2024

abravalheri marked this pull request as ready for review

May 2, 2024 10:44

Copy link

Member

jaraco commentedJun 23, 2024

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

This library is merged back into CPython asimportlib.metadata so these annotations won't make sense when that happens. Moreover, this is the first introduction of references toimportlib.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 added4 commits

June 24, 2024 09:47

Use more realistic return types

3a90a8d

Use type check guard for legacy annotations

c1612ec

Fix type annotation for Python 3.10+

e30d8f7

Fix warnings in sphinx docs

2044db1

abravalheri force-pushed theissue-486 branch from99ef61a to77eb71eCompare

June 24, 2024 09:33

Move code specific to backport to compat module

4fe96a4

abravalheri force-pushed theissue-486 branch from77eb71e to4fe96a4Compare

June 24, 2024 09:41

Copy link

ContributorAuthor

abravalheri commentedJun 24, 2024

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 becomesimportlib.metadata.

In this sense onlyimportlib_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 whileimportlib_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.