diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index 39252086ca1..4f38ce5aa80 100644 --- a/peps/pep-0825.rst +++ b/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,14 +861,31 @@ 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 ^^^^^ +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 +`__. + 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 @@ -993,6 +1009,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,