From 2e597d1ea1497b3336d8e818ca4bc05b54ff5299 Mon Sep 17 00:00:00 2001 From: Shamil Date: Mon, 26 May 2025 22:59:51 +0300 Subject: [PATCH] bpo-134740: Add missing documentation for importlib.metadata.distributions() Add documentation for the distributions() function, Distribution.discover() method, and DistributionFinder classes that were missing from the importlib.metadata documentation despite being part of the public API. --- Doc/library/importlib.metadata.rst | 57 ++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/Doc/library/importlib.metadata.rst b/Doc/library/importlib.metadata.rst index 12014309e26ec9..fa46afe20aed1f 100644 --- a/Doc/library/importlib.metadata.rst +++ b/Doc/library/importlib.metadata.rst @@ -410,6 +410,20 @@ Distributions Raises :exc:`PackageNotFoundError` if the named distribution package is not installed in the current Python environment. +.. function:: distributions(**kwargs) + + Get all :class:`Distribution` instances in the current environment. + + Any keyword arguments are passed to the ``find_distributions()`` method + of the registered distribution finders (see :class:`DistributionFinder`). + + Common keyword arguments include: + + * ``name``: Filter to distributions matching this package name + * ``path``: Search these path segments (defaults to :data:`sys.path`) + + :return: An iterable of :class:`Distribution` instances. + .. class:: Distribution Details of an installed distribution package. @@ -418,6 +432,47 @@ Distributions equal, even if they relate to the same installed distribution and accordingly have the same attributes. + .. classmethod:: discover(*, context=None, **kwargs) + + Return an iterable of Distribution objects for all packages. + + Pass a ``context`` or pass keyword arguments for constructing + a context. + + :param context: A :class:`DistributionFinder.Context` object. + :param kwargs: Context parameters used to construct a new context if one + is not supplied. + :return: Iterable of Distribution objects for packages matching + the context. + +.. class:: DistributionFinder + + An abstract base class subclass of :class:`importlib.abc.MetaPathFinder` + capable of discovering installed distributions. + + Custom providers should implement this interface to supply metadata + for distributions that cannot be discovered through the file system + or other built-in mechanisms. + + See the section on :ref:`implementing-custom-providers` for more details. + +.. class:: DistributionFinder.Context + + Context object used to provide parameters when discovering distributions. + + Keyword arguments supplied to :func:`distributions` or + :meth:`Distribution.discover` are stored as attributes in the context + object and can be used by distribution finders to filter or customize + their search results. + + The context provides these attributes: + + * ``name``: A package name to match, or ``None`` to match all distributions + * ``path``: A list of directories to search (defaults to :data:`sys.path`) + + Custom distribution finders can accept other keyword parameters through + this 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 @@ -467,6 +522,8 @@ This metadata finder search defaults to ``sys.path``, but varies slightly in how - ``importlib.metadata`` will incidentally honor :py:class:`pathlib.Path` objects on ``sys.path`` even though such values will be ignored for imports. +.. _implementing-custom-providers: + Implementing Custom Providers =============================