Documentation

Asimportlib_metadata provides a backport ofimportlib.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 fromimportlib.metadata (not using the backport). For example:

• project A implements and installs a DistributionFinder tosys.meta_path providingimportlib.metadata.Distribution instances.
• project B callsimportlib_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 returnIterable[importlib_metadata.Distribution] objects, their expectation is violated when theDistributionFinder installed by project A emitsimportlib.metadata.Distribution objects.

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 referencingimportlib.metadata to instead use objects fromimportlib_metadata.

However, forimportlib.metadata.Distribution objects, it's not possible to replace safely the objects of an arbitrary custom provider, so the proposed implementationemits a warning when such an object is encountered.

Therefore, we'd like to add some documentation to thecustom provider docs to advise custom providers on what to do to avoid their users encountering the warning. In particular:

• Custom providers should emitimportlib_metadata.Distribution objects whenimportlib_metadata is present, or
• Custom providers should register their objects withimportlib_metadata to bypass the warning.

Linked PRs

• gh-123976: Refresh docs around custom providers. #123977