Support arbitrary equality on arbitrary strings

Author: notatallshaw

src/packaging/specifiers.py

@@ -278,21 +278,27 @@ def _get_spec_version(self, version: str) -> Version:
         return version_specifier
 
     @property
-    def prereleases(self) -> bool:
+    def prereleases(self) -> bool | None:
         # If there is an explicit prereleases set for this, then we'll just
         # blindly use that.
         if self._prereleases is not None:
             return self._prereleases
 
         # Only the "!=" operator does not imply prereleases when
         # the version in the specifier is a prerelease.
-        operator, version = self._spec
+        operator, item = self._spec
         if operator != "!=":
             # The == specifier with trailing .* cannot include prereleases
             # e.g. "==1.0a1.*" is not valid.
-            if operator == "==" and version.endswith(".*"):
+            if operator == "==" and item.endswith(".*"):
                 return False
 
+            # "===" can have arbitrary string versions, so we cannot
+            # parse those, we take prereleases as False for those.
+            version = _coerce_version(item)
+            if version is None:
+                return None
+
             # For all other operators, use the check if spec Version
             # object implies pre-releases.
             if self._get_spec_version(version).is_prerelease:
@@ -537,7 +543,7 @@ def _compare_greater_than(self, prospective: Version, spec_str: str) -> bool:
         # same version in the spec.
         return True
 
-    def _compare_arbitrary(self, prospective: Version, spec: str) -> bool:
+    def _compare_arbitrary(self, prospective: Version | str, spec: str) -> bool:
         return str(prospective).lower() == str(spec).lower()
 
     def __contains__(self, item: str | Version) -> bool:
