From cbd0408b54c8f9512bfeace2aaf9da064053e86d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Sun, 29 Dec 2019 18:26:35 +0100 Subject: [PATCH] links in importlib.metadata.rst replaced with sphinx references (GH-17730) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The importlib.metadata documentation uses hardcoded links to internal pages. This results in minor rendering issues. This change replaces the hardcoded links with suitable Sphinx roles. Signed-off-by: Oleg Höfling --- Doc/library/importlib.metadata.rst | 39 ++++++++++++------------------ Doc/reference/import.rst | 2 ++ Misc/ACKS | 1 + 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/Doc/library/importlib.metadata.rst b/Doc/library/importlib.metadata.rst index dc6b66ca384..15e58b860d9 100644 --- a/Doc/library/importlib.metadata.rst +++ b/Doc/library/importlib.metadata.rst @@ -1,8 +1,8 @@ .. _using: -========================== - Using importlib.metadata -========================== +================================= + Using :mod:`!importlib.metadata` +================================= .. note:: This functionality is provisional and may deviate from the usual @@ -12,8 +12,8 @@ package metadata. Built in part on Python's import system, this library intends to replace similar functionality in the `entry point API`_ and `metadata API`_ of ``pkg_resources``. Along with -``importlib.resources`` in `Python 3.7 -and newer`_ (backported as `importlib_resources`_ for older versions of +:mod:`importlib.resources` in Python 3.7 +and newer (backported as `importlib_resources`_ for older versions of Python), this can eliminate the need to use the older and less efficient ``pkg_resources`` package. @@ -21,9 +21,9 @@ By "installed package" we generally mean a third-party package installed into Python's ``site-packages`` directory via tools such as `pip `_. Specifically, it means a package with either a discoverable ``dist-info`` or ``egg-info`` -directory, and metadata defined by `PEP 566`_ or its older specifications. +directory, and metadata defined by :pep:`566` or its older specifications. By default, package metadata can live on the file system or in zip archives on -``sys.path``. Through an extension mechanism, the metadata can live almost +:data:`sys.path`. Through an extension mechanism, the metadata can live almost anywhere. @@ -134,7 +134,7 @@ Distribution files You can also get the full set of files contained within a distribution. The ``files()`` function takes a distribution package name and returns all of the files installed by this distribution. Each file object returned is a -``PackagePath``, a `pathlib.Path`_ derived object with additional ``dist``, +``PackagePath``, a :class:`pathlib.Path` derived object with additional ``dist``, ``size``, and ``hash`` properties as indicated by the metadata. For example:: >>> util = [p for p in files('wheel') if 'util.py' in str(p)][0] # doctest: +SKIP @@ -203,18 +203,18 @@ instance:: >>> d.metadata['License'] # doctest: +SKIP 'MIT' -The full set of available metadata is not described here. See `PEP 566 -`_ for additional details. +The full set of available metadata is not described here. See :pep:`566` +for additional details. Extending the search algorithm ============================== -Because package metadata is not available through ``sys.path`` searches, or +Because package metadata is not available through :data:`sys.path` searches, or package loaders directly, the metadata for a package is found through import -system `finders`_. To find a distribution package's metadata, -``importlib.metadata`` queries the list of `meta path finders`_ on -`sys.meta_path`_. +system :ref:`finders `. To find a distribution package's metadata, +``importlib.metadata`` queries the list of :term:`meta path finders ` on +:data:`sys.meta_path`. The default ``PathFinder`` for Python includes a hook that calls into ``importlib.metadata.MetadataPathFinder`` for finding distributions @@ -224,7 +224,7 @@ The abstract class :py:class:`importlib.abc.MetaPathFinder` defines the 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 -``sys.meta_path`` and presents this extended interface as the +:data:`sys.meta_path` and presents this extended interface as the ``DistributionFinder`` abstract base class, which defines this abstract method:: @@ -247,20 +247,13 @@ a custom finder, return instances of this derived ``Distribution`` in the .. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points .. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api -.. _`Python 3.7 and newer`: https://docs.python.org/3/library/importlib.html#module-importlib.resources .. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html -.. _`PEP 566`: https://www.python.org/dev/peps/pep-0566/ -.. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders -.. _`meta path finders`: https://docs.python.org/3/glossary.html#term-meta-path-finder -.. _`sys.meta_path`: https://docs.python.org/3/library/sys.html#sys.meta_path -.. _`pathlib.Path`: https://docs.python.org/3/library/pathlib.html#pathlib.Path .. rubric:: Footnotes .. [#f1] Technically, the returned distribution metadata object is an - `email.message.Message - `_ + :class:`email.message.EmailMessage` instance, but this is an implementation detail, and not part of the stable API. You should only use dictionary-like methods and syntax to access the metadata contents. diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index c95826305b6..20a2ea69e2d 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -202,6 +202,8 @@ named module, the two module objects will *not* be the same. By contrast, reinitialise the module contents by rerunning the module's code. +.. _finders-and-loaders: + Finders and loaders ------------------- diff --git a/Misc/ACKS b/Misc/ACKS index 8ab7a6cee5a..5ecbac13e0b 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -751,6 +751,7 @@ Ludwig Hähne Gerhard Häring Fredrik Håård Florian Höch +Oleg Höfling Robert Hölzl Catalin Iacob Mihai Ibanescu