Fix #284: implement "is_compatible" with method

tomschr · Lexicality · tlaferriere · tomschr · commit 2be3b6ae90bc · 2022-11-19T13:44:31.000+01:00
* Implement Version.is_compatible() method
* Update test cases
* Update documentation
* Rename isvalid method to is_valid to make it consistent
  with is_compatible

The algorithm checks:

* if the two majors are different, it's incompatible
* if the two majors are equal, but the minor of the new
  version is lower than the old, it's incompatible
* if both prereleases are present and different,
  it's incompatible
* otherwise it's compatible

The algorithm does *not* check patches!

Co-authored-by: Lexi Robinson &lt;lexi@lexi.org.uk&gt;
Co-authored-by: Thomas Laferriere &lt;tlaferriere@users.noreply.github.com&gt;
Co-authored-by: Raphael Krupinski &lt;rafalkrupinski@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -264,3 +264,6 @@ fabric.properties
 *.diff
 docs/_api
 !docs/_api/semver.__about__.rst
+
+# For node
+node_modules/
diff --git a/changelog.d/284.doc.rst b/changelog.d/284.doc.rst
@@ -0,0 +1 @@
+Document deprecation of :meth:`Version.isvalid`.
diff --git a/changelog.d/284.feature.rst b/changelog.d/284.feature.rst
@@ -0,0 +1,6 @@
+Implement :meth:`Version.is_compatible <semver.version.Version.is_compatible>` to make "is self compatible with X".
+
+Rename :meth:`Version.isvalid <semver.version.Version.isvalid>`
+to :meth:`Version.is_valid <semver.version.Version.is_valid>`
+for consistency reasons and deprecate the use of
+:meth:`Version.isvalid`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -118,8 +118,8 @@ def find_version(*file_paths):
 # Markup to shorten external links
 # See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
-    "gh": ("https://github.com/python-semver/python-semver/issues/%s", "#"),
-    "pr": ("https://github.com/python-semver/python-semver/pull/%s", "PR #"),
+    "gh": ("https://github.com/python-semver/python-semver/issues/%s", "#%s"),
+    "pr": ("https://github.com/python-semver/python-semver/pull/%s", "PR #%s"),
 }
 
 # -- Options for HTML output ----------------------------------------------
diff --git a/docs/migration/migratetosemver3.rst b/docs/migration/migratetosemver3.rst
@@ -3,8 +3,9 @@
 Migrating from semver2 to semver3
 =================================
 
-This document describes the visible differences for
+This section describes the visible differences for
 users and how your code stays compatible for semver3.
+Some changes are backward incompatible.
 
 Although the development team tries to make the transition
 to semver3 as smooth as possible, at some point change
@@ -34,9 +35,16 @@ Use semver.cli instead of semver
 --------------------------------
 
 All functions related to CLI parsing are moved to :mod:`semver.cli`.
-If you are such functions, like :func:`semver.cmd_bump <semver.cli.cmd_bump>`,
+If you need such functions, like :func:`semver.cmd_bump <semver.cli.cmd_bump>`,
 import it from :mod:`semver.cli` in the future:
 
 .. code-block:: python
 
    from semver.cli import cmd_bump
+
+
+Use semver.Version.is_valid instead of semver.Version.isvalid
+-------------------------------------------------------------
+
+The pull request :pr:`284` introduced the method :meth:`Version.is_compatible <semver.Version.is_compatible>`. To keep consistency, the development team
+decided to rename the :meth:`isvalid <semver.Version.isvalid>` to :meth:`is_valid <semver.Version.is_valid>`.
diff --git a/docs/usage/check-compatible-semver-version.rst b/docs/usage/check-compatible-semver-version.rst
@@ -0,0 +1,55 @@
+Checking for a Compatible Semver Version
+========================================
+
+In case you need to check if a semver version is compatible
+with another semver version, use :meth:`Version.is_compatible <semver.Version.is_compatible>`.
+
+A version `a` is compatible with another version `b` if:
+
+* Both are of type :class:`Version <semver.version.Version>`.
+* If the two majors parts are different, it's incompatible.
+* If the two major parts are equal, but the minor of `b` is
+  lower than `a`, it's incompatible.
+* If both pre-releases are present and different, it's incompatible.
+* In all other cases, it's compatible.
+
+Keep in mind, the method *does not* check patches!
+
+
+.. code-block:: python
+
+    # Two different majors:
+    >>> a = Version(1, 1, 1) # This is "A"
+    >>> b = Version(2, 0, 0) # This is "B"
+    >>> a.is_compatible(b)
+    False
+
+    # The same two majors and minors:
+    >>> b = Version(1, 1, 0) # This is another "B"
+    >>> a.is_compatible(b)
+    True
+
+    # The same two majors, but B.minor < A.minor:
+    >>> b = Version(1, 0, 0) # This is another "B"
+    >>> a.is_compatible(b)
+    False
+
+    # Checking compatibility between release and pre-release:
+    >>> b = Version(1,0,0,'rc1.')
+    >>> a.is_compatible(b)
+    False
+
+    # But pre-release and release:
+    >>> b.is_compatible(a)
+    False
+
+All major zero versions are incompatible with anything but itself:
+
+.. code-block:: python
+
+    >>> Version(0,1,0).is_compatible(Version(0,1,1))
+    False
+
+    # Only identical versions are compatible for major zero versions:
+    >>> Version(0,1,0).is_compatible(Version(0,1,0))
+    True
diff --git a/docs/usage/check-valid-semver-version.rst b/docs/usage/check-valid-semver-version.rst
@@ -6,7 +6,7 @@ classmethod :func:`Version.isvalid <semver.version.Version.isvalid>`:
 
 .. code-block:: python
 
