[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.

Assumes two things that have not landed

python/importlib_metadata#505. Released importlib_metadata (9.0.1) has
no localize module, so today there is no substitution and no warning to
document. The text describes 505 as of 3130095: localize.dist /
localize.message / localize.package_path, and the UserWarning raised
when 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.

The protocols in this module. IDistribution and IPackagePath are
documented here with .. versionadded:: 3.16, but no such change to
Lib/importlib/metadata/ exists yet; today they live only in the backport.
This PR is docs-only and must not land before that change does. Note the
backport's protocols are @runtime_checkable and the stdlib's existing
PackageMetadata and SimplePath are not, which the code change would need
to reconcile for the conformance check.

Assumed, but not documented as such: that only the protocols come to the
stdlib. The localize machinery and its warning stay backport behavior, since
this module has no reason to convert the backport's objects and cannot import
it to try.

🤖 Generated with Claude Code

• Issue: Expand documentation for importlib.metadata custom providers to include caveats regarding backports #123976

[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