Fix #284: Concise "compatibility" matching

tomschr · tomschr · commit 620514214b11 · 2022-11-12T20:40:56.000+01:00
Use parts of PEP 440
diff --git a/docs/usage/compare-versions-through-expression.rst b/docs/usage/compare-versions-through-expression.rst
@@ -2,7 +2,8 @@ Comparing Versions through an Expression
 ========================================
 
 If you need a more fine-grained approach of comparing two versions,
-use the :func:`semver.match` function. It expects two arguments:
+use the :func:`Version.match <semver.version.Version.match>` function.
+It expects two arguments:
 
 1. a version string
 2. a match expression
@@ -20,9 +21,10 @@ That gives you the following possibilities to express your condition:
 
 .. code-block:: python
 
-    >>> semver.match("2.0.0", ">=1.0.0")
+    >>> version = Version(2, 0, 0)
+    >>> version.match(">=1.0.0")
     True
-    >>> semver.match("1.0.0", ">1.0.0")
+    >>> version.match("<1.0.0")
     False
 
 If no operator is specified, the match expression is interpreted as a
@@ -33,7 +35,8 @@ handle both cases:
 
 .. code-block:: python
 
-    >>> semver.match("2.0.0", "2.0.0")
+    >>> version = Version(2, 0, 0)
+    >>> version.match("2.0.0")
     True
-    >>> semver.match("1.0.0", "3.5.1")
+    >>> version.match("3.5.1")
     False
diff --git a/src/semver/version.py b/src/semver/version.py
@@ -1,5 +1,6 @@
 """Version handling."""
 
+from ast import operator
 import collections
 import re
 from functools import wraps
@@ -14,6 +15,7 @@
     cast,
     Callable,
     Collection,