-    >>> Version.isvalid("1.0.0")
+    >>> Version.is_valid("1.0.0")
     True
-    >>> Version.isvalid("invalid")
+    >>> Version.is_valid("invalid")
     False
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
@@ -8,6 +8,7 @@ Using semver
    create-a-version
    parse-version-string
    check-valid-semver-version
+   check-compatible-semver-version
    access-parts-of-a-version
    access-parts-through-index
    replace-parts-of-a-version
diff --git a/src/semver/cli.py b/src/semver/cli.py
@@ -54,7 +54,7 @@ def cmd_check(args: argparse.Namespace) -> None:
 
     :param args: The parsed arguments
     """
-    if Version.isvalid(args.version):
+    if Version.is_valid(args.version):
         return None
     raise ValueError("Invalid version %r" % args.version)
 
diff --git a/src/semver/version.py b/src/semver/version.py
@@ -645,7 +645,7 @@ def replace(self, **parts: Union[int, Optional[str]]) -> "Version":
             raise TypeError(error)
 
     @classmethod
-    def isvalid(cls, version: str) -> bool:
+    def is_valid(cls, version: str) -> bool:
         """
         Check if the string is a valid semver version.
 
@@ -661,6 +661,42 @@ def isvalid(cls, version: str) -> bool:
         except ValueError:
             return False
 
+    def is_compatible(self, new: 'Version') -> bool:
+        """
+        Check if current version is compatible with new.
+
+        The algorithm checks:
+
+        * if the two majors are different, it's incompatible
+        * if the two majors are equal, but the minor of ``new``
+          is lower than self.minor, it's incompatible
+        * if both pre-releases are present and different,
+          it's incompatible
+        * otherwise it's compatible
+
+        The algorithm does *not* check patches.
+
+        :param new: the new version to check for compatibility
+        :return: True, if new is compatible with the old version,
+                 otherwise False
+        """
+        if not (
+            isinstance(new, Version)
+        ):
+            raise TypeError(
+                f"Expected a Version type but got {type(new)}"
+            )
+
+        # All major-0 versions should be incompatible with anything but itself
+        if (0 == self.major == new.major) and (self[:4] != new[:4]):
+            return False
+
+        return (
+            (self.major == new.major)
+            and (new.minor >= self.minor)
+            and (self.prerelease == new.prerelease)
+        )
+
 
 #: Keep the VersionInfo name for compatibility
 VersionInfo = Version
diff --git a/tests/test_semver.py b/tests/test_semver.py
@@ -73,10 +73,65 @@ def test_should_be_able_to_use_integers_as_prerelease_build():
 
 
 def test_should_versioninfo_isvalid():
-    assert Version.isvalid("1.0.0") is True
-    assert Version.isvalid("foo") is False
+    assert Version.is_valid("1.0.0") is True
+    assert Version.is_valid("foo") is False
 
 
 def test_versioninfo_compare_should_raise_when_passed_invalid_value():
     with pytest.raises(TypeError):
         Version(1, 2, 3).compare(4)
+
+
+@pytest.mark.parametrize(
+    "old, new",
+    [
+        ((1, 2, 3), (1, 2, 3)),
+        ((1, 2, 3), (1, 2, 4)),
+        ((1, 2, 4), (1, 2, 3)),
+        ((1, 2, 3, "rc.0"), (1, 2, 4, "rc.0")),
+        ((0, 1, 0), (0, 1, 0)),
+    ],
+)
+def test_should_succeed_compatible_match(old, new):
+    old = Version(*old)
+    new = Version(*new)
+    assert old.is_compatible(new)
+
+
+@pytest.mark.parametrize(
+    "old, new",
+    [
+        ((1, 1, 0), (1, 0, 0)),
+        ((2, 0, 0), (1, 5, 0)),
+        ((1, 2, 3, "rc.1"), (1, 2, 3, "rc.0")),
+        ((1, 2, 3, "rc.1"), (1, 2, 4, "rc.0")),
+        ((0, 1, 0), (0, 1, 1)),
+        ((1, 0, 0), (1, 0, 0, "rc1")),
+        ((1, 0, 0, "rc1"), (1, 0, 0)),
+    ]
+)
+def test_should_fail_compatible_match(old, new):
+    old = Version(*old)
+    new = Version(*new)
+    assert not old.is_compatible(new)
+
+
+@pytest.mark.parametrize(
+    "wrongtype",
+    [
+        "wrongtype",
+        dict(a=2),
+        list(),
+    ]
+)
+def test_should_fail_with_incompatible_type_for_compatible_match(wrongtype):
+    with pytest.raises(TypeError, match="Expected a Version type .*"):
+        v = Version(1, 2, 3)
+        v.is_compatible(wrongtype)
+
+
+def test_should_succeed_with_compatible_subclass_for_is_compatible():
+    class CustomVersion(Version):
+        ...
+
+    assert CustomVersion(1, 0, 0).is_compatible(Version(1, 0, 0))

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Document deprecation of :meth:`Version.isvalid`.