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.

Update: the protocols landed, and need syncing

python/importlib_metadata#505 merged 2026-10-23 and released in importlib_metadata 10.0.0. It takes the shared-protocol approach settled on in python/importlib_metadata#486 rather than either recommendation above:

• IDistribution and IPackagePath protocols join the existing PackageMetadata, so providers and consumers have one interface that the classes of both libraries satisfy.
• Objects a provider supplies from importlib.metadata are adapted to this package's classes where they can be. An arbitrary Distribution subclass cannot be, so it is passed through, and the warning now fires only where the class omits members IDistribution requires, naming them, rather than merely because it derives from importlib.metadata.

So neither recommendation above is needed: a provider implements the interface, and a conforming one draws no warning. gh-160344 drafts the documentation on that basis.

That documentation names the protocols, so this issue now also covers getting them into the stdlib. Under the development methodology, _meta.py carries the protocols and syncs downstream, while the compat and _compat packages holding localize and its warning are excluded from the port. Only the protocols arrive here, which is what gh-160344 assumes.

Lib/importlib/metadata/ was last synced at importlib_metadata 8.7 (gh-132947, 3.15.0a1). The current release is 10.1.0, so a sync spans 9.0.0, 9.0.1, 9.1.0, 10.0.0 and 10.1.0 — among them the MetadataNotFound and KeyError changes, lazy EntryPoint.value validation, the metadata directory preference added in 9.1.0 and reverted in 10.1.0, and the Prepared.normalized and metadata detection performance work. Some of those originated in CPython and have already been ported back, so the diff wants tracing rather than taking wholesale.

Tasks

• Sync Lib/importlib/metadata/ with importlib_metadata 10.1.0
• Document the custom provider caveats (gh-123976: Document the protocols shared with the importlib_metadata backport #160344), which depends on the sync

Linked PRs

• gh-123976: Refresh docs around custom providers. #123977
• gh-123976: Document the protocols shared with the importlib_metadata backport #160344