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.

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot ARM Raspbian 3.x (tier-3) has failed when building commit ae7fc4a.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/424/builds/12918) and take a look at the build logs.
4. Check if the failure is related to this commit (ae7fc4a) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/424/builds/12918

Failed tests:

• test.test_multiprocessing_fork.test_processes

Failed subtests:

• test_interrupt - test.test_multiprocessing_fork.test_processes.WithProcessesTestProcess.test_interrupt

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/contextlib.py", line 85, in inner
    return func(*args, **kwds)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 597, in test_interrupt
    exitcode = self._kill_process(multiprocessing.Process.interrupt)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/contextlib.py", line 85, in inner
    return func(*args, **kwds)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 578, in _kill_process
    self.assertEqual(join(), None)
                     ~~~~^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 251, in __call__
    return self.func(*args, **kwds)
           ~~~~~~~~~^^^^^^^^^^^^^^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/multiprocessing/process.py", line 156, in join
    res = self._popen.wait(timeout)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 44, in wait
    return self.poll(os.WNOHANG if timeout == 0.0 else 0)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 28, in poll
    pid, sts = os.waitpid(self.pid, flag)
               ~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 574, in handler
    raise RuntimeError('join took too long: %s' % p)
RuntimeError: join took too long: <Process name='Process-150' pid=15147 parent=14253 started daemon>


Traceback (most recent call last):
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/contextlib.py", line 85, in inner
    return func(*args, **kwds)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 597, in test_interrupt
    exitcode = self._kill_process(multiprocessing.Process.interrupt)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/contextlib.py", line 85, in inner
    return func(*args, **kwds)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 578, in _kill_process
    self.assertEqual(join(), None)
                     ~~~~^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 251, in __call__
    return self.func(*args, **kwds)
           ~~~~~~~~~^^^^^^^^^^^^^^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/multiprocessing/process.py", line 156, in join
    res = self._popen.wait(timeout)
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 44, in wait
    return self.poll(os.WNOHANG if timeout == 0.0 else 0)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 28, in poll
    pid, sts = os.waitpid(self.pid, flag)
               ~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "/var/lib/buildbot/workers/3.x.gps-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 574, in handler
    raise RuntimeError('join took too long: %s' % p)
RuntimeError: join took too long: <Process name='Process-1' pid=2871 parent=2869 started daemon>