From 7bfb17939b2fb99d5fa3e3b1a47a657c71f7d0cc Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 29 Jul 2025 11:56:37 -0700 Subject: [PATCH] PEP 794: address feedback --- peps/pep-0794.rst | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/peps/pep-0794.rst b/peps/pep-0794.rst index 41c23ec6db4..3709abbc493 100644 --- a/peps/pep-0794.rst +++ b/peps/pep-0794.rst @@ -46,10 +46,10 @@ names will become available once they install a project. There is also no easy way to know whether installing two projects will conflict with one another based on the import names they provide. For instance, if two -different projects have a ``_utils`` module, installing both project will lead +different projects have a ``_utils`` module, installing both projects will lead to a clash as one project's ``_utils`` module would take precedence over the -other project's version. This issue has been -`seen in the wild `__. +other project's version by overwriting the other project's file; this issue +has been `seen in the wild `__. It may also help with spam detection. If a project specifies the same import names as a very popular project it can act as a signal to take a closer look @@ -84,7 +84,7 @@ a specification that is somehow strict about what can be listed would be near impossible to get right due to how flexible Python's import system is. As such, this PEP only requires that valid import names be used and that projects don't lie (and it is acknowledged the latter requirements cannot be validated -programmatically). Project do, though, need to account for all levels of the +programmatically). Projects do, though, need to account for all levels of the names they list (e.g. you can't list ``a.b.c`` and not account for ``a`` and ``a.b``). @@ -98,7 +98,7 @@ read the table of contents of the zip file). This sort of calculation is also currently repeated by everyone independently instead of having the metadata 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 +of the code installed isn't possible. As well, these solutions are not necessarily accurate as it is based on inference instead of being explicitly 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 @@ -137,14 +137,13 @@ value on the user's behalf if desired, if the user declares the key in Projects SHOULD list all the shortest import names that are exclusively provided by a project which would cover all import name scenarios. If any of the shortest names are dotted names, all intervening names from that name to the top-level -name should also be listed appropriately in ``Import-Namespace``. -For instance, a project which is a single package named ``spam`` with multiple -submodules would only list ``project.import-names = ["spam"]``. A project that -provides ``spam.bacon.eggs`` which is exclusively from the project while the -intervening names are namespaces would have -``project-names = ["spam.bacon.eggs"]`` and -``project-namespaces = ["spam", "spam.bacon"]``. Listing all names acts as a -check that the intent of the import names is as expected. +name should also be listed appropriately in ``Import-Namespace`` and/or +``Import-Names``. For instance, a project which is a single package named +``spam`` with multiple submodules would only list +``project.import-names = ["spam"]``. A project that lists ``spam.bacon.eggs`` +would also need to account for ``spam`` and ``spam.bacon`` appropriately in +``project-names`` and ``project-namespaces``. Listing all names acts as a check +that the intent of the import names is as expected. Tools SHOULD raise an error when two projects that are to be installed list names that overlap in each others' ``Import-Name`` entries. This is to avoid @@ -152,14 +151,6 @@ projects unexpectedly shadowing another project's code. The same applies to when a project has an entry in ``Import-Name`` that overlaps with another project's ``Import-Namespace`` entries. -Tools SHOULD raise an error when an entry in ``Import-Name`` is higher than -``Import-Namespace`` in the same project, e.g. -``project.import-names = ["spam"]`` and -``project.import-namespaces = ["spam.bacon"]``. This is because if a project -exclusively owns a higher import name then that would mean it is impossible for -another project to install with the same import name found in ``Import-Name`` -in order to contribute to the namespace listed in ``Import-Namespace``. - Projects MAY leave ``Import-Name`` and ``Import-Namespace`` empty. In that instance, tools SHOULD assume that the normalized project name when converted to an import name would be an entry in ``Import-Name`` @@ -253,6 +244,17 @@ listing something that would be interpreted as an implicit namespace, but it also made the data more self-documenting. +Require that names listed in ``Import-Namespace`` never be contained by a name in ``Import-Name`` +------------------------------------------------------------------------------------------------- + +The way Python's import system works by default means that it isn't possible to +have an import name contain an namespace. But Python's import system is flexible +enough that user code could make that possible. As such, the requirement that +tools error out if an import name contained a namespace name -- +``import-names = ["spam"]`` and ``import-namespaces = ["spam.bacon"]`` -- was +removed. + + Re-purpose the ``Provides`` field ----------------------------------