pypa / pypa/packaging.python.org

Non-normative guidance on sdist filenames?

Open
#1,077 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component: specifications type: discussion
Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

Description

This is a copy of what I wrote in https://github.com/pypa/packaging.python.org/pull/1066#issuecomment-1116728314, since it's off-topic there, in reference to the current source distribution filename format guidelines (link):

The file name of a sdist is not currently standardised, although the de facto form is {name}-{version}.tar.gz, where {name} is the canonicalized form of the project name (see PEP 503 for the canonicalization rules) with - characters replaced with _, and {version} is the canonicalized form of the project version (see Version specifiers).

Does PyPI or any other PEP 503-compliant host currently do the - to _ normalization? The standard here suggests that foo-bar==1.2.3 should be normalized to foo_bar-1.2.3.tar.gz, but here's how PyPI's simple index supplies pip-audit's source distributions (link):

pip-audit-2.1.0.tar.gz
pip-audit-2.1.1.tar.gz
pip-audit-2.2.0.tar.gz
pip-audit-2.2.1.tar.gz
(The current behavior is clearly working since pip has a workaround for the "vexing parse" case in https://github.com/pypa/packaging/issues/527, but I wonder if it makes sense to amend this documentation again to emphasize that the normalization suggested currently isn't practiced.)

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 with the source distribution file name section in the Python Packaging User Guide and compare its guidance with the linked PyPI simple index examples. Read PEP 503 and the referenced packaging issue 527 to understand the normalization behavior. Done means the documentation accurately distinguishes the stated guidance from the behavior used by package indexes.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.