PEP 794: Clarifications based on feedback (#4462)

Author: brettcannon

peps/pep-0794.rst

@@ -54,11 +54,7 @@ Rationale
 
 This PEP proposes extending the packaging :ref:`packaging:core-metadata` so
 that project owners can specify the highest-level import names that a project
-provides and owns if installed.
-
-By keeping the information to the import names a project would own if
-installed, it makes it clear which project maps directly to what import name
-once the project is installed.
+provides and owns if installed on some platform.
 
 Putting this metadata in the core metadata means the data is (potentially)
 served independently of any sdist or wheel by an index server. That negates
@@ -94,7 +90,9 @@ hosted by a central index server like PyPI. It also doesn't work for sdists
 as the structure of the wheel isn't known yet, and so inferring the structure
 of the code installed isn't known yet. As well, these solutions are not
 necessarily accurate as it is based on inference instead of being explicitly
-provided by the project owners.
+provided by the project owners. All of these accuracy issues affect even having
+an index hosting the information to avoid the compute costs of gathering the
+information.
 
 
 Specification
@@ -106,22 +104,22 @@ latest core metadata version to 2.5.
 The ``Import-Name`` field is a "multiple uses" field. Each entry of
 ``Import-Name`` MUST be a valid import name. The names specified in
 ``Import-Name`` MUST be importable when the project is installed on *some*
-platform for the same version of the project (i.e. the metadata MUST be
+platform for the same version of the project (e.g. the metadata MUST be
 consistent across all sdists and wheels for a project release). This does
 imply that the information isn't specific to the distribution artifact it is
 found in, but for the release version the distribution artifact belongs to.
 
-Projects are not expected to list every single import name that is provided.
+Projects are not required to list every single import name that is provided.
 Instead, projects SHOULD list the highest-level/shortest import name that the
-project would "own" when installed. For example, if you install a project
-that has a single package named ``myproj`` which itself has multiple
-submodules, the expectation is only ``myproj`` would be listed in
-``Import-Name`` and not every submodule. If a project is part of a namespace
-package named ``ns`` and it provides a subpackage called ``ns.myproj`` (i.e.
-``ns.myproj.__init__`` exists), then ``ns.myproj`` should be listed in
-``Import-Name``, but NOT ``ns`` alone as that is not "owned" by the project
-upon installation (i.e. other projects can be installed which also contribute to
-``ns``).
+project would "own" when installed (this includes "private" names). For
+example, if you install a project that has a single package named ``myproj``
+which itself has multiple submodules, the expectation is only ``myproj``
+would be listed in ``Import-Name`` and not every submodule. If a project is
+part of a namespace package named ``ns`` and it provides a subpackage called
+``ns.myproj`` (i.e. ``ns.myproj.__init__`` exists), then ``ns.myproj`` should
+be listed in ``Import-Name``, but NOT ``ns`` alone as that is not "owned" by
+the project upon installation (i.e. other projects can be installed which
+also contribute to ``ns``).
 
 If a project chooses not to provide any ``Import-Name`` entries, tools MAY
 assume the import name matches the project name (including de-normalization of
@@ -137,9 +135,9 @@ value on the user's behalf if desired, if the user declares the key in
 Examples
 --------
 
-`In httpx 0.28.1
-<https://pypi-browser.org/package/httpx/httpx-0.28.1-py3-none-any.whl>`__ ,
-an entry for the ``httpx`` package.
+`In scikit-learn 1.7.0
+<https://pypi-browser.org/package/scikit-learn/scikit_learn-1.7.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl>`__ ,
+an entry for the ``sklearn`` package would be used.
 
 `In pytest 8.3.5
 <https://pypi-browser.org/package/pytest/pytest-8.3.5-py3-none-any.whl>`__