Problem with PackageMetadata protocol

[jaraco]

In #371, @saaketp reported:

The second problem is not clear whether it was intentional or a mistake. The actual type returned by the metadata function is a subclass of email.message.Message which supports "dict-like" operations like .get and .items(). I have seen some scripts rely on this dict-like behavior and I only noticed these methods are not present in PackageMetadata protocol because of pyright complaining.

Are those methods intentionally left out of the protocol or should they be added?

[jaraco]

Those methods were intentionally left out of the protocol. Only the protocol interface is supported. Let me know if you have follow-up concerns or advice.

[saaketp]

Thanks @jaraco for the response. My only concern is that it is not easy to figure out what is supported or not unless you are using a type checker, which most people don't.

The standard library docs don't mention this properly. The only section that mentions PackageMetadata is https://docs.python.org/3/library/importlib.metadata.html#distribution-metadata. It would be good to have a section about PackageMetadata itself with the list of methods it has, like it is done for all other standard library classes.

Without that I think people just look at the methods available on the object at runtime, which contains a lot of extra stuff which is not supported, and the fact that it behaves almost like a dict makes it more likely to be confusing.

I see that the docs in readthedocs have a API reference which kinda has this information (though it would be good to list the dunder methods supported too) https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata but this is not included in the stdlib docs (unless I missed it somehow). I only started using this after it landed in the standard library, so I first looked at the docs in standard library and only found these docs later.

[jaraco]

These docs are synced to the standard library, except some features available here don't have an analog in CPython (such as automodule). That's why the docs here are better than the docs there. To get to these same docs in CPython, you have to follow the link to the source.

It would be good to have a section about PackageMetadata itself with the list of methods it has, like it is done for all other standard library classes.

I'd welcome contributions to supply this. I'm personally disinclined to write documentation that is merely a copy of what the implementation already documents and the dependency and maintenance burden that creates. Better would be for the CPython docs to support automodule or something similar to render docs in the code to the manual. Until then, the best users have is to fall back to the importlib_metadata docs.

I have seen some scripts rely on this dict-like behavior.

Perhaps importlib metadata should mask these interfaces so that others aren't tempted to rely on them... or at least advertise them as unsupported.

[saaketp]

Maybe we can just have a "See also:" box that links to https://importlib_metadata.readthedocs.io/?
Similar to how https://docs.python.org/3/library/sqlite3.html links to https://www.sqlite.org

And then another link to https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata after the first mention of PackageMetadata to advertise what is supported.

[jaraco]

That sounds good to me. Are you willing to draft that change? If you propose it in this project under the using.rst doc, and it will get merged upstream into CPython.

[saaketp]

Okay I created a PR for that change #375

I wasn't too sure about how rst works, so I just copy pasted the directives I saw being used in cpython docs, hopefully they work here too.