+    Match
 )
 
 from ._types import (
@@ -66,6 +68,10 @@ class Version:
     """
 
     __slots__ = ("_major", "_minor", "_patch", "_prerelease", "_build")
+    #:
+    _RE_NUMBER = r"0|[1-9]\d*"
+
+
     #: Regex for number in a prerelease
     _LAST_NUMBER = re.compile(r"(?:[^\d]*(\d+)[^\d]*)+")
     #: Regex template for a semver version
@@ -102,6 +108,14 @@ class Version:
         re.VERBOSE,
     )
 
+    #: The default prefix for the prerelease part.
+    #: Used in :meth:`Version.bump_prerelease`.
+    default_prerelease_prefix = "rc"
+
+    #: The default prefix for the build part
+    #: Used in :meth:`Version.bump_build`.
+    default_build_prefix = "build"
+
     def __init__(
         self,
         major: SupportsInt,
@@ -340,22 +354,21 @@ def compare(self, other: Comparable) -> int:
         :return: The return value is negative if ver1 < ver2,
              zero if ver1 == ver2 and strictly positive if ver1 > ver2
 
-        >>> semver.compare("2.0.0")
+        >>> ver = semver.Version.parse("3.4.5")
+        >>> ver.compare("4.0.0")
         -1
-        >>> semver.compare("1.0.0")
+        >>> ver.compare("3.0.0")
         1
-        >>> semver.compare("2.0.0")
-        0
-        >>> semver.compare(dict(major=2, minor=0, patch=0))
+        >>> ver.compare("3.4.5")
         0
         """
         cls = type(self)
         if isinstance(other, String.__args__):  # type: ignore
-            other = cls.parse(other)
+            other = cls.parse(other)  # type: ignore
         elif isinstance(other, dict):
-            other = cls(**other)
+            other = cls(**other)  # type: ignore
         elif isinstance(other, (tuple, list)):
-            other = cls(*other)
+            other = cls(*other)  # type: ignore
         elif not isinstance(other, cls):
             raise TypeError(
                 f"Expected str, bytes, dict, tuple, list, or {cls.__name__} instance, "
@@ -518,25 +531,19 @@ def finalize_version(self) -> "Version":
         cls = type(self)
         return cls(self.major, self.minor, self.patch)
 
-    def match(self, match_expr: str) -> bool:
+    def _match(self, match_expr: str) -> bool:
         """
         Compare self to match a match expression.
 
         :param match_expr: optional operator and version; valid operators are
-              ``<```   smaller than
+              ``<```  smaller than
               ``>``   greater than
               ``>=``  greator or equal than
               ``<=``  smaller or equal than
               ``==``  equal
               ``!=``  not equal
+              ``~=``  compatible release clause
         :return: True if the expression matches the version, otherwise False
-
-        >>> semver.Version.parse("2.0.0").match(">=1.0.0")
-        True
-        >>> semver.Version.parse("1.0.0").match(">1.0.0")
-        False
-        >>> semver.Version.parse("4.0.4").match("4.0.4")
-        True
         """
         prefix = match_expr[:2]
         if prefix in (">=", "<=", "==", "!="):
@@ -551,7 +558,7 @@ def match(self, match_expr: str) -> bool:
             raise ValueError(
                 "match_expr parameter should be in format <op><ver>, "
                 "where <op> is one of "
-                "['<', '>', '==', '<=', '>=', '!=']. "
+                "['<', '>', '==', '<=', '>=', '!=', '~=']. "
                 "You provided: %r" % match_expr
             )
 
@@ -569,6 +576,119 @@ def match(self, match_expr: str) -> bool:
 
         return cmp_res in possibilities
 
+    def match(self, match_expr: str) -> bool:
+        """Compare self to match a match expression.
+
+        :param match_expr: optional operator and version; valid operators are
+              ``<```  smaller than
+              ``>``   greater than
+              ``>=``  greator or equal than
+              ``<=``  smaller or equal than
+              ``==``  equal
+              ``!=``  not equal
+              ``~=``  compatible release clause
+        :return: True if the expression matches the version, otherwise False
+        """
+        # TODO: The following function should be better
+        # integrated into a special Spec class
+        def compare_eq(index, other) -> bool:
+            return self[:index] == other[:index]
+
+        def compare_ne(index, other) -> bool:
+            return not compare_eq(index, other)
+
+        def compare_lt(index, other) -> bool:
+            return self[:index] < other[:index]
+
+        def compare_gt(index, other) -> bool:
+            return not compare_lt(index, other)
+
+        def compare_le(index, other) -> bool:
+            return self[:index] <= other[:index]
+
+        def compare_ge(index, other) -> bool:
+            return self[:index] >= other[:index]
+
+        def compare_compatible(index, other) -> bool:
+            return compare_gt(index, other) and compare_eq(index, other)
+
+        op_table: Dict[str, Callable[[int, Tuple], bool]] = {
+            '==': compare_eq,
+            '!=': compare_ne,
+            '<': compare_lt,
+            '>': compare_gt,
+            '<=': compare_le,
+            '>=': compare_ge,
+            '~=': compare_compatible,
+        }
+
+        regex = r"""(?P<operator>[<]|[>]|<=|>=|~=|==|!=)?
+                 (?P<version>
+                  (?P<major>0|[1-9]\d*)
+                   (?:\.(?P<minor>\*|0|[1-9]\d*)
+                   (?:\.(?P<patch>\*|0|[1-9]\d*))?
+                   )?
+                 )"""
+        match = re.match(regex, match_expr, re.VERBOSE)
+        if match is None:
+            raise ValueError(
+                "match_expr parameter should be in format <op><ver>, "
+                "where <op> is one of %s. "
+                "<ver> is a version string like '1.2.3' or '1.*' "
+                "You provided: %r" % (list(op_table.keys()), match_expr)
+            )
+        match_version = match["version"]
+        operator = cast(Dict, match).get('operator', '==')
+
+        if "*" not in match_version:
+            # conventional compare
+            possibilities_dict = {
+                ">": (1,),
+                "<": (-1,),
+                "==": (0,),
+                "!=": (-1, 1),
+                ">=": (0, 1),
+                "<=": (-1, 0),
+            }
+
+            possibilities = possibilities_dict[operator]
+            cmp_res = self.compare(match_version)
+
+            return cmp_res in possibilities
+
+        # Advanced compare with "*" like "<=1.2.*"
+        # Algorithm:
+        # TL;DR: Delegate the comparison to tuples
+        #
+        # 1. Create a tuple of the string with major, minor, and path
+        #    unless one of them is None
+        # 2. Determine the position of the first "*" in the tuple from step 1
+        # 3. Extract the matched operators
+        # 4. Look up the function in the operator table
+        # 5. Call the found function and pass the index (step 2) and
+        #    the tuple (step 1)
+        # 6. Compare the both tuples up to the position of index
+        #    For example, if you have (1, 2, "*") and self is
+        #    (1, 2, 3, None, None), you compare (1, 2) <OPERATOR> (1, 2)
+        # 7. Return the result of the comparison
+        match_version = tuple([match[item]
+                               for item in ('major', 'minor', 'patch')
+                               if item is not None
+                               ]
+                              )
+
+        try:
+            index = match_version.index("*")
+        except ValueError:
+            index = None
+
+        if not index:
+            raise ValueError("Major version cannot be set to '*'")
+
+        # At this point, only valid operators should be available
+        func: Callable[[int, Tuple], bool] = op_table[operator]
+        return func(index, match_version)
+
     @classmethod
     def parse(
         cls,
diff --git a/tests/test_match.py b/tests/test_match.py
@@ -1,14 +1,18 @@
 import pytest
 
-from semver import match
+from semver import match, Version
 
 
 def test_should_match_simple():
-    assert match("2.3.7", ">=2.3.6") is True
+    left, right = ("2.3.7", ">=2.3.6")
+    assert match(left, right) is True
+    assert Version.parse(left).match(right) is True
 
 
 def test_should_no_match_simple():
-    assert match("2.3.7", ">=2.3.8") is False
+    left, right = ("2.3.7", ">=2.3.8")
+    assert match(left, right) is False
+    assert Version.parse(left).match(right) is False
 
 
 @pytest.mark.parametrize(
@@ -21,6 +25,7 @@ def test_should_no_match_simple():
 )
 def test_should_match_not_equal(left, right, expected):
     assert match(left, right) is expected
+    assert Version.parse(left).match(right) is expected
 
 
 @pytest.mark.parametrize(
@@ -33,6 +38,7 @@ def test_should_match_not_equal(left, right, expected):
 )
 def test_should_match_equal_by_default(left, right, expected):
     assert match(left, right) is expected
+    assert Version.parse(left).match(right) is expected
 
 
 @pytest.mark.parametrize(
@@ -50,6 +56,7 @@ def test_should_not_raise_value_error_for_expected_match_expression(
     left, right, expected
 ):
     assert match(left, right) is expected
+    assert Version.parse(left).match(right) is expected
 
 
 @pytest.mark.parametrize(
@@ -58,6 +65,8 @@ def test_should_not_raise_value_error_for_expected_match_expression(
 def test_should_raise_value_error_for_unexpected_match_expression(left, right):
     with pytest.raises(ValueError):
         match(left, right)
+    with pytest.raises(ValueError):
+        Version.parse(left).match(right)
 
 
 @pytest.mark.parametrize(
@@ -66,3 +75,19 @@ def test_should_raise_value_error_for_unexpected_match_expression(left, right):
 def test_should_raise_value_error_for_invalid_match_expression(left, right):
     with pytest.raises(ValueError):
         match(left, right)
+    with pytest.raises(ValueError):
+        Version.parse(left).match(right)
+
+
+@pytest.mark.parametrize(
+    "left,right,expected",
+    [
+        ("2.3.7", "<2.4.*", True),
+        ("2.3.7", ">2.3.5", True),
+        ("2.3.7", "<=2.3.9", True),
+        ("2.3.7", ">=2.3.5", True),
+        ("2.3.7", "==2.3.7", True),
+        ("2.3.7", "!=2.3.7", False),
+    ],
+)
+def test_should_match_with_asterisk(left, right, expected):
