Skip to content

Commit dc90126

Browse files
committed
PEP 825: Address filename compatibility concerns from DPO
Add an explicit requirement that the Python tag does not start with a digit, and cover filename backwards compatibility risks in greater extent, following the suggestions from the DPO thread. Signed-off-by: Michał Górny <mgorny@quansight.com>
1 parent 1195ff0 commit dc90126

1 file changed

Lines changed: 30 additions & 7 deletions

File tree

peps/pep-0825.rst

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,8 @@ to:
136136
{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}(-{variant label})?.whl
137137
+++++++++++++++++++
138138
139+
The Python tag component MUST NOT start with a digit.
140+
139141
Variant wheels MUST include the variant label component. Conversely,
140142
wheels without variant label are non-variant wheels. The variant label
141143
MUST be non-empty and consist only of ``0-9``, ``a-z``, ``_`` and ``.``
@@ -846,11 +848,8 @@ Backwards Compatibility
846848
=======================
847849

848850
Variant wheels add an additional `variant label`_ component to the wheel
849-
filename, causing them to be rejected while verifying the filename. This
850-
permits publishing them on an index alongside non-variant wheels,
851-
without risking previous installer versions accidentally installing
852-
them. It was confirmed that the filename validation algorithms in tools
853-
commonly used today reject it:
851+
filename. A complete filename verification step should reject such
852+
wheels:
854853

855854
- If both the build tag and the variant label are present, the filename
856855
contains too many components. Example:
@@ -862,14 +861,31 @@ commonly used today reject it:
862861
863862
- If only the variant label is present, the Python tag at third position
864863
will be misinterpreted as a build number. Since the build number must
865-
start with a digit and Python tags do not start with digits,
866-
the filename is considered invalid. Example:
864+
start with a digit, the filename is considered invalid. Example:
867865

868866
.. code-block:: text
869867
870868
numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
871869
^^^^^
872870
871+
Currently, no Python tags start with a digit. To guarantee unambiguity,
872+
the specification enforces that going forward. Tools commonly used to
873+
install wheels at the time of writing implemented a verification
874+
algorithm of that kind, making it possible to publish variant wheels on
875+
an index alongside non-variant wheels without risk of them being
876+
installed accidentally.
877+
878+
Tools that do not perform full filename verification will consume some
879+
or all variant wheels as regular wheels. This may cause unexpected
880+
behavior or breakage if the tool in question needs to specially account
881+
for variant wheels.
882+
883+
The libraries for processing wheel files and their consumers will need
884+
to be updated to handle the new filename component and possibly the new
885+
metadata. For example, there is an `open discussion in packaging project
886+
how to adapt the parse_wheel_filename() function
887+
<https://github.com/pypa/packaging/issues/1148>`__.
888+
873889
The addition of the variant label increases the filename length. On platforms
874890
with a low total path length limit such as Windows, long filenames are a
875891
concern. However, given that the name and version components are already
@@ -993,6 +1009,13 @@ and Zanie Blue.
9931009
Change History
9941010
==============
9951011

1012+
- 06-Apr-2026
1013+
1014+
- Added a formal requirement that Python tags must not start with
1015+
a digit.
1016+
- Expanded backwards compatibility concerns regarding tools that do
1017+
not perform full filename verification.
1018+
9961019
- 09-Mar-2026
9971020

9981021
- Clarified that feature values in ``variants`` dictionary are sets,

0 commit comments

Comments
 (0)