diff --git a/peps/pep-0794.rst b/peps/pep-0794.rst index 748c20eb36e..b8fa0bef002 100644 --- a/peps/pep-0794.rst +++ b/peps/pep-0794.rst @@ -165,20 +165,27 @@ If a project lists the same name in both ``Import-Name`` and ``Import-Namespace``, then tools MUST raise an error due to ambiguity; this also applies to ``import-names`` and ``import-namespaces``, respectively. -Tools SHOULD raise an error when two projects that are to be installed list -names that overlap in each other's ``Import-Name`` entries. This is to avoid -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 +Tools SHOULD raise an error when two projects that are about to be installed by +a tool list names that overlap in each other's ``Import-Name`` entries (i.e. +installed in the same command/action). This is to avoid 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. This does not apply to overlapping -``Import-Namespace`` entries as that's the purpose of namespace packages. - -Projects MAY leave ``Import-Name`` and ``Import-Namespace`` out of the core -metadata for a project. In that instance, tools SHOULD assume that when the -core metadata is 2.5 or newer, the normalized project name, when converted to -an import name, would be an entry in ``Import-Name`` (i.e. ``-`` replaced with -``_`` in the normalized project name). This is deemed reasonable as this will -only occur for projects that make a new release once their build back-end -supports core metadata 2.5 or newer as proposed by this PEP. +``Import-Namespace`` entries as that's the purpose of namespace packages. Tools +MAY warn or raise an error when installing a project into a preexisting +environment where there is import name overlap with a project that is already +installed. This is a "MAY" and not a "SHOULD" due to some users purposefully +overwriting import names when installation is done in multiple steps (e.g. +using different installers with the same environment). + +Tools MAY leave ``Import-Name`` and ``Import-Namespace`` out of the core +metadata for a project. In that instance, tools consuming such metadata SHOULD +assume that when the core metadata is 2.5 or newer, the normalized project name, +when converted to an import name, would be an entry in ``Import-Name`` (i.e. +``-`` replaced with ``_`` in the normalized project name). This is deemed +reasonable as this will only occur for projects that make a new release once +their build back-end supports core metadata 2.5 or newer as proposed by this +PEP. Projects MAY set ``import-names`` or ``import-namespaces`` -- as well as ``Import-Name`` or ``Import-Namespace``, respectively -- to the normalized @@ -211,6 +218,8 @@ there would be 3 expected entries: .. code-block:: TOML [project] + # The pytest docs list code out of all of these modules, so it isn't + # obvious whether they would mark any as private. import-names = ["_pytest", "py", "pytest"]