gh-160386: Apply changes from importlib_metadata 10.0 and document the shared protocols - #160344

Applies the importlib_metadata 10.0 sync and documents the protocols it
introduces. These began as separate changes; they are combined here because
the documentation describes the protocols the sync adds, so neither reviews
well on its own.

The sync (gh-160386)

• Adds the IDistribution and IPackagePath protocols to
  Lib/importlib/metadata/_meta.py, and annotates the functions returning
  distributions and files with them, so a consumer can target one interface
  across this module and the backport rather than either library's concrete
  classes (API incompatibility with importlib.metadata (or at least the API is not type-safe?) importlib_metadata#486).
• Makes PackageMetadata @runtime_checkable, as the protocols are meant to
  be tested with isinstance.

The backport's compat and _compat packages are excluded from the port as
usual, so localize and the UserWarning it raises where a provider's class
omits a required member do not appear here; only the protocols they are
defined against do. That is why the caveats below describe that warning as the
backport's behavior rather than this module's.

Merged from python/importlib_metadata at the v10.0.0 tag rather than from
main, so this applies that release alone. 10.1.0 follows separately.

The documentation (gh-123976)

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.

Testing

./python.exe -m test test_importlib -m 'test.test_importlib.metadata.*'
passes: 102 tests, including the three new test_protocols tests. A full
test_importlib run on this build also shows 8 test_threaded_import
failures, which reproduce with these changes stashed and are unrelated to
importlib.metadata.

🤖 Generated with Claude Code