Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 8af04cd

Browse filesBrowse files
jaracojaraco
authored
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.
1 parent 2b5f136 commit 8af04cd
Copy full SHA for 8af04cd

File tree

5 files changed

+88
-302
lines changed
Filter options

5 files changed

+88
-302
lines changed

‎Doc/library/importlib.metadata.rst

Copy file name to clipboardExpand all lines: Doc/library/importlib.metadata.rst
+73-35Lines changed: 73 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,39 @@
1313

1414
**Source code:** :source:`Lib/importlib/metadata/__init__.py`
1515

16-
``importlib.metadata`` is a library that provides access to installed
17-
package metadata, such as its entry points or its
18-
top-level name. Built in part on Python's import system, this library
16+
``importlib_metadata`` is a library that provides access to
17+
the metadata of an installed `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
18+
such as its entry points
19+
or its top-level names (`Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_\s, modules, if any).
20+
Built in part on Python's import system, this library
1921
intends to replace similar functionality in the `entry point
2022
API`_ and `metadata API`_ of ``pkg_resources``. Along with
2123
:mod:`importlib.resources`,
2224
this package can eliminate the need to use the older and less efficient
2325
``pkg_resources`` package.
2426

25-
By "installed package" we generally mean a third-party package installed into
26-
Python's ``site-packages`` directory via tools such as `pip
27-
<https://pypi.org/project/pip/>`_. Specifically,
28-
it means a package with either a discoverable ``dist-info`` or ``egg-info``
29-
directory, and metadata defined by :pep:`566` or its older specifications.
30-
By default, package metadata can live on the file system or in zip archives on
27+
``importlib_metadata`` operates on third-party *distribution packages*
28+
installed into Python's ``site-packages`` directory via tools such as
29+
`pip <https://pypi.org/project/pip/>`_.
30+
Specifically, it works with distributions with discoverable
31+
``dist-info`` or ``egg-info`` directories,
32+
and metadata defined by the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_.
33+
34+
.. important::
35+
36+
These are *not* necessarily equivalent to or correspond 1:1 with
37+
the top-level *import package* names
38+
that can be imported inside Python code.
39+
One *distribution package* can contain multiple *import packages*
40+
(and single modules),
41+
and one top-level *import package*
42+
may map to multiple *distribution packages*
43+
if it is a namespace package.
44+
You can use :ref:`package_distributions() <package-distributions>`
45+
to get a mapping between them.
46+
47+
By default, distribution metadata can live on the file system
48+
or in zip archives on
3149
:data:`sys.path`. Through an extension mechanism, the metadata can live almost
3250
anywhere.
3351

@@ -37,12 +55,19 @@ anywhere.
3755
https://importlib-metadata.readthedocs.io/
3856
The documentation for ``importlib_metadata``, which supplies a
3957
backport of ``importlib.metadata``.
58+
This includes an `API reference
59+
<https://importlib-metadata.readthedocs.io/en/latest/api.html>`__
60+
for this module's classes and functions,
61+
as well as a `migration guide
62+
<https://importlib-metadata.readthedocs.io/en/latest/migration.html>`__
63+
for existing users of ``pkg_resources``.
4064

4165

4266
Overview
4367
========
4468

45-
Let's say you wanted to get the version string for a package you've installed
69+
Let's say you wanted to get the version string for a
70+
`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ you've installed
4671
using ``pip``. We start by creating a virtual environment and installing
4772
something into it:
4873

@@ -151,19 +176,19 @@ for more information on entry points, their definition, and usage.
151176
The "selectable" entry points were introduced in ``importlib_metadata``
152177
3.6 and Python 3.10. Prior to those changes, ``entry_points`` accepted
153178
no parameters and always returned a dictionary of entry points, keyed
154-
by group. For compatibility, if no parameters are passed to entry_points,
155-
a ``SelectableGroups`` object is returned, implementing that dict
156-
interface. In the future, calling ``entry_points`` with no parameters
157-
will return an ``EntryPoints`` object. Users should rely on the selection
158-
interface to retrieve entry points by group.
179+
by group. With ``importlib_metadata`` 5.0 and Python 3.12,
180+
``entry_points`` always returns an ``EntryPoints`` object. See
181+
`backports.entry_points_selectable <https://pypi.org/project/backports.entry_points_selectable>`_
182+
for compatibility options.
159183

160184

161185
.. _metadata:
162186

163187
Distribution metadata
164188
---------------------
165189

