mirror of
https://github.com/python/cpython.git
synced 2025-08-01 15:43:13 +00:00
gh-97781: Apply changes from importlib_metadata 5. (GH-97785)
* gh-97781: Apply changes from importlib_metadata 5. * Apply changes from upstream * Apply changes from upstream.
This commit is contained in:
Jason R. Coombs
GitHub
parent
2b5f1360ea
commit
8af04cdef2
5 changed files with 88 additions and 302 deletions
|
|
@ -13,21 +13,39 @@
|
|||
|
||||
**Source code:** :source:`Lib/importlib/metadata/__init__.py`
|
||||
|
||||
``importlib.metadata`` is a library that provides access to installed
|
||||
package metadata, such as its entry points or its
|
||||
top-level name. Built in part on Python's import system, this library
|
||||
``importlib_metadata`` is a library that provides access to
|
||||
the metadata of an installed `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
|
||||
such as its entry points
|
||||
or its top-level names (`Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_\s, modules, if any).
|
||||
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
|
||||
:mod:`importlib.resources`,
|
||||
this package can eliminate the need to use the older and less efficient
|
||||
``pkg_resources`` package.
|
||||
|
||||
By "installed package" we generally mean a third-party package installed into
|
||||
Python's ``site-packages`` directory via tools such as `pip
|
||||
<https://pypi.org/project/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.
|
||||
By default, package metadata can live on the file system or in zip archives on
|
||||
``importlib_metadata`` operates on third-party *distribution packages*
|
||||
installed into Python's ``site-packages`` directory via tools such as
|
||||
`pip <https://pypi.org/project/pip/>`_.
|
||||
Specifically, it works with distributions with discoverable
|
||||
``dist-info`` or ``egg-info`` directories,
|
||||
and metadata defined by the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_.
|
||||
|
||||
.. important::
|
||||
|
||||
These are *not* necessarily equivalent to or correspond 1:1 with
|
||||
the top-level *import package* names
|
||||
that can be imported inside Python code.
|
||||
One *distribution package* can contain multiple *import packages*
|
||||
(and single modules),
|
||||
and one top-level *import package*
|
||||
may map to multiple *distribution packages*
|
||||
if it is a namespace package.
|
||||
You can use :ref:`package_distributions() <package-distributions>`
|
||||
to get a mapping between them.
|
||||
|
||||
By default, distribution metadata can live on the file system
|
||||
or in zip archives on
|
||||
:data:`sys.path`. Through an extension mechanism, the metadata can live almost
|
||||
anywhere.
|
||||
|
||||
|
|
@ -37,12 +55,19 @@ anywhere.
|
|||
https://importlib-metadata.readthedocs.io/
|
||||
The documentation for ``importlib_metadata``, which supplies a
|
||||
backport of ``importlib.metadata``.
|
||||
This includes an `API reference
|
||||
<https://importlib-metadata.readthedocs.io/en/latest/api.html>`__
|
||||
for this module's classes and functions,
|
||||
as well as a `migration guide
|
||||
<https://importlib-metadata.readthedocs.io/en/latest/migration.html>`__
|
||||
for existing users of ``pkg_resources``.
|
||||
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
Let's say you wanted to get the version string for a package you've installed
|
||||
Let's say you wanted to get the version string for a
|
||||
`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ you've installed
|
||||
using ``pip``. We start by creating a virtual environment and installing
|
||||
something into it:
|
||||
|
||||
|
|
@ -151,11 +176,10 @@ for more information on entry points, their definition, and usage.
|
|||
The "selectable" entry points were introduced in ``importlib_metadata``
|
||||
3.6 and Python 3.10. Prior to those changes, ``entry_points`` accepted
|
||||
no parameters and always returned a dictionary of entry points, keyed
|
||||
by group. For compatibility, if no parameters are passed to entry_points,
|
||||
a ``SelectableGroups`` object is returned, implementing that dict
|
||||
interface. In the future, calling ``entry_points`` with no parameters
|
||||
will return an ``EntryPoints`` object. Users should rely on the selection
|
||||
interface to retrieve entry points by group.
|
||||
by group. With ``importlib_metadata`` 5.0 and Python 3.12,
|
||||
``entry_points`` always returns an ``EntryPoints`` object. See
|
||||
`backports.entry_points_selectable <https://pypi.org/project/backports.entry_points_selectable>`_
|
||||
for compatibility options.
|
||||
|
||||
|
||||
.. _metadata:
|
||||
|
|
@ -163,7 +187,8 @@ interface to retrieve entry points by group.
|
|||
Distribution metadata
|
||||
---------------------
|
||||
|
||||
Every distribution includes some metadata, which you can extract using the
|
||||
Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ includes some metadata,
|
||||
which you can extract using the
|
||||
``metadata()`` function::
|
||||
|
||||
>>> wheel_metadata = metadata('wheel') # doctest: +SKIP
|
||||
|
|
@ -201,7 +226,8 @@ all the metadata in a JSON-compatible form per :PEP:`566`::
|
|||
Distribution versions
|
||||
---------------------
|
||||
|
||||
The ``version()`` function is the quickest way to get a distribution's version
|
||||
The ``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::
|
||||
|
||||
>>> version('wheel') # doctest: +SKIP
|
||||
|
|
@ -214,7 +240,8 @@ 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()`` 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::
|
||||
|
|
@ -259,19 +286,24 @@ distribution is not known to have the metadata present.
|
|||
Distribution requirements
|
||||
-------------------------
|
||||
|
||||
To get the full set of requirements for a distribution, use the ``requires()``
|
||||
To get the full set of requirements for a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
|
||||
use the ``requires()``
|
||||
function::
|
||||
|
||||
>>> requires('wheel') # doctest: +SKIP
|
||||
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]
|
||||
|
||||
|
||||
Package distributions
|
||||
---------------------
|
||||
.. _package-distributions:
|
||||
.. _import-distribution-package-mapping:
|
||||
|
||||
A convenience method to resolve the distribution or
|
||||
distributions (in the case of a namespace package) for top-level
|
||||
Python packages or modules::
|
||||
Mapping import to distribution packages
|
||||
---------------------------------------
|
||||
|
||||
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
|
||||
Python module or `Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_::
|
||||
|
||||
>>> packages_distributions()
|
||||
{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}
|
||||
|
|
@ -285,7 +317,8 @@ 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 package. You can
|
||||
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::
|
||||
|
||||
>>> from importlib.metadata import distribution # doctest: +SKIP
|
||||
|
|
@ -305,14 +338,16 @@ instance::
|
|||
>>> dist.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 the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
|
||||
|
||||
|
||||
Distribution Discovery
|
||||
======================
|
||||
|
||||
By default, this package provides built-in support for discovery of metadata for file system and zip file packages. This metadata finder search defaults to ``sys.path``, but varies slightly in how it interprets those values from how other import machinery does. In particular:
|
||||
By default, this package provides built-in support for discovery of metadata
|
||||
for file system and zip file `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_\s.
|
||||
This metadata finder search defaults to ``sys.path``, but varies slightly in how it interprets those values from how other import machinery does. In particular:
|
||||
|
||||
- ``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.
|
||||
|
|
@ -321,15 +356,18 @@ By default, this package provides built-in support for discovery of metadata for
|
|||
Extending the search algorithm
|
||||
==============================
|
||||
|
||||
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 :ref:`finders <finders-and-loaders>`. To find a distribution package's metadata,
|
||||
Because `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ metadata
|
||||
is not available through :data:`sys.path` searches, or
|
||||
package loaders directly,
|
||||
the metadata for a distribution is found through import
|
||||
system `finders`_. To find a distribution package's metadata,
|
||||
``importlib.metadata`` queries the list of :term:`meta path finders <meta path finder>` on
|
||||
:data:`sys.meta_path`.
|
||||
|
||||
The default ``PathFinder`` for Python includes a hook that calls into
|
||||
``importlib.metadata.MetadataPathFinder`` for finding distributions
|
||||
loaded from typical file-system-based paths.
|
||||
By default ``importlib_metadata`` installs a finder for distribution packages
|
||||
found on the file system.
|
||||
This finder doesn't actually find any *distributions*,
|
||||
but it can find their metadata.
|
||||
|
||||
The abstract class :py:class:`importlib.abc.MetaPathFinder` defines the
|
||||
interface expected of finders by Python's import system.
|
||||
|
|
@ -358,4 +396,4 @@ 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
|
||||
.. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html
|
||||
.. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue