_ExclusionBound, full === detection, local version fixes

Author: notatallshaw

src/packaging/specifiers.py

@@ -49,63 +49,78 @@ def _trim_release(release: tuple[int, ...]) -> tuple[int, ...]:
     return release if end == len(release) else release[:end]
 
 
+# Sentinel kinds for _ExclusionBound.
+_AFTER_LOCALS: Final[int] = 0  # sorts after V+local, before V.post0
+_AFTER_POSTS: Final[int] = 1  # sorts after V.postN, before next release
+
+
 @functools.total_ordering
-class _PostExcludeBound:
-    """A bound version that sorts after all post-releases of a base version.
+class _ExclusionBound:
+    """A synthetic bound that sorts between version families.
+
+    PEP 440 has exclusion rules that cannot be expressed with plain Version
+    bounds.  This sentinel encodes those rules into the version ordering so
+    that interval arithmetic handles them correctly.
 
-    Used for ``>V`` (where V is not a post-release) to model PEP 440's rule
-    that ``>V`` must not match post-releases of V.
+    ``_AFTER_LOCALS``: sorts after V and all V+local, before V.post0.
+    Used for ``<=V``, ``==V``, ``!=V``, and ``>V.postN`` to correctly
+    handle local versions.
 
-    Ordering::
+    ``_AFTER_POSTS``: sorts after all V.postN (and V+local), before the
+    next release segment.  Used for ``>V`` (non-post) to exclude
+    post-releases per PEP 440.
 
-        1.0 < 1.0.post0 < 1.0.post1 < _PostExcludeBound(1.0) < 1.0.1.dev0
+    Ordering for base version V::
 
-    This type is only used in interval bounds. Most bounds use plain Version
-    objects for direct C-level comparison performance.
+        V < V+local < AFTER_LOCALS(V) < V.post0 < ... < AFTER_POSTS(V) < V.0.1
     """
 
-    __slots__ = ("_trimmed_release", "version")
+    __slots__ = ("_kind", "_trimmed_release", "version")
 
-    def __init__(self, version: Version) -> None:
+    def __init__(self, version: Version, kind: int) -> None:
         self.version = version
+        self._kind = kind
         self._trimmed_release = _trim_release(version.release)
 
-    def _is_post_family(self, other: Version) -> bool:
-        """Is ``other`` the same version as self.version, or a post-release of it?
-
-        A "post-release of V" shares V's epoch, release, and pre segment
-        but adds a post (and possibly dev-of-post) segment.
-        """
+    def _is_family(self, other: Version) -> bool:
+        """Is ``other`` a version that this sentinel sorts above?"""
         v = self.version
-        return (
+        if not (
             other.epoch == v.epoch
             and _trim_release(other.release) == self._trimmed_release
             and other.pre == v.pre
-            and (other.dev == v.dev or other.post is not None)
-        )
+        ):
+            return False
+        if self._kind == _AFTER_LOCALS:
+            # Local family: exact same public version (any local label).
+            return other.post == v.post and other.dev == v.dev
+        # Post family: same base + any post-release (or identical).
+        return other.dev == v.dev or other.post is not None
 
     def __eq__(self, other: object) -> bool:
-        if isinstance(other, _PostExcludeBound):
-            return self.version == other.version
+        if isinstance(other, _ExclusionBound):
+            return self.version == other.version and self._kind == other._kind
         return NotImplemented
 
     def __lt__(self, other: object) -> bool:
-        if isinstance(other, _PostExcludeBound):
-            return self.version < other.version
+        if isinstance(other, _ExclusionBound):
+            if self.version != other.version:
+                return self.version < other.version
+            return self._kind < other._kind
         assert isinstance(other, Version)
-        # self < other iff other is NOT in the post-family and other > V
-        return not self._is_post_family(other) and self.version < other
+        # self < other iff other is NOT in the family and other > V
+        return not self._is_family(other) and self.version < other
 
     def __hash__(self) -> int:
-        return hash(self.version)
+        return hash((self.version, self._kind))
 
 
 if typing.TYPE_CHECKING:
     from typing_extensions import TypeAlias
 
-    # Bound version: plain Version for most operators, _PostExcludeBound
-    # for >V (sorts after V.postN), or None for unbounded.
-    _BoundVersion: TypeAlias = Union[Version, _PostExcludeBound, None]
+    # Bound version: plain Version for most operators, _ExclusionBound
+    # for local/post exclusion zones, or None for unbounded.
+    _BoundVersion: TypeAlias = Union[Version, _ExclusionBound, None]
 
     # A specifier bound: (bound_version, inclusive).
     _SpecifierBound: TypeAlias = tuple[_BoundVersion, bool]
@@ -504,10 +519,8 @@ def _require_spec_version(self, version: str) -> Version:
     def _to_intervals(self) -> list[_SpecifierInterval]:
         """Convert this specifier to sorted, non-overlapping intervals.
 
