Repository navigation
Expand documentation for importlib.metadata custom providers to include caveats regarding backports #123976
Description
Documentation
As importlib_metadata provides a backport of importlib.metadata and asserts primacy when imported, for consumers of the API, it provides a consistent interface, except when a custom provider serves objects as imported from importlib.metadata (not using the backport). For example:
- project A implements and installs a DistributionFinder to
sys.meta_pathprovidingimportlib.metadata.Distributioninstances. - project B calls
importlib_metadata.distributions()to return all distributions, including that of project A. - A user installs project A and project B.
- When project B queries for the distributions, expecting it to return
Iterable[importlib_metadata.Distribution]objects, their expectation is violated when theDistributionFinderinstalled by project A emitsimportlib.metadata.Distributionobjects.
python/importlib_metadata#486 captures this concern. python/importlib_metadata#505 promises to correct this concern by wrapping and transforming any objects from custom providers referencing importlib.metadata to instead use objects from importlib_metadata.
However, for importlib.metadata.Distribution objects, it's not possible to replace safely the objects of an arbitrary custom provider, so the proposed implementation emits a warning when such an object is encountered.
Therefore, we'd like to add some documentation to the custom provider docs to advise custom providers on what to do to avoid their users encountering the warning. In particular:
- Custom providers should emit
importlib_metadata.Distributionobjects whenimportlib_metadatais present, or- Custom providers should register their objects with
importlib_metadatato bypass the warning.
Activity
jaraco commentedon Sep 11, 2024
As I write that recommendation, I'm already uncomfortable with the recommendation. It's unclear what "when
importlib_metadatais present" means. Does it mean the module is available for import? Does it mean it's been imported previously (e.g. insys.modules)?I think it has to mean it's available for import, because the provider can't tell if it will later be imported by a consumer. But that also means the provider might activate
importlib_metadatain an environment that would otherwise have never had it activated. Perhaps that's not a huge concern - if it's installed, it's likely to be activated.That also means that users of
importlib.metadatawill be gettingimportlib_metadata.Distributionobjects, violating the type spec. But that's the case already today, so perhaps that's not so bad.Also, "register with
importlib_metadatato bypass the warning" sounds messy at best. There probably aren't a lot of providers out there, but even so, having to make new releases that are required to support their custom provider does not sound like a lot of fun for anyone.jaraco commentedon Sep 11, 2024
All of this has me re-thinking the strategy.
Maybe instead of having two distinct class trees (
importlib.metadata.Distributionandimportlib_metadata.Distributionand subclasses), there should be a protocol that's shared by both versions of the library, explicitly modeling what's currently implicit - that there's an interface expected byDistributionobjects (alsoPackagePathandMessageobjects), and those protocols are what the two libraries are coded against.pythongh-123976: Refresh docs around custom providers.
pythongh-123976: Refresh docs around custom providers.
gh-123976: Refresh docs around custom providers. (#123977)
hugovk commentedon Sep 15, 2024
Triage: #123977 has been merged, ready to close this?
jaraco commentedon Sep 15, 2024
Thanks, but no. The PR only did some minor refreshing of the docs. The core concern of this issue remains.