166-
Every distribution includes some metadata, which you can extract using the
190+
Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ includes some metadata,
191+
which you can extract using the
167192
``metadata()`` function::
168193

169194
>>> wheel_metadata = metadata('wheel') # doctest: +SKIP
@@ -201,7 +226,8 @@ all the metadata in a JSON-compatible form per :PEP:`566`::
201226
Distribution versions
202227
---------------------
203228

204-
The ``version()`` function is the quickest way to get a distribution's version
229+
The ``version()`` function is the quickest way to get a
230+
`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_'s version
205231
number, as a string::
206232

207233
>>> version('wheel') # doctest: +SKIP
@@ -214,7 +240,8 @@ Distribution files
214240
------------------
215241

216242
You can also get the full set of files contained within a distribution. The
217-
``files()`` function takes a distribution package name and returns all of the
243+
``files()`` function takes a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ name
244+
and returns all of the
218245
files installed by this distribution. Each file object returned is a
219246
``PackagePath``, a :class:`pathlib.PurePath` derived object with additional ``dist``,
220247
``size``, and ``hash`` properties as indicated by the metadata. For example::
@@ -259,19 +286,24 @@ distribution is not known to have the metadata present.
259286
Distribution requirements
260287
-------------------------
261288

262-
To get the full set of requirements for a distribution, use the ``requires()``
289+
To get the full set of requirements for a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
290+
use the ``requires()``
263291
function::
264292

265293
>>> requires('wheel') # doctest: +SKIP
266294
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]
267295

268296

269-
Package distributions
270-
---------------------
297+
.. _package-distributions:
298+
.. _import-distribution-package-mapping:
299+
300+
Mapping import to distribution packages
301+
---------------------------------------
271302

272-
A convenience method to resolve the distribution or
273-
distributions (in the case of a namespace package) for top-level
274-
Python packages or modules::
303+
A convenience method to resolve the `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
304+
name (or names, in the case of a namespace package)
305+
that provide each importable top-level
306+
Python module or `Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_::
275307

276308
>>> packages_distributions()
277309
{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}
@@ -285,7 +317,8 @@ Distributions
285317

286318
While the above API is the most common and convenient usage, you can get all
287319
of that information from the ``Distribution`` class. A ``Distribution`` is an
288-
abstract object that represents the metadata for a Python package. You can
320+
abstract object that represents the metadata for
321+
a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_. You can
289322
get the ``Distribution`` instance::
290323

291324
>>> from importlib.metadata import distribution # doctest: +SKIP
@@ -305,14 +338,16 @@ instance::
305338
>>> dist.metadata['License'] # doctest: +SKIP
306339
'MIT'
307340

308-
The full set of available metadata is not described here. See :pep:`566`
309-
for additional details.
341+
The full set of available metadata is not described here.
342+
See the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
310343

311344

312345
Distribution Discovery
313346
======================
314347

315-
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:
348+
By default, this package provides built-in support for discovery of metadata
349+
for file system and zip file `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_\s.
350+
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:
316351

317352
- ``importlib.metadata`` does not honor :class:`bytes` objects on ``sys.path``.
318353
- ``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
321356
Extending the search algorithm
322357
==============================
323358

324-
Because package metadata is not available through :data:`sys.path` searches, or
325-
package loaders directly, the metadata for a package is found through import
326-
system :ref:`finders <finders-and-loaders>`. To find a distribution package's metadata,
359+
Because `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ metadata
360+
is not available through :data:`sys.path` searches, or
361+
package loaders directly,
362+
the metadata for a distribution is found through import
363+
system `finders`_. To find a distribution package's metadata,
327364
``importlib.metadata`` queries the list of :term:`meta path finders <meta path finder>` on
328365
:data:`sys.meta_path`.
329366

330-
The default ``PathFinder`` for Python includes a hook that calls into
331-
``importlib.metadata.MetadataPathFinder`` for finding distributions
332-
loaded from typical file-system-based paths.
367+
By default ``importlib_metadata`` installs a finder for distribution packages
368+
found on the file system.
369+
This finder doesn't actually find any *distributions*,
370+
but it can find their metadata.
333371

334372
The abstract class :py:class:`importlib.abc.MetaPathFinder` defines the
335373
interface expected of finders by Python's import system.
@@ -358,4 +396,4 @@ a custom finder, return instances of this derived ``Distribution`` in the
358396

359397
.. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
360398
.. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api
361-
.. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html
399+
.. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.