Repository navigation
Package Naming Convention and Issue 4766 #5156
Description
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.
Activity
abravalheri commentedon Jan 22, 2026
Hi @RogerMarsh, thanks for the report.
There are a couple of subtleties...
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.What is likely to remain similar to the initial input is value of the
Name:field in theMETADATAfileYou can check if the value is consistent using something like this:
The up-to-date specs can be found in:
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.whlCould you please provide what is the value stored inside the
METADATAfile inside the wheel distribution so we can check what is the behaviour setuptools is using?RogerMarsh commentedon Jan 22, 2026
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 commentedon Jan 22, 2026
Hi @RogerMarsh, thank you very much for providing the info.
The
Name: dpt3.0-dptdbin 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.
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 matter1.
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
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. ↩
[-][BUG] Package Naming Convention and Issue 4766[/-][+]Package Naming Convention and Issue 4766[/+]abravalheri commentedon Feb 5, 2026
I will move this to the
Discussionsas it does not seem to me thatsetuptoolshas a pending action point on this matter.