Package Naming Convention and Issue 4766

[RogerMarsh]

setuptools version

setuptools==80.10.1

Python version

Python 3.14

OS

Microsoft Windows 10

Additional environment information

No response

Description

I have a package called dpt3.0-dptdb and while catching up to Python3.14 ran into a problem where wheel complains with a FileNotFoundError about a successfully built package. The existing build and install stuff, up to Python3.11 using older versions of build, setuptools, and wheel, continued to succeed.

The difference between success and failure turns out to be between setuptools-75.8.0 and setuptools-75.8.1 which involved 'Fix "Wheel naming is not following PEP 491 convention" #4766'.

The problem was first seen after 'py -3.14-32 -m pip install setuptools' installed version 80.10.1 on a fresh install.

The Python Packaging User Guide says distribution name can contain letters, numbers, ., _ , and -.

PEP 491 gives the pattern re.sub("[^\w\d.]+", "_", distribution, re.UNICODE) for escaping each component of the filename.

So I am expecting the '.' in 'dpt3.0-dptdb' to be retained, not replaced by '_'.

The script demonstrating this is at packaging-problem.txt.

Expected behavior

I expected the 'nmake -f v3r0_vs2017_c++14_py3-14_32.Nmakefile local-install' command to successfully install the package with both 75.8.0 and 75.8.1 versions of setuptools, and by implication the 80.10.1 version too.

How to Reproduce

I will create a minimal reproducer if I must. Assuming just the project name matters it would be created with Python 3.12 on OpenBSD, not the nmake stuff where I care.

Output

[abravalheri]

Hi @RogerMarsh, thanks for the report.

There are a couple of subtleties...

1. In terms of file names (e.g. the .whl), they will always be normalized because the file name is meant to be machine-parsed and the . and - characters are field separators.

2. What is likely to remain similar to the initial input is value of the Name: field in the METADATA file
   You can check if the value is consistent using something like this:

   unzip dist/<normalised_package_name>-<version>-<other_flags>.whl <normalised_package_name>-<version>.dist-info/METADATA

3. The up-to-date specs can be found in:

   • https://packaging.python.org/en/latest/specifications/binary-distribution-format/#escaping-and-unicode
   • https://packaging.python.org/en/latest/specifications/name-normalization/

   So the normalisation for the file naming should be something like: re.sub(r"[-_.]+", "-", name).lower().replace('-', '_')
   I can see in your logs that this normalisation seems to be respected:

   Successfully built dpt3_0_dptdb-1.0.0.tar.gz and dpt3_0_dptdb-1.0.0-py3-none-any.whl

---

Could you please provide what is the value stored inside the METADATA file inside the wheel distribution so we can check what is the behaviour setuptools is using?

[RogerMarsh]

The Name field is dpt3.0-dptdb.

Script attached in case other stuff in METADATA matters:

typescipt.txt

The name-normalization link led me to PEPs 503 and 508 both of which have bright blue boxes saying go look at PyPA specs page. The PEP 491 page, where I got the re expression I quoted, does not have that warning.

[abravalheri]

Hi @RogerMarsh, thank you very much for providing the info.
The Name: dpt3.0-dptdb in metadate seems to be confirming that setuptools seems to be preserving the given name, as intended.

As previously mentioned, when it comes to the file name, it should always be normalised given the most up to date spec, because it is meant for machine-parsing.

---

The name-normalization link led me to PEPs 503 and 508 both of which have bright blue boxes saying go look at PyPA specs page. The PEP 491 page, where I got the re expression I quoted, does not have that warning.

I see. The lack of a warning is possibly merely reflecting lack of human availability for tracing back all the documents that need updating and back-filling standards. In general Packaging-PEPs are historical documents that work as snapshots in time of the spec in the exact moment they were published. But because follow up PEPs can modify the standards, they don't work as the final source of information on the matter¹.

Lately the folks behind the https://packaging.python.org/en/latest/specifications/ website have been trying to compile the information in all the PEPs and consolidate the standards in their most up-to-date form. So this should be the first place to look for info. (But yeah, as any open source project, they have limited available human-power, so one or other document may not have been consolidated yet).

Please feel free to fire up an issue in https://github.com/python/peps/issues if you feel that the community would benefit for adding a warning about where to find the most up-to-date information in any historical PEP document.

---

Given that the file naming seems to be following the spec in https://packaging.python.org/en/latest/specifications/binary-distribution-format/#escaping-and-unicode, and that the Name: metadata field preserves the given package name, it seems to me that Setuptools is following the PyPA naming conventions.

Footnotes

1. That is the nature of PEPs: they pile up and overlapbits and pieces of each other. The living standard is the final compound effect of all of them. ↩

[abravalheri]

I will move this to the Discussions as it does not seem to me that setuptools has a pending action point on this matter.