gh-134740: Document distribution discovery in importlib.metadata

[emmatyping]

Document the following items listed in __all__ but missing from documentation:

• distributions(): mentioned in doc strings as well
• DistributionFinder: mentioned but didn't have it's own :class: entry
• DistributionFinder.Context: mentioned but didn't have it's own :class: entry)
• Distribution.discover(): mentioned in doc strings

• Issue: gh-134740

---

📚 Documentation preview 📚: https://cpython-previews--134751.org.readthedocs.build/

[emmatyping]

Closing as there's already #134749

[StanFromIreland]

It seems both were closed?

[emmatyping]

Yes, I will revive this one.

[flying-sheep]

Hi! @emmatyping you said in #110937 that this PR might close that issue.

I see you’re adding documentation for the discover class method. Do you plan to add Distribution’s remaining API in this PR (which is titled to be about discovery) or should that be in another PR?

The remaining methods/properties would be the other ones listed here: https://importlib-metadata.readthedocs.io/en/stable/api.html#importlib_metadata.Distribution

This includes 1. properties, of which metadata, version, and origin are partially and implicitly documented through code examples, but should be fully documented (what type do they have? origin has an url attribute, what else does it have?)

• metadata (and some related derived properies)
  • name
  • requires
  • version
• origin
• entry_points
• files

Also 2. abstract instance methods, which are also partially implicitly documented at the Example in the end, as they’re the abstract methods one needs to override when defining their own new Distribution

• locate_file
• read_text

And 3. two more class/static methods besides discover:

• at
• from_name

[emmatyping]

I see you’re adding documentation for the discover class method. Do you plan to add Distribution’s remaining API in this PR (which is titled to be about discovery) or should that be in another PR?

I can expand this PR

[abitrolly]

It is better to merge this, and then open new issues for undocumented things. What is missing, is the cookcook for the discovery API.

1. Check if package is installed
2. Get package version
3. Get packages version from virtualenv path
4. Get information about multiple packages in a single pass (not sure it is possible)

[abitrolly]

@emmatyping @flying-sheep @johnslavik can this PR be merged to get another iteration over the contents?

[flying-sheep]

In its current state, this PR doesn’t close #110937 yet, but that’s OK, the rest can for sure be done in another PR.

[abitrolly]

@flying-sheep think the PR aimed to document only the discovery part of #110937.

[flying-sheep]

yes, that’s why I asked above:

I see you’re adding documentation for the discover class method. Do you plan to add Distribution’s remaining API in this PR (which is titled to be about discovery) or should that be in another PR?

to which @emmatyping answered

I can expand this PR

which she didn’t end up doing. Which is fine! This PR should just be brought out of limbo one way or another.