[jaraco]

Documents the interaction between a custom provider and the
importlib_metadata backport, built around the protocols both libraries
satisfy.

The two libraries define separate, unrelated class hierarchies but discover
distributions through the same sys.meta_path, so one provider serves
consumers of both and cannot satisfy both by subclassing. The protocols, not
any concrete class, are the interface to write against.

• New "Caveats for backports" section, split into guidance for consumers and
  for custom providers.
• Documents IDistribution and IPackagePath.
• Corrects the PackageMetadata entry. It currently calls itself "a concrete
  implementation of the PackageMetadata protocol" and links to the backport's
  docs for the protocol, but importlib.metadata._meta.PackageMetadata is
  itself a Protocol, and is exported in __all__.
• Points from the DatabaseDistribution example to the provider guidance.

Depends on the importlib_metadata sync

python/importlib_metadata#505 merged on 2026-10-23 and released in
importlib_metadata 10.0.0; the current release is 10.1.0. This text describes
that behavior: localize.dist / localize.message / localize.package_path,
the IDistribution / IPackagePath / PackageMetadata protocols added per
python/importlib_metadata#486, and the UserWarning raised where a provider's
class omits members IDistribution requires. Because that warning is decided
by conformance rather than by class identity, a provider deriving from
Distribution and inheriting the rest of the interface — the example in these
docs — draws no warning.

IDistribution and IPackagePath are documented here with
.. versionadded:: 3.16, but Lib/importlib/metadata/ does not have them
yet. They arrive by the usual sync: _meta.py is synced downstream, carrying
the protocols and the @runtime_checkable the conformance check needs, while
the compat and _compat packages holding localize and its warning are
excluded from the port. That is why only the protocols are documented here as
this module's own, and the warning is described as the backport's behavior.

CPython was last synced at importlib_metadata 8.7 (gh-132947, 3.15.0a1). The
sync is tracked on gh-123976; this PR should not land before it.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35338294 | 📁 Comparing be9a5de against main (e7e0b35)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• library/dis.html
• library/importlib.metadata.html
• library/shutil.html
• using/configure.html
• using/windows.html
• whatsnew/3.16.html
• whatsnew/changelog.html