gh-125018: Add importlib.metadata semantic link targets (#125027)

This allows direct intersphinx references to APIs via references
like `` :func:`importlib.metadata.version` ``.

---------

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

1 files changed, 144 insertions, 44 deletions

diff --git a/Doc/library/importlib.metadata.rst b/Doc/library/importlib.metadata.rst
index 66ba621..ddb7278 100644
--- a/Doc/library/importlib.metadata.rst
+++ b/Doc/library/importlib.metadata.rst
@@ -100,6 +100,13 @@ You can also get a :ref:`distribution's version number <version>`, list its
 :ref:`requirements`.
 
 
+.. exception:: PackageNotFoundError
+
+   Subclass of :class:`ModuleNotFoundError` raised by several functions in this
+   module when queried for a distribution package which is not installed in the
+   current Python environment.
+
+
 Functional API
 ==============
 
@@ -111,31 +118,53 @@ This package provides the following functionality via its public API.
 Entry points
 ------------
 
-The ``entry_points()`` function returns a collection of entry points.
-Entry points are represented by ``EntryPoint`` instances;
-each ``EntryPoint`` has a ``.name``, ``.group``, and ``.value`` attributes and
-a ``.load()`` method to resolve the value. There are also ``.module``,
-``.attr``, and ``.extras`` attributes for getting the components of the
-``.value`` attribute.
+.. function:: entry_points(**select_params)
+
+   Returns a :class:`EntryPoints` instance describing entry points for the
+   current environment. Any given keyword parameters are passed to the
+   :meth:`!~EntryPoints.select` method for comparison to the attributes of
+   the individual entry point definitions.
+
+   Note: it is not currently possible to query for entry points based on
+   their :attr:`!EntryPoint.dist` attribute (as different :class:`!Distribution`
+   instances do not currently compare equal, even if they have the same attributes)
+
+.. class:: EntryPoints
+
+   Details of a collection of installed entry points.
+
+   Also provides a ``.groups`` attribute that reports all identifed entry
+   point groups, and a ``.names`` attribute that reports all identified entry
+   point names.
+
+.. class:: EntryPoint
+
+   Details of an installed entry point.
+
+   Each :class:`!EntryPoint` instance has ``.name``, ``.group``, and ``.value``
+   attributes and a ``.load()`` method to resolve the value. There are also
+   ``.module``, ``.attr``, and ``.extras`` attributes for getting the
+   components of the ``.value`` attribute, and ``.dist`` for obtaining
+   information regarding the distribution package that provides the entry point.
 
 Query all entry points::
 
     >>> eps = entry_points()  # doctest: +SKIP
 
-The ``entry_points()`` function returns an ``EntryPoints`` object,
-a collection of all ``EntryPoint`` objects with ``names`` and ``groups``
+The :func:`!entry_points` function returns a :class:`!EntryPoints` object,
+a collection of all :class:`!EntryPoint` objects with ``names`` and ``groups``
 attributes for convenience::
 
     >>> sorted(eps.groups)  # doctest: +SKIP
     ['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
 
-``EntryPoints`` has a ``select`` method to select entry points
+:class:`!EntryPoints` has a :meth:`!~EntryPoints.select` method to select entry points
 matching specific properties. Select entry points in the
 ``console_scripts`` group::
 
     >>> scripts = eps.select(group='console_scripts')  # doctest: +SKIP
 
-Equivalently, since ``entry_points`` passes keyword arguments
+Equivalently, since :func:`!entry_points` passes keyword arguments
 through to select::
 
     >>> scripts = entry_points(group='console_scripts')  # doctest: +SKIP
@@ -189,31 +218,41 @@ for more information on entry points, their definition, and usage.
 Distribution metadata
 ---------------------
 
-Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ includes some metadata,
-which you can extract using the
-``metadata()`` function::
+.. function:: metadata(distribution_name)
+
+   Return the distribution metadata corresponding to the named
+   distribution package as a :class:`PackageMetadata` instance.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+.. class:: PackageMetadata
+
+   A concrete implementation of the
+    `PackageMetadata protocol <https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata>`_.
+
+    In addition to providing the defined protocol methods and attributes, subscripting
+    the instance is equivalent to calling the :meth:`!~PackageMetadata.get` method.
+
+Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
+includes some metadata, which you can extract using the :func:`!metadata` function::
 
     >>> wheel_metadata = metadata('wheel')  # doctest: +SKIP
 
-The keys of the returned data structure, a ``PackageMetadata``,
-name the metadata keywords, and
+The keys of the returned data structure name the metadata keywords, and
 the values are returned unparsed from the distribution metadata::
 
     >>> wheel_metadata['Requires-Python']  # doctest: +SKIP
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
 
-``PackageMetadata`` also presents a ``json`` attribute that returns
+:class:`PackageMetadata` also presents a :attr:`!~PackageMetadata.json` attribute that returns
 all the metadata in a JSON-compatible form per :PEP:`566`::
 
     >>> wheel_metadata.json['requires_python']
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
 
-.. note::
-
-    The actual type of the object returned by ``metadata()`` is an
-    implementation detail and should be accessed only through the interface
-    described by the
-    `PackageMetadata protocol <https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata>`_.
+The full set of available metadata is not described here.
+See the PyPA `Core metadata specification <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
 
 .. versionchanged:: 3.10
    The ``Description`` is now included in the metadata when presented
@@ -227,7 +266,15 @@ all the metadata in a JSON-compatible form per :PEP:`566`::
 Distribution versions
 ---------------------
 
-The ``version()`` function is the quickest way to get a
+.. function:: version(distribution_name)
+
+   Return the installed distribution package version for the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+The :func:`!version` function is the quickest way to get a
 `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_'s version
 number, as a string::
 
@@ -240,12 +287,28 @@ number, as a string::
 Distribution files
 ------------------
 
-You can also get the full set of files contained within a distribution. The
-``files()`` function takes a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ name
-and returns all of the
-files installed by this distribution. Each file object returned is a
-``PackagePath``, a :class:`pathlib.PurePath` derived object with additional ``dist``,
-``size``, and ``hash`` properties as indicated by the metadata. For example::
+.. function:: files(distribution_name)
+
+   Return the full set of files contained within the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+   Returns :const:`None` if the distribution is found but the installation
+   database records reporting the files associated with the distribuion package
+   are missing.
+
+.. class:: PackagePath
+
+    A :class:`pathlib.PurePath` derived object with additional ``dist``,
+    ``size``, and ``hash`` properties corresponding to the distribution
+    package's installation metadata for that file.
+
+The :func:`!files` function takes a
+`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
+name and returns all of the files installed by this distribution. Each file is reported
+as a :class:`PackagePath` instance. For example::
 
     >>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]  # doctest: +SKIP
     >>> util  # doctest: +SKIP
@@ -268,16 +331,16 @@ Once you have the file, you can also read its contents::
             return s.encode('utf-8')
         return s
 
-You can also use the ``locate`` method to get a the absolute path to the
-file::
+You can also use the :meth:`!~PackagePath.locate` method to get the absolute
+path to the file::
 
     >>> util.locate()  # doctest: +SKIP
     PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')
 
 In the case where the metadata file listing files
-(RECORD or SOURCES.txt) is missing, ``files()`` will
-return ``None``. The caller may wish to wrap calls to
-``files()`` in `always_iterable
+(``RECORD`` or ``SOURCES.txt``) is missing, :func:`!files` will
+return :const:`None`. The caller may wish to wrap calls to
+:func:`!files` in `always_iterable
 <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable>`_
 or otherwise guard against this condition if the target
 distribution is not known to have the metadata present.
@@ -287,8 +350,16 @@ distribution is not known to have the metadata present.
 Distribution requirements
 -------------------------
 
+.. function:: requires(distribution_name)
+
+   Return the declared dependency specifiers for the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
 To get the full set of requirements for a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
-use the ``requires()``
+use the :func:`!requires`
 function::
 
     >>> requires('wheel')  # doctest: +SKIP
@@ -301,6 +372,16 @@ function::
 Mapping import to distribution packages
 ---------------------------------------
 
+.. function:: packages_distributions()
+
+   Return a mapping from the top level module and import package
+   names found via :attr:`sys.meta_path` to the names of the distribution
+   packages (if any) that provide the corresponding files.
+
+   To allow for namespace packages (which may have members provided by
+   multiple distribution packages), each top level import name maps to a
+   list of distribution names rather than mapping directly to a single name.
+
 A convenience method to resolve the `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
 name (or names, in the case of a namespace package)
 that provide each importable top-level
@@ -320,23 +401,42 @@ function is not reliable with such installs.
 Distributions
 =============
 
-While the above API is the most common and convenient usage, you can get all
-of that information from the ``Distribution`` class. A ``Distribution`` is an
-abstract object that represents the metadata for
-a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_. You can
-get the ``Distribution`` instance::
+.. function:: distribution(distribution_name)
+
+   Return a :class:`Distribution` instance describing the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+.. class:: Distribution
+
+   Details of an installed distribution package.
+
+   Note: different :class:`!Distribution` instances do not currently compare
+   equal, even if they relate to the same installed distribution and
+   accordingly have the same attributes.
+
+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
+a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_.
+You can get the concreate :class:`!Distribution` subclass instance for an installed
+distribution package by calling the :func:`distribution` function::
 
     >>> from importlib.metadata import distribution  # doctest: +SKIP
     >>> dist = distribution('wheel')  # doctest: +SKIP
+    >>> type(dist)  # doctest: +SKIP
+    <class 'importlib.metadata.PathDistribution'>
 
 Thus, an alternative way to get the version number is through the
-``Distribution`` instance::
+:class:`!Distribution` instance::
 
     >>> dist.version  # doctest: +SKIP
     '0.32.3'
 
-There are all kinds of additional metadata available on the ``Distribution``
-instance::
+There are all kinds of additional metadata available on :class:`!Distribution`
+instances::
 
     >>> dist.metadata['Requires-Python']  # doctest: +SKIP
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
@@ -350,7 +450,7 @@ metadata::
     'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'
 
 The full set of available metadata is not described here.
-See the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
+See the PyPA `Core metadata specification <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
 
 .. versionadded:: 3.13
    The ``.origin`` property was added.