gh-110937: Document full public importlib.metadata.Distribution API

[flying-sheep]

This PR documents the entire remainder of the importlib.metadata.Distribution API as described in #110937 (comment)

It lightly restructures the narrative documentation of the Distributions section so the whole thing flows into the class docs.

I also fixed a small issue with the signature of Distribution.discover, which wasn’t declared as .. classmethod, and added the (already documented) PackagePath class to importlib.metadata.__all__.

• Issue: importlib.metadata lacks reference documentation #110937

TODO:

• Which APIs were added in which Python version?

  Determined using this nushell script:

  ❯ ['3.8' '3.9' '3.10' '3.11' '3.12' '3.13' '3.14']
    | each { |v| { v: $v, ...(uvx -p $v --with=uv python -c '
  import json
  importlib.metadata as im
  d = im.distribution("uv")
  m = {attr: hasattr(d, attr) for attr in ("at", "from_name", "metadata", "name", "requires", "version", "origin", "entry_points", "files", "locate_file", "read_text")}
  print(json.dumps(m))'
    | from json) } }
  ╭───┬──────┬──────┬───────────┬──────────┬───────┬──────────┬─────────┬────────┬──────────────┬───────┬─────────────┬───────────╮
  │ # │  v   │  at  │ from_name │ metadata │ name  │ requires │ version │ origin │ entry_points │ files │ locate_file │ read_text │
  ├───┼──────┼──────┼───────────┼──────────┼───────┼──────────┼─────────┼────────┼──────────────┼───────┼─────────────┼───────────┤
  │ 0 │ 3.8  │ true │ true      │ true     │ false │ true     │ true    │ false  │ true         │ true  │ true        │ true      │
  │ 1 │ 3.9  │ true │ true      │ true     │ false │ true     │ true    │ false  │ true         │ true  │ true        │ true      │
  │ 2 │ 3.10 │ true │ true      │ true     │ true  │ true     │ true    │ false  │ true         │ true  │ true        │ true      │
  │ 3 │ 3.11 │ true │ true      │ true     │ true  │ true     │ true    │ false  │ true         │ true  │ true        │ true      │
  │ 4 │ 3.12 │ true │ true      │ true     │ true  │ true     │ true    │ false  │ true         │ true  │ true        │ true      │
  │ 5 │ 3.13 │ true │ true      │ true     │ true  │ true     │ true    │ true   │ true         │ true  │ true        │ true      │
  │ 6 │ 3.14 │ true │ true      │ true     │ true  │ true     │ true    │ true   │ true         │ true  │ true        │ true      │
  ╰───┴──────┴──────┴───────────┴──────────┴───────┴──────────┴─────────┴────────┴──────────────┴───────┴─────────────┴───────────╯

---

📚 Documentation preview 📚: https://cpython-previews--143480.org.readthedocs.build/en/143480/library/importlib.metadata.html

[jaraco]

LGTM. Thanks for doing this!

[jaraco]

We'll want to backport this change to importlib_metadata.

[flying-sheep]

Yeah, this is a public API so it should be explicitly exported.