PEP 825: Address filename compatibility concerns from DPO (#4890)

* 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>

* PEP 825: reflow "backwards compatibility" section over line width

Signed-off-by: Michał Górny <mgorny@quansight.com>

---------

Signed-off-by: Michał Górny <mgorny@quansight.com>
Co-authored-by: Jonathan DEKHTIAR <jonathan@dekhtiar.com>

Author: mgorny

peps/pep-0825.rst

@@ -136,6 +136,8 @@ to:
     {distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}(-{variant label})?.whl
                                                                                  +++++++++++++++++++
 
+The Python tag component MUST NOT start with a digit.
+
 Variant wheels MUST include the variant label component. Conversely,
 wheels without variant label are non-variant wheels. The variant label
 MUST be non-empty and consist only of ``0-9``, ``a-z``, ``_`` and ``.``
@@ -846,11 +848,8 @@ Backwards Compatibility
 =======================
 
 Variant wheels add an additional `variant label`_ component to the wheel
-filename, causing them to be rejected while verifying the filename. This
-permits publishing them on an index alongside non-variant wheels,
-without risking previous installer versions accidentally installing
-them. It was confirmed that the filename validation algorithms in tools
-commonly used today reject it:
+filename. A complete filename verification step should reject such
+wheels:
 
 - If both the build tag and the variant label are present, the filename
   contains too many components. Example:
@@ -862,19 +861,37 @@ commonly used today reject it:
 
 - If only the variant label is present, the Python tag at third position
   will be misinterpreted as a build number. Since the build number must
-  start with a digit and Python tags do not start with digits,
-  the filename is considered invalid. Example:
+  start with a digit, the filename is considered invalid. Example:
 
   .. code-block:: text
 
      numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
                  ^^^^^
 
-The addition of the variant label increases the filename length. On platforms
-with a low total path length limit such as Windows, long filenames are a
-concern. However, given that the name and version components are already
-unrestricted, we do not set a specific limit in this PEP. Others, such as PyPI,
-may set a limit for total filename length.
+Currently, no Python tags start with a digit. To guarantee unambiguity,
+the specification enforces that going forward. Tools commonly used to
+install wheels at the time of writing implemented a verification
+algorithm of that kind, making it possible to publish variant wheels on
+an index alongside non-variant wheels without risk of them being
+installed accidentally.
+
+Tools that do not perform full filename verification will consume some
+or all variant wheels as regular wheels. This may cause unexpected
+behavior or breakage if the tool in question needs to specially account
+for variant wheels.
+
+The libraries for processing wheel files and their consumers will need
+to be updated to handle the new filename component and possibly the new
+metadata. For example, there is an `open discussion in packaging project
+how to adapt the parse_wheel_filename() function
+<https://github.com/pypa/packaging/issues/1148>`__.
+
+The addition of the variant label increases the filename length. On
+platforms with a low total path length limit such as Windows, long
+filenames are a concern. However, given that the name and version
+components are already unrestricted, we do not set a specific limit in
+this PEP. Others, such as PyPI, may set a limit for total filename
+length.
 
 Aside from this explicit incompatibility, the specification makes
 minimal and non-intrusive changes to the binary package format. The
@@ -885,10 +902,10 @@ preserve the contents of said directory.
 
 If the new `environment markers`_ are used in wheel dependencies, these
 wheels will be incompatible with existing tools. For example, upon
-meeting these markers in a dependency from an index, pip will backtrack and
-use an older dependency version (if possible). This is a general problem
-with the design of environment markers, and not specific to wheel
-variants. It is possible to work around it by partially evaluating
+meeting these markers in a dependency from an index, pip will backtrack
+and use an older dependency version (if possible). This is a general
+problem with the design of environment markers, and not specific to
+wheel variants. It is possible to work around it by partially evaluating
 environment markers at build time, and removing the markers or
 dependencies specific to variant wheels from the non-variant wheel.
 
@@ -993,6 +1010,13 @@ and Zanie Blue.
 Change History
 ==============
 
+- 06-Apr-2026
+
+  - Added a formal requirement that Python tags must not start with
+    a digit.
+  - Expanded backwards compatibility concerns regarding tools that do
+    not perform full filename verification.
+
 - 09-Mar-2026
 
   - Clarified that feature values in ``variants`` dictionary are sets,