@@ -15,11 +15,26 @@ API`_ and `metadata API`_ of ``pkg_resources``. Along with
1515this 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+
2338By default, distribution metadata can live on the file system
2439or in zip archives on
2540:data: `sys.path `. Through an extension mechanism, the metadata can live almost
0 commit comments