pypa / pypa/packaging.python.org

Extract rules for normalising components of filenames

Open
#1,142 0 comments 0 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

The wheel spec contains the rules for normalising distribution name and version for use in a filename (which involves ensuring hyphens are replaced by underscores, so we can use hyphens to separate parts of filenames). PEP 625 uses the same rules (by reference) for source distributions, and in general having a "filename-safe" normalisation rule is potentially useful in other circumstances.

We should split out the normalisation rules into a separate document, keeping it under "Package Distribution File Formats" as it's a form of file format specification. It might also be worth putting the "PEP 503 normalisation" rule in this same section, so we can refer to it as a standard rather than as part of a PEP.

Ideally, we should take the time to tidy up the wording, particularly of the distribution name normalisation rule, as this has proved easy to misinterpret in the past. But if we do this, we should be careful not to nadvertantly change the meaning (as such a change would not be a simple textual clarification, and so would need approval and possibly a PEP).

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

Start by reading the wheel filename normalisation rules, PEP 625, and the PEP 503 normalisation rule. Create a separate specification under “Package Distribution File Formats,” clarify the distribution-name wording without changing its meaning, and ensure the rules can be referenced consistently for source distributions and other filename-safe uses.

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.