@@ -627,9 +633,15 @@ def filter(
         for version in iterable:
             parsed_version = _coerce_version(version)
             if parsed_version is None:
-                continue
-
-            if operator_callable(parsed_version, self.version):
+                # === operator can match arbitrary (non-version) strings
+                if self.operator == "===" and self._compare_arbitrary(
+                    version, self.version
+                ):
+                    yield version
+                # != operator: non-version strings pass through (they're "not equal")
+                elif self.operator == "!=":
+                    yield version
+            elif operator_callable(parsed_version, self.version):
                 # If it's not a prerelease or prereleases are allowed, yield it directly
                 if not parsed_version.is_prerelease or include_prereleases:
                     found_non_prereleases = True
@@ -944,13 +956,12 @@ def contains(
         True
         """
         version = _coerce_version(item)
-        if version is None:
-            return False
 
-        if installed and version.is_prerelease:
+        if version is not None and installed and version.is_prerelease:
             prereleases = True
 
-        return bool(list(self.filter([version], prereleases=prereleases)))
+        check_item = item if version is None else version
+        return bool(list(self.filter([check_item], prereleases=prereleases)))
 
     def filter(
         self, iterable: Iterable[UnparsedVersionVar], prereleases: bool | None = None
@@ -1030,9 +1041,7 @@ def filter(
 
         for item in iterable:
             parsed_version = _coerce_version(item)
-            if parsed_version is None:
-                continue
-            if parsed_version.is_prerelease:
+            if parsed_version is not None and parsed_version.is_prerelease:
                 found_prereleases.append(item)
             else:
                 filtered.append(item)

tests/test_specifiers.py

@@ -517,15 +517,26 @@ def test_specifiers(self, version: str, spec_str: str, expected: bool) -> None:
             assert not spec.contains(Version(version))
 
     @pytest.mark.parametrize(
-        ("spec_str", "version"),
+        ("spec_str", "version", "expected"),
         [
-            ("==1.0", "not a valid version"),
-            ("===invalid", "invalid"),
+            ("==1.0", "not a valid version", False),
+            (">=1.0", "not a valid version", False),
+            (">1.0", "not a valid version", False),
+            ("<=1.0", "not a valid version", False),
+            ("<1.0", "not a valid version", False),
+            ("~=1.0", "not a valid version", False),
+            # Test invalid versions with != (should pass as "not equal")
+            ("!=1.0", "not a valid version", True),
+            ("!=1.0", "not a valid version", True),
+            ("!=2.0.*", "not a valid version", True),
+            # Test with arbitrary equality (===)
+            ("===invalid", "invalid", True),
+            ("===foobar", "invalid", False),
         ],
     )
-    def test_invalid_spec(self, spec_str: str, version: str) -> None:
+    def test_invalid_version(self, spec_str: str, version, expected: str) -> None:
         spec = Specifier(spec_str, prereleases=True)
-        assert not spec.contains(version)
+        assert spec.contains(version) == expected
 
     @pytest.mark.parametrize(
         (
@@ -588,9 +599,15 @@ def test_specifier_prereleases_set(
         [
             ("1.0.0", "===1.0", False),
             ("1.0.dev0", "===1.0", False),
-            # Test identity comparison by itself
+            # Test exact arbitrary equality (===)
             ("1.0", "===1.0", True),
             ("1.0.dev0", "===1.0.dev0", True),
+            # Test that local versions don't match
+            ("1.0+downstream1", "===1.0", False),
+            ("1.0", "===1.0+downstream1", False),
+            # Test with arbitrary (non-version) strings
+            ("foobar", "===foobar", True),
+            ("foobar", "===baz", False),
             # Test case insensitivity for pre-release versions
             ("1.0a1", "===1.0a1", True),
             ("1.0A1", "===1.0A1", True),
@@ -636,17 +653,11 @@ def test_specifier_prereleases_set(
             ("1.0A1.POST2.DEV3", "===1.0a1.post2.dev3", True),
         ],
     )
-    def test_specifiers_identity(
+    def test_arbitrary_equality(
         self, version: str, spec_str: str, expected: bool
     ) -> None:
         spec = Specifier(spec_str)
-
-        if expected:
-            # Identity comparisons only support the plain string form
-            assert version in spec
-        else:
-            # Identity comparisons only support the plain string form
-            assert version not in spec
+        assert spec.contains(version) == expected
 
     @pytest.mark.parametrize(
         ("specifier", "expected"),
@@ -730,6 +741,33 @@ def test_specifiers_prereleases(
             # Test that invalid versions are discarded
             (">=1.0", None, None, ["not a valid version"], []),
             (">=1.0", None, None, ["1.0", "not a valid version"], ["1.0"]),
+            # Test arbitrary equality (===)
+            ("===foobar", None, None, ["foobar", "foo", "bar"], ["foobar"]),
+            ("===foobar", None, None, ["foo", "bar"], []),
+            # Test that === does not match with zero padding
+            ("===1.0", None, None, ["1.0", "1.0.0", "2.0"], ["1.0"]),
+            # Test that === does not match with local versions
+            ("===1.0", None, None, ["1.0", "1.0+downstream1"], ["1.0"]),
+            # Test === with mix of valid versions and arbitrary strings
+            (
+                "===foobar",
+                None,
+                None,
+                ["foobar", "1.0", "2.0a1", "invalid"],
+                ["foobar"],
+            ),
+            ("===1.0", None, None, ["1.0", "foobar", "invalid", "1.0.0"], ["1.0"]),
+            # Test != with invalid versions (should pass through as "not equal")
+            ("!=1.0", None, None, ["invalid", "foobar"], ["invalid", "foobar"]),
+            ("!=1.0", None, None, ["1.0", "invalid", "2.0"], ["invalid", "2.0"]),
+            (
+                "!=2.0.*",
+                None,
+                None,
+                ["invalid", "foobar", "2.0"],
+                ["invalid", "foobar"],
+            ),
+            ("!=2.0.*", None, None, ["1.0", "invalid", "2.0.0"], ["1.0", "invalid"]),
         ],
     )
     def test_specifier_filter(
@@ -1190,12 +1228,61 @@ def test_specifier_contains_installed_prereleases(
             (">=1.0,<=2.0dev", True, False, ["1.0", "1.5a1"], ["1.0"]),
             (">=1.0,<=2.0dev", False, True, ["1.0", "1.5a1"], ["1.0", "1.5a1"]),
             # Test that invalid versions are discarded
-            ("", None, None, ["invalid version"], []),
+            ("", None, None, ["invalid version"], ["invalid version"]),
             ("", None, False, ["invalid version"], []),
             ("", False, None, ["invalid version"], []),
-            ("", None, None, ["1.0", "invalid version"], ["1.0"]),
+            ("", None, None, ["1.0", "invalid version"], ["1.0", "invalid version"]),
             ("", None, False, ["1.0", "invalid version"], ["1.0"]),
             ("", False, None, ["1.0", "invalid version"], ["1.0"]),
+            # Test arbitrary equality (===)
+            ("===foobar", None, None, ["foobar", "foo", "bar"], ["foobar"]),
+            ("===foobar", None, None, ["foo", "bar"], []),
+            # Test that === does not match with zero padding
+            ("===1.0", None, None, ["1.0", "1.0.0", "2.0"], ["1.0"]),
+            # Test that === does not match with local versions
+            ("===1.0", None, None, ["1.0", "1.0+downstream1"], ["1.0"]),
+            # Test === combined with other operators (arbitrary string)
+            (">=1.0,===foobar", None, None, ["foobar", "1.0", "2.0"], []),
+            ("!= 2.0,===foobar", None, None, ["foobar", "2.0", "bar"], ["foobar"]),
+            # Test === combined with other operators (version string)
+            (">=1.0,===1.5", None, None, ["1.0", "1.5", "2.0"], ["1.5"]),
+            (">=2.0,===1.5", None, None, ["1.0", "1.5", "2.0"], []),
+            # Test === with mix of valid and invalid versions
+            (
+                "===foobar",
+                None,
+                None,
+                ["foobar", "1.0", "invalid", "2.0a1"],
+                ["foobar"],
+            ),
+            ("===1.0", None, None, ["1.0", "foobar", "invalid", "1.0.0"], ["1.0"]),
+            (">=1.0,===1.5", None, None, ["1.5", "foobar", "invalid"], ["1.5"]),
+            # Test != with invalid versions (should pass through as "not equal")
+            ("!=1.0", None, None, ["invalid", "foobar"], ["invalid", "foobar"]),
+            ("!=1.0", None, None, ["1.0", "invalid", "2.0"], ["invalid", "2.0"]),
+            (
+                "!=2.0.*",
+                None,
+                None,
+                ["invalid", "foobar", "2.0"],
+                ["invalid", "foobar"],
+            ),
+            ("!=2.0.*", None, None, ["1.0", "invalid", "2.0.0"], ["1.0", "invalid"]),
+            # Test != with invalid versions combined with other operators
+            (
+                "!=1.0,!=2.0",
+                None,
+                None,
+                ["invalid", "1.0", "2.0", "3.0"],
+                ["invalid", "3.0"],
+            ),
+            (
+                ">=1.0,!=2.0",
+                None,
+                None,
+                ["invalid", "1.0", "2.0", "3.0"],
+                ["1.0", "3.0"],
+            ),
         ],
     )
     def test_specifier_filter(
@@ -1591,6 +1678,41 @@ def test_contains_rejects_invalid_specifier(
         spec = SpecifierSet(specifier, prereleases=True)
         assert not spec.contains(input)
 
+    @pytest.mark.parametrize(
+        ("version", "specifier", "expected"),
+        [
+            # Test arbitrary equality (===) with arbitrary strings
+            ("foobar", "===foobar", True),
+            ("foo", "===foobar", False),
+            ("bar", "===foobar", False),
+            # Test that === does not match with zero padding
+            ("1.0", "===1.0", True),
+            ("1.0.0", "===1.0", False),
+            # Test that === does not match with local versions
+            ("1.0", "===1.0+downstream1", False),
+            ("1.0+downstream1", "===1.0", False),
+            # Test === combined with other operators (arbitrary string)
+            ("foobar", "===foobar,!=1.0", True),
+            ("1.0", "===foobar,!=1.0", False),
+            ("foobar", ">=1.0,===foobar", False),
+            # Test === combined with other operators (version string)
+            ("1.5", ">=1.0,===1.5", True),
+            ("1.5", ">=2.0,===1.5", False),  # Doesn't meet >=2.0
+            ("2.5", ">=1.0,===2.5", True),
+            # Test != with invalid versions (should pass as "not equal")
+            ("invalid", "!=1.0", True),
+            ("foobar", "!=1.0", True),
+            ("invalid", "!=2.0.*", True),
+            # Test != with invalid versions combined with other operators
+            ("invalid", "!=1.0,!=2.0", True),
+            ("foobar", ">=1.0,!=2.0", False),
+            ("1.5", ">=1.0,!=2.0", True),
+        ],
+    )
+    def test_contains_arbitrary_equality_contains(self, version, specifier, expected):
+        spec = SpecifierSet(specifier)
+        assert spec.contains(version) == expected
+
     @pytest.mark.parametrize(
         ("specifier", "expected"),
         [