Skip to content

PEP 794: Address comments #4571

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brettcannon merged 1 commit into from
Sep 2, 2025
Merged

PEP 794: Address comments #4571

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 22 additions & 13 deletions peps/pep-0794.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"]


Expand Down