pypa / pypa/packaging.python.org

Possible contradiction in rules for naming source distribution files containing `-_.`

Open
#1,750 5 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the source distribution, binary distribution, core metadata, and name normalization specification pages linked in the issue, focusing on how each defines name normalization. Trace the example “my-package” through those rules and document a consistent resolution, updating the affected specification wording and references so the filename and metadata requirements no longer contradict each other.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.