feat: option to validate compressed tag set sort order in parse_wheel_filename (#1150)

* fix(utils): validate compressed tag set sort order per PEP 425 (closes #909)

* tests(utils): add tests for compressed tag set sort order validation

* tests(utils): add tests for compressed tag set sort order validation

* refactor: move compressed tag set sorted-order check into parse_tag

Per review suggestion from pradyunsg: the PEP 425 sorted-order invariant
is now enforced at the parse_tag level, raising ValueError when a
compressed tag set component is not sorted. parse_wheel_filename catches
this and re-raises as InvalidWheelFilename with the full filename for
better error context.

* refactor: move compressed tag set sorted-order check into parse_tag

Per review suggestion from pradyunsg: the PEP 425 sorted-order invariant
is now enforced at the parse_tag level, raising ValueError when a
compressed tag set component is not sorted. parse_wheel_filename catches
this and re-raises as InvalidWheelFilename with the full filename for
better error context.

* refactor: move compressed tag set sorted-order check into parse_tag

Per review suggestion from pradyunsg: the PEP 425 sorted-order invariant
is now enforced at the parse_tag level, raising ValueError when a
compressed tag set component is not sorted. parse_wheel_filename catches
this and re-raises as InvalidWheelFilename with the full filename for
better error context.

* Make sorted-tag validation opt-in via validate_order parameter

Per review feedback: 370K+ wheels on PyPI have unsorted compressed
tag sets, so the check must be opt-in for backwards compatibility.

- Add validate_order=False to parse_tag() and parse_wheel_filename()
- Only check sorted order when validate_order=True
- Fix exception chaining (raise ... from None)
- Update tests: unsorted tags parse by default, rejected with validate

* style: fix lint (trailing newline + line length)

* chore: one more edit from prek

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

* refactor: use UnsortedTagsError

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

---------

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>
Co-authored-by: r266-tech <r266-tech@users.noreply.github.com>
Co-authored-by: Henry Schreiner <henryfs@princeton.edu>
Co-authored-by: Brett Cannon <brett@python.org>

Author: 3 people

src/packaging/tags.py

@@ -36,6 +36,7 @@
     "AppleVersion",
     "PythonVersion",
     "Tag",
+    "UnsortedTagsError",
     "android_platforms",
     "compatible_tags",
     "cpython_tags",
@@ -79,6 +80,12 @@ def _compute_32_bit_interpreter() -> bool:
 _32_BIT_INTERPRETER = _compute_32_bit_interpreter()
 
 
+class UnsortedTagsError(ValueError):
+    """
+    Raised when a tag component is not in sorted order per PEP 425.
+    """
+
+
 class Tag:
     """
     A representation of the tag triple for a wheel.
@@ -159,7 +166,7 @@ def __setstate__(self, state: tuple[None, dict[str, Any]]) -> None:
         self._hash = hash((self._interpreter, self._abi, self._platform))
 
 
-def parse_tag(tag: str) -> frozenset[Tag]:
+def parse_tag(tag: str, *, validate_order: bool = False) -> frozenset[Tag]:
     """
     Parses the provided tag (e.g. `py3-none-any`) into a frozenset of
     :class:`Tag` instances.
@@ -168,10 +175,27 @@ def parse_tag(tag: str) -> frozenset[Tag]:
     `compressed tag set`_, e.g. ``"py2.py3-none-any"`` which supports both
     Python 2 and Python 3.
 
+    If **validate_order** is true, compressed tag set components are checked
+    to be in sorted order as required by PEP 425.
+
     :param str tag: The tag to parse, e.g. ``"py3-none-any"``.
+    :param bool validate_order: Check whether compressed tag set components
+        are in sorted order.
+    :raises UnsortedTagsError: If **validate_order** is true and any compressed tag
+        set component is not in sorted order.
+
+    .. versionadded:: 26.1
+       The *validate_order* parameter.
     """
     tags = set()
     interpreters, abis, platforms = tag.split("-")
+    if validate_order:
+        for component in (interpreters, abis, platforms):
+            parts = component.split(".")
+            if parts != sorted(parts):
+                raise UnsortedTagsError(
+                    f"Tag component {component!r} is not in sorted order per PEP 425"
+                )
     for interpreter in interpreters.split("."):
         for abi in abis.split("."):
             for platform_ in platforms.split("."):

src/packaging/utils.py

@@ -7,7 +7,7 @@
 import re
 from typing import NewType, Tuple, Union, cast
 
-from .tags import Tag, parse_tag
+from .tags import Tag, UnsortedTagsError, parse_tag
 from .version import InvalidVersion, Version, _TrimmedRelease
 
 __all__ = [
@@ -156,6 +156,8 @@ def canonicalize_version(
 
 def parse_wheel_filename(
     filename: str,
+    *,
+    validate_order: bool = False,
 ) -> tuple[NormalizedName, Version, BuildTag, frozenset[Tag]]:
     """
     This function takes the filename of a wheel file, and parses it,
@@ -171,7 +173,12 @@ def parse_wheel_filename(
     string format allows multiple tags to be combined into a single
     string).
 
+    If **validate_order** is true, compressed tag set components are
+    checked to be in sorted order as required by PEP 425.
+
     :param str filename: The name of the wheel file.
+    :param bool validate_order: Check whether compressed tag set components
+        are in sorted order.
     :raises InvalidWheelFilename: If the filename in question
         does not follow the :ref:`wheel specification
         <pypug:binary-distribution-format>`.
@@ -188,6 +195,9 @@ def parse_wheel_filename(
     True
     >>> not build
     True
+
+    .. versionadded:: 26.1
+       The *validate_order* parameter.
     """
     if not filename.endswith(".whl"):
         raise InvalidWheelFilename(
@@ -225,7 +235,14 @@ def parse_wheel_filename(
         build = cast("BuildTag", (int(build_match.group(1)), build_match.group(2)))
     else:
         build = ()
-    tags = parse_tag(parts[-1])
+    tag_str = parts[-1]
+    try:
+        tags = parse_tag(tag_str, validate_order=validate_order)
+    except UnsortedTagsError:
+        raise InvalidWheelFilename(
+            f"Invalid wheel filename (compressed tag set components must be in "
+            f"sorted order per PEP 425): {filename!r}"
+        ) from None
     return (name, version, build, tags)
 
 

tests/test_tags.py

@@ -167,6 +167,35 @@ def test_multi_platform(self) -> None:
         )
         assert given == expected
 
+    def test_unsorted_interpreter_parses_by_default(self) -> None:
+        # Unsorted tags should parse fine without validate_order
+        result = tags.parse_tag("py3.py2-none-any")
+        assert tags.Tag("py3", "none", "any") in result
+        assert tags.Tag("py2", "none", "any") in result
+
+    def test_unsorted_interpreter_raises_with_validate(self) -> None:
+        with pytest.raises(ValueError, match="not in sorted order"):
+            tags.parse_tag("py3.py2-none-any", validate_order=True)
+
+    def test_unsorted_platform_parses_by_default(self) -> None:
+        result = tags.parse_tag(
+            "cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64"
+        )
+        assert len(result) == 2
+
+    def test_unsorted_platform_raises_with_validate(self) -> None:
+        with pytest.raises(ValueError, match="not in sorted order"):
+            tags.parse_tag(
+                "cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64",
+                validate_order=True,
+            )
+
+    def test_sorted_multi_interpreter_valid(self) -> None:
+        # py2 < py3 alphabetically — should not raise even with validation
+        result = tags.parse_tag("py2.py3-none-any", validate_order=True)
+        assert tags.Tag("py2", "none", "any") in result
+        assert tags.Tag("py3", "none", "any") in result
+
 
 class TestInterpreterName:
     def test_sys_implementation_name(self, monkeypatch: pytest.MonkeyPatch) -> None:

tests/test_utils.py

@@ -137,6 +137,16 @@ def test_canonicalize_version_no_strip_trailing_zero(version: str) -> None:
             (1000, "abc"),
             {Tag("py3", "none", "any")},
         ),
+        (
+            "pyvirtualcam-0.13.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl",
+            "pyvirtualcam",
+            Version("0.13.0"),
+            (),
+            {
+                Tag("cp310", "cp310", "manylinux2014_x86_64"),
+                Tag("cp310", "cp310", "manylinux_2_17_x86_64"),
+            },
+        ),
         (
             "foo_bár-1.0-py3-none-any.whl",
             "foo-bár",
@@ -177,6 +187,30 @@ def test_parse_wheel_invalid_filename(filename: str) -> None:
         parse_wheel_filename(filename)
 
 
+@pytest.mark.parametrize(
+    "filename",
+    [
+        "pyvirtualcam-0.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
+        "foo-1.0-py3.py2-none-any.whl",
+    ],
+)
+def test_parse_wheel_unsorted_tags_valid_by_default(filename: str) -> None:
+    # Unsorted compressed tags should parse fine without validate_order
+    parse_wheel_filename(filename)
+
+
+@pytest.mark.parametrize(
+    "filename",
+    [
+        "pyvirtualcam-0.13.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
+        "foo-1.0-py3.py2-none-any.whl",
+    ],
+)
+def test_parse_wheel_unsorted_tags_invalid_with_validate(filename: str) -> None:
+    with pytest.raises(InvalidWheelFilename):
+        parse_wheel_filename(filename, validate_order=True)
+
+
 @pytest.mark.parametrize(
     ("filename", "name", "version"),
     [("foo-1.0.tar.gz", "foo", Version("1.0")), ("foo-1.0.zip", "foo", Version("1.0"))],