Expand documentation for importlib.metadata custom providers to include caveats regarding backports

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_path providing importlib.metadata.Distribution instances.
• 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 the DistributionFinder installed by project A emits importlib.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 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.Distribution objects when importlib_metadata is present, or
• Custom providers should register their objects with importlib_metadata to bypass the warning.

Linked PRs

• gh-123977