Skip to content

Commit c9f2d6e

Browse files
committed
Add admonition further clarifying import vs distribution packages
1 parent 43233ab commit c9f2d6e

File tree

1 file changed

+20
-5
lines changed

1 file changed

+20
-5
lines changed

docs/using.rst

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,26 @@ API`_ and `metadata API`_ of ``pkg_resources``. Along with
1515
this package can eliminate the need to use the older and less efficient
1616
``pkg_resources`` package.
1717

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

0 commit comments

Comments
 (0)