pypa / pypa/packaging.python.org
Extract rules for normalising components of filenames
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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