GeezerVison

Describe how the separate class hierarchies in importlib.metadata and
the importlib_metadata backport affect custom providers: which objects
the backport substitutes, which it passes through with a warning, and
why a provider should implement the whole interface and rely on the
shared protocols rather than on a particular base class.

Co-Authored-By: Claude Opus 5 <[email protected]>

importlib_metadata now decides the warning by conformance to
IDistribution rather than by class identity, so a provider that
presents the whole interface draws no warning and the warning names
what a class omits.

Co-Authored-By: Claude Opus 5 <[email protected]>

The guidance to rely on the interface rather than the type addresses
every consumer, not only a provider that consumes metadata, so promote
the caveats to their own section and split it by audience. Note that
the protocols come from the backport, which this module does not yet
present.

Co-Authored-By: Claude Opus 5 <[email protected]>

Assume the shared protocols from python/importlib_metadata#505 are
presented by this module as well: document IDistribution and
IPackagePath, correct PackageMetadata, which is already a protocol here
rather than an implementation of the backport's, and write the caveats
around the protocols as the interface both libraries satisfy.

Co-Authored-By: Claude Opus 5 <[email protected]>

…backport-caveats

Adds the IDistribution and IPackagePath protocols, so a consumer can
target one interface across this module and the backport rather than
either library's concrete classes, and annotates the functions returning
distributions and files with them.

The backport's compat and _compat packages are excluded from the port as
usual, so localize and the conformance warning it raises do not appear
here; only the protocols they are defined against do. This is what the
caveats documented for pythongh-123976 in this branch describe.

Co-Authored-By: Claude Opus 5 <[email protected]>

The caveats are largely this backport's concern, so they now live in
its own documentation (python/importlib_metadata@be2ea93bc), which this
module links to from the overview, from IDistribution, and from the
custom provider example. What stays here is the documentation of the
protocols themselves.

Co-Authored-By: Claude Opus 5 <[email protected]>