-        Each standard operator maps to one or two intervals. The ``===``
-        operator is modeled as full range since it uses arbitrary string
-        matching; the actual check is done separately.
-        Result is cached.
+        Each standard operator maps to one or two intervals.  ``===`` is
+        modeled as full range (actual check done separately).  Cached.
         """
         if self._intervals is not None:
             return self._intervals
@@ -519,51 +532,62 @@ def _to_intervals(self) -> list[_SpecifierInterval]:
             self._intervals = _FULL_RANGE
             return _FULL_RANGE
 
-        result: list[_SpecifierInterval]
-
         if ver_str.endswith(".*"):
-            # Wildcard bounds: ==1.2.* matches [1.2.dev0, 1.3.dev0).
-            base = self._require_spec_version(ver_str[:-2])
-            lower = _base_dev0(base)
-            upper = _next_prefix_dev0(base)
-            if op == "==":
-                result = [((lower, True), (upper, False))]
-            else:  # !=
-                result = [
-                    ((None, False), (lower, False)),
-                    ((upper, True), (None, False)),
-                ]
+            result = self._wildcard_intervals(op, ver_str)
         else:
-            v = self._require_spec_version(ver_str)
-            if op == ">=":
-                result = [((v, True), (None, False))]
-            elif op == "<=":
-                result = [((None, False), (v, True))]
-            elif op == ">":
-                if v.is_postrelease:
-                    result = [((v, False), (None, False))]
-                else:
-                    result = [((_PostExcludeBound(v), False), (None, False))]
-            elif op == "<":
-                bound = v if v.is_prerelease else _base_dev0(v)
-                if bound <= _MIN_VERSION:
-                    result = []
-                else:
-                    result = [((None, False), (bound, False))]
-            elif op == "==":
-                result = [((v, True), (v, True))]
-            elif op == "!=":
-                result = [((None, False), (v, False)), ((v, False), (None, False))]
-            elif op == "~=":
-                prefix = v.__replace__(release=v.release[:-1])
-                upper = _next_prefix_dev0(prefix)
-                result = [((v, True), (upper, False))]
-            else:
-                raise ValueError(f"Unknown operator: {op!r}")  # pragma: no cover
+            result = self._standard_intervals(op, ver_str)
 
         self._intervals = result
         return result
 
+    def _wildcard_intervals(self, op: str, ver_str: str) -> list[_SpecifierInterval]:
+        # ==1.2.* -> [1.2.dev0, 1.3.dev0);  !=1.2.* -> complement.
+        base = self._require_spec_version(ver_str[:-2])
+        lower = _base_dev0(base)
+        upper = _next_prefix_dev0(base)
+        if op == "==":
+            return [((lower, True), (upper, False))]
+        # !=
+        return [((None, False), (lower, False)), ((upper, True), (None, False))]
+
+    def _standard_intervals(self, op: str, ver_str: str) -> list[_SpecifierInterval]:
+        v = self._require_spec_version(ver_str)
+        has_local = "+" in ver_str
+        after_locals = _ExclusionBound(v, _AFTER_LOCALS)
+
+        if op == ">=":
+            return [((v, True), (None, False))]
+
+        if op == "<=":
+            return [((None, False), (after_locals, True))]
+
+        if op == ">":
+            # >V.postN: skip V.postN+local.  >V: skip all V.postN too.
+            kind = _AFTER_LOCALS if v.is_postrelease else _AFTER_POSTS
+            return [((_ExclusionBound(v, kind), False), (None, False))]
+
+        if op == "<":
+            bound = v if v.is_prerelease else _base_dev0(v)
+            if bound <= _MIN_VERSION:
+                return []
+            return [((None, False), (bound, False))]
+
+        if op == "==":
+            # ==V (no local) matches V+local; ==V+local matches exactly.
+            eq_upper: Version | _ExclusionBound = v if has_local else after_locals
+            return [((v, True), (eq_upper, True))]
+
+        if op == "!=":
+            # !=V (no local) excludes V+local; !=V+local excludes exactly.
+            ne_upper: Version | _ExclusionBound = v if has_local else after_locals
+            return [((None, False), (v, False)), ((ne_upper, False), (None, False))]
+
+        if op == "~=":
+            prefix = v.__replace__(release=v.release[:-1])
+            return [((v, True), (_next_prefix_dev0(prefix), False))]
+
+        raise ValueError(f"Unknown operator: {op!r}")  # pragma: no cover
+
     @property
     def prereleases(self) -> bool | None:
         # If there is an explicit prereleases set for this, then we'll just
@@ -1366,8 +1390,6 @@ def is_unsatisfiable(self) -> bool:
         """Check whether this specifier set can never be satisfied.
 
         Returns True if no version can satisfy all specifiers simultaneously.
-        Returns False if the set might be satisfiable (conservative: may
-        return False for some unsatisfiable sets involving === specifiers).
 
         >>> SpecifierSet(">=2.0,<1.0").is_unsatisfiable()
         True
@@ -1388,17 +1410,41 @@ def is_unsatisfiable(self) -> bool:
 
         result = not self._get_intervals()
 
-        # Extra: === with an unparsable version can only match raw
-        # strings, but standard specs reject raw strings.
-        if not result and any(
-            s.operator == "===" and _coerce_version(s.version) is None
-            for s in self._specs
-        ):
-            result = any(s.operator != "===" for s in self._specs)
+        if not result:
+            result = self._check_arbitrary_unsatisfiable()
 
         self._is_unsatisfiable = result
         return result
 
+    def _check_arbitrary_unsatisfiable(self) -> bool:
+        """Check === (arbitrary equality) specs for unsatisfiability.
+
+        === uses case-insensitive string comparison, so the only candidate
+        that can match ``===V`` is the literal string V.  This method
+        checks whether that candidate is excluded by other specifiers.
+        """
+        arbitrary = [s for s in self._specs if s.operator == "==="]
+        if not arbitrary:
+            return False
+
+        # Multiple === must agree on the same string (case-insensitive).
+        first = arbitrary[0].version.lower()
+        if any(s.version.lower() != first for s in arbitrary[1:]):
+            return True
+
+        # The sole candidate is the === version string.  Check whether
+        # it can satisfy every standard spec.
+        standard = [s for s in self._specs if s.operator != "==="]
+        if not standard:
+            return False
+
+        candidate = _coerce_version(arbitrary[0].version)
+        if candidate is None:
+            # Unparsable string cannot satisfy any standard spec.
+            return True
+
+        return not all(s.contains(candidate) for s in standard)
+
     def __contains__(self, item: UnparsedVersion) -> bool:
         """Return whether or not the item is contained in this specifier.