@@ -15,11 +15,26 @@ API`_ and `metadata API`_ of ``pkg_resources``. Along with
15
15
this package can eliminate the need to use the older and less efficient
16
16
``pkg_resources `` package.
17
17
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
+
23
38
By default, distribution metadata can live on the file system
24
39
or in zip archives on
25
40
:data: `sys.path `. Through an extension mechanism, the metadata can live almost
0 commit comments