8000 gh-134740: Document distribution discovery in importlib.metadata by emmatyping · Pull Request #134751 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-134740: Document distribution discovery in importlib.metadata #134751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

gh-134740: Document distribution discovery in importlib.metadata #134751

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e4d2f89
Document distribution discovery in importlib.metadata docs
emmatyping May 26, 2025
8f76e0e
Fix ref to MetaPathFinder
emmatyping May 26, 2025
435f5cc
Disambiguate path and name
emmatyping May 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 69 additions & 5 deletions Doc/library/importlib.metadata.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -418,6 +418,16 @@ Distributions
equal, even if they relate to the same installed distribution and
accordingly have the same attributes.

.. method:: discover(cls, *, context=None, **kwargs)

Returns an iterable of :class:`Distribution` instances for all packages.

The optional argument *context* is a :class:`DistributionFinder.Context`
instance, used to modify the search for distributions. Alternatively,
*kwargs* may contian keyword arguments for constructing a new
:class:`!DistributionFinder.Context`.


While the module level API described above is the most common and convenient usage,
you can get all of that information from the :class:`!Distribution` class.
:class:`!Distribution` is an abstract object that represents the metadata for
Expand Down Expand Up @@ -466,6 +476,58 @@ This metadata finder search defaults to ``sys.path``, but varies slightly in how
- ``importlib.metadata`` does not honor :class:`bytes` objects on ``sys.path``.
- ``importlib.metadata`` will incidentally honor :py:class:`pathlib.Path` objects on ``sys.path`` even though such values will be ignored for imports.

.. class:: DistributionFinder

A :class:`~importlib.abc.MetaPathFinder` subclass capable of discovering
installed distributions.

Custom providers should implement this interface in order to
supply metadata.

.. class:: Context(**kwargs)

A :class:`!Context` gives a custom provider a means to
solicit additional details from the callers of distribution discovery
functions like :func:`distributions` or :meth:`Distribution.discover`
beyond :attr:`!.name` and :attr:`!.path` when searching
for distributions.

For example, a provider could expose suites of packages in either a
"public" or "private" ``realm``. A caller of distribution discovery
functions may wish to query only for distributions in a particular realm
and could call ``distributions(realm="private")`` to signal to the
custom provider to only include distributions from that
realm.

Each :class:`!DistributionFinder` must expect any parameters and should
attempt to honor the canonical parameters defined below when
appropriate.

.. attribute:: name

Specific name for which a distribution finder should match.

A :attr:`!.name` of ``None`` matches all distributions.

.. attribute:: path

A property providing the sequence of directory paths that a
distribution finder should search.

Typically refers to Python installed package paths such as
"site-packages" directories and defaults to :attr:`sys.path`.


.. function:: distributions(**kwargs)

Returns an iterable of :class:`Distribution` instances for all packages.

The *kwargs* argument may contain either a keyword argument ``context``, a
:class:`DistributionFinder.Context` instance, or pass keyword arguments for
constructing a new :class:`!DistributionFinder.Context`. The
:class:`!DistributionFinder.Context` is used to modify the search for
distributions.


Implementing Custom Providers
=============================
Expand Down Expand Up @@ -493,7 +555,7 @@ interface expected of finders by Python's import system.
``importlib.metadata`` extends this protocol by looking for an optional
``find_distributions`` callable on the finders from
:data:`sys.meta_path` and presents this extended interface as the
``DistributionFinder`` abstract base class, which defines this abstract
:class:`DistributionFinder` abstract base class, which defines this abstract
method::

@abc.abstractmethod
Expand All @@ -502,9 +564,11 @@ method::
loading the metadata for packages for the indicated ``context``.
"""

The ``DistributionFinder.Context`` object provides ``.path`` and ``.name``
properties indicating the path to search and name to match and may
supply other relevant context sought by the consumer.
The :class:`DistributionFinder.Context` object provides
:attr:`~DistributionFinder.Context.path` and
:attr:`~DistributionFinder.Context.name` properties indicating the path to
search and name to match and may supply other relevant context sought by the
consumer.

In practice, to support finding distribution package
metadata in locations other than the file system, subclass
Expand All @@ -529,7 +593,7 @@ Imagine a custom finder that loads Python modules from a database::
That importer now presumably provides importable modules from a
database, but it provides no metadata or entry points. For this
custom importer to provide metadata, it would also need to implement
``DistributionFinder``::
:class:`DistributionFinder`::

from importlib.metadata import DistributionFinder

Expand Down
Loading
0