[jaraco]

Applies importlib_metadata 10.0 and documents the protocols it adds.

Sync

Lib/importlib/metadata/ picks up importlib_metadata 10.0
(python/importlib_metadata#505, for python/importlib_metadata#486):
IDistribution and IPackagePath protocols in _meta.py, both
@runtime_checkable, exported from importlib.metadata. The compat and
_compat packages, which hold localize and the warning it raises for a
provider's incomplete Distribution subclass, are excluded from the port as
usual, so only the protocols arrive here.

Documentation (gh-123976)

• Documents IDistribution and IPackagePath.
• Corrects the PackageMetadata entry, which described itself as "a concrete
  implementation of the PackageMetadata protocol" and linked to the backport's
  docs for the protocol. importlib.metadata._meta.PackageMetadata is itself a
  Protocol, and is exported in __all__.
• Links to the backport's new
  Caveats
  page from the overview's seealso, from IDistribution, and from the custom
  provider example.

The caveats themselves — the two class hierarchies, what the backport
substitutes and what it passes through unchanged, and what that asks of
consumers and of custom providers — now live in the backport's documentation
(python/importlib_metadata@be2ea93bc), the concern being largely the backport's
rather than the stdlib's.

🤖 Generated with Claude Code

• Issue: Sync with importlib_metadata for Python 3.16 #160386

[read-the-docs-community]

Documentation build overview

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

  🔍 Preview build  

160 files changed · ± 160 modified

± Modified

• glossary.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• c-api/bool.html
• c-api/buffer.html
• c-api/bytes.html
• c-api/code.html
• c-api/codec.html
• and 150 more...

[warsaw]

@jaraco While I think it's a worthy goal to enable type checks in a way that bridges the gap between the stdlib API and the backport API, I have some concerns about backward compatibility. Changing the types can potentially break existing code, so I had my agent help with an analysis.

The IPackagePath protocol is narrower than PackagePath objects. PackagePath is documented as a PurePath, and code like [f for f in files('pkg') if f.suffix == '.py'], or anything using name, stem, parent, match(), or /, would no longer type check against the new annotations once typeshed adopts the new types.

Both libraries' PackagePath derive from PurePosixPath, so the protocol could declare that interface (or at least the commonly used members) without weakening the cross-library guarantee. There's nothing public in pathlib to compose with: pathlib.types._JoinablePath is private, an ABC rather than a protocol, and absent before 3.14, so the members would need to be declared on IPackagePath directly. Since 10.0 has already shipped, this would presumably go to importlib_metadata first and then be synced here.

[warsaw]

This covers objects that came from files(), but a directly constructed PackagePath doesn't
satisfy the protocol:

>>> isinstance(PackagePath('foo.py'), IPackagePath)
False

hash, size, and dist are only set on instances in make_file(). The doctests on _get_toplevel_name(), now annotated IPackagePath, pass exactly such objects. Since the docs now steer users toward the protocols, it would be good to either give PackagePath class-level defaults for those attributes or note the limitation in the IPackagePath docs. A test for whichever behavior is intended would help too.

See my general comment below.

[bedevere-app]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.