From 8098433df67bbbb0503ca4a79821f5ce2918414e Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 5 Sep 2025 10:43:51 -0700 Subject: [PATCH] PEP 794: Weaken the suggestion to use a project's name when `Import-Name` isn't set --- peps/pep-0794.rst | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/peps/pep-0794.rst b/peps/pep-0794.rst index b8fa0bef002..062809b1c07 100644 --- a/peps/pep-0794.rst +++ b/peps/pep-0794.rst @@ -178,20 +178,6 @@ 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 -import name of the project to explicitly declare that the project's name -is also the import name. - Projects MAY set ``import-names`` an empty array and not set ``import-namespaces`` at all in a :file:`pyproject.toml` file (e.g. ``import-names = []``). To match this, projects MAY have an empty @@ -199,6 +185,21 @@ Projects MAY set ``import-names`` an empty array and not set import names, public or private (i.e. there are no Python modules of any kind in the distribution file). +Since projects MAY have no ``Import-Name`` metadata (either because the project +uses an older metadata version, or because it didn't specify any), then tools +have no information about what names the project provides. However, in practice +the majority of projects have their project name match what their import name +would be. As such, it is a reasonable assumption to make that a project name +that is normalized in some way to an import name (e.g. +``packaging.utils.canonicalize_name(name, validate=True).replace("-", "_")``) +can be used if some answer is needed. + +Projects MAY set ``import-names`` or ``import-namespaces`` -- as well as +``Import-Name`` or ``Import-Namespace``, respectively -- to an import name that +matches the project name (normalized or not) to explicitly declare that the +project's name is also the import name. + + Examples --------