Repository navigation
Possible contradiction in rules for naming source distribution files containing -_. #1750
Description
Issue Description
The specification page for source distributions states the following:
The file name of a sdist was standardised in PEP 625. The file name must be in the form {name}-{version}.tar.gz, where {name} is normalised according to the same rules as for binary distributions (see Binary distribution format), and {version} is the canonicalized form of the project version (see Version specifiers).
The name and version components of the filename MUST match the values stored in the metadata contained in the file.
The rules for binary distributions states that -_. should be replaced by _ in distribution names.
But the naming convention for core metadatas requires the package maintainer to follow this normalization, which states -_. should be replaced by -.
Hence, for a package named for instance "my-package" v0.1, the metadata specification would require the "Name" attribute in the metadata to be my-package, while the specification for source distribution files requires the name of the file to be my_package-0.1.tar.gz, making it impossible to follow this part of the source distribution filename specification: "The name and version components of the filename MUST match the values stored in the metadata contained in the file."
Code of Conduct
- I am aware that participants in this repository must follow the PSF Code of Conduct.
Activity
webknjaz commented on Dec 26, 2024
I suppose "match" != "be equal exactly"? It might mean "correspond" in this context.
SoeAung95 commented on Jan 1, 2025
zahlman commented on Apr 9, 2025
This is correct. The entire point is not to use -, so that the -s in the filename can unambiguously understood as separators (between the name, version string and wheel tags, if applicable).
By my understanding: this doesn't refer specifically to "core metadata" (meaning the PKG-INFO file in an sdist or METADATA file in a wheel) - it comes first in the "Package Distribution Metadata" section, before the "Core metadata specifications". But more importantly, it's only making recommendations ("should" rather than "must"), and also isn't talking about the actual content of the metadata. This section is instead about how tools understand metadata. There are normalization rules so that they can consider different values to be equivalent; this implies that any of the equivalent values is legal in the input. Key quote:
What the core metadata specification says about the name, rather, is that
which refers back to the other part of your first link:
I don't read "the names should be normalized before comparing" as constraining the metadata file content. If it does, that really needs to be clarified.
By my reading, though, the filename can't always contain the same distribution name as the metadata; it contains a normalized version instead. I agree that "match" is intended here to mean "correspond". It would be better to make this explicit, and explicitly refer to the normalization rules there as well.
abravalheri commented on Apr 9, 2025
Yes I agree with @zahlman and @webknjaz, there is a difference between the package naming as provided by the (human) user1 and the file naming as intended to be consumed by (automated) tools.
The wheel and sdist file names need to be optimised so that the installers can quickly infer the version. That is why the package name need to be "normalised" by replacing . and - with _ when creating the archive. This way the heuristic for inferring the version is simply a variation of filename.split('-')[1].
When comparing names, (automated) tools will also perform some (other) form of "normalisation" to find matching (but not identical) names.
Footnotes
and it may contain .- characters ↩
abravalheri commented on Apr 9, 2025
This normalisation when writing core metadata files is not necessary. There were many discussions at the time of the proposal and adoption about this, the conclusion is that the metadata should preserve the intent of the user (how they want to call the package), but tools should normalising it when comparing or processing the names in automated processes.
There are many related topics in the Discourse, but this is a short one summarising the conclusions https://discuss.python.org/t/revisiting-distribution-name-normalization/12348.
docs: clarify sdist name comparison with metadata (pypa#1750)
docs(spec): explain normalized sdist filename metadata matching (pypa…