8000 Fix #284: implement "is_compatible" with method · python-semver/python-semver@753771d · GitHub
[go: up one dir, main page]
Skip to content

Commit 753771d

Browse files
tomschrLexicalitytlaferriererafalkrupinski
committed
Fix #284: implement "is_compatible" with method
* 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 <lexi@lexi.org.uk> Co-authored-by: Thomas Laferriere <tlaferriere@users.noreply.github.com> Co-authored-by: Raphael Krupinski <rafalkrupinski@users.noreply.github.com>
1 parent bf8757a commit 753771d

14 files changed

+178
-11
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,3 +268,6 @@ fabric.properties
268268

269269
docs/_api
270270
!docs/_api/semver.__about__.rst
271+
272+
# For node
273+
node_modules/

‎changelog.d/284.deprecation.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Deprecate the use of :meth:`Version.isvalid`.
2+
3+
Rename :meth:`Version.isvalid <semver.version.Version.isvalid>`
4+
to :meth:`Version.is_valid <semver.version.Version.is_valid>`
5+
for consistency reasons with :meth:`Version.is_compatible <semver.version.Version.is_compatible>`

‎changelog.d/284.doc.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Document deprecation of :meth:`Version.isvalid`.

‎changelog.d/284.feature.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Implement :meth:`Version.is_compatible <semver.version.Version.is_compatible>` to make "is self compatible with X".

‎docs/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,8 @@ def find_version(*file_paths):
118118
# Markup to shorten external links
119119
# See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
120120
extlinks = {
121-
"gh": ("https://github.com/python-semver/python-semver/issues/%s", "#"),
122-
"pr": ("https://github.com/python-semver/python-semver/pull/%s", "PR #"),
121+
"gh": ("https://github.com/python-semver/python-semver/issues/%s", "#%s"),
122+
"pr": ("https://github.com/python-semver/python-semver/pull/%s", "PR #%s"),
123123
}
124124

125125
# -- Options for HTML output ----------------------------------------------

‎docs/migration/migratetosemver3.rst

Lines changed: 10 additions & 2 deletions
< 9E88 /tr>
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,9 @@
33
Migrating from semver2 to semver3
44
=================================
55

6-
This document describes the visible differences for
6+
This section describes the visible differences for
77
users and how your code stays compatible for semver3.
8+
Some changes are backward incompatible.
89

910
Although the development team tries to make the transition
1011
to semver3 as smooth as possible, at some point change
@@ -34,9 +35,16 @@ Use semver.cli instead of semver
3435
--------------------------------
3536

3637
All functions related to CLI parsing are moved to :mod:`semver.cli`.
37-
If you are such functions, like :func:`semver.cmd_bump <semver.cli.cmd_bump>`,
38+
If you need such functions, like :func:`semver.cmd_bump <semver.cli.cmd_bump>`,
3839
import it from :mod:`semver.cli` in the future:
3940

4041
.. code-block:: python
4142
4243
from semver.cli import cmd_bump
44+
45+
46+
Use semver.Version.is_valid instead of semver.Version.isvalid
47+
-------------------------------------------------------------
48+
49+
The pull request :pr:`284` introduced the method :meth:`Version.is_compatible <semver.Version.is_compatible>`. To keep consistency, the development team
50+
decided to rename the :meth:`isvalid <semver.Version.isvalid>` to :meth:`is_valid <semver.Version.is_valid>`.

‎docs/migration/replace-deprecated-functions.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ them with code which is compatible for future versions:
3131
3232
Likewise with the other module level functions.
3333

34+
* :func:`semver.Version.isvalid`
35+
36+
Replace it with :meth:`semver.Version.is_valid`:
37+
38+
3439
* :func:`semver.finalize_version`
3540

3641
Replace it with :func:`semver.Version.finalize_version`:

‎docs/usage/check-compatible-semver-version.rst

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Checking for a Compatible Semver Version
2+
========================================
3+
4+
If you need to check if a semver version is compatible
5+
with another semver version, use :meth:`Version.is_compatible <semver.Version.is_compatible>`.
6+
7+
A version `a` is compatible with another version `b` if:
8+
9+
* Both types are of type :class:`Version <semver.version.Version>`.
10+
* The two majors parts equal.
11+
* The two major parts are equal and the minor of ``a`` is lower
12+
than the minor of ``b``.
13+
* Both pre-releases are present and equal.
14+
15+
In all other cases, it's incompatible.
16+
17+
Keep in mind, the method *does not* check patches!
18+
19+
20+
.. code-block:: python
21+
22+
# Two different majors:
23+
>>> a = Version(1, 1, 1) # This is "A"
24+
>>> b = Version(2, 0, 0) # This is "B"
25+
>>> a.is_compatible(b)
26+
False
27+
28+
# The same two majors and minors:
29+
>>> b = Version(1, 1, 0) # This is another "B"
30+
>>> a.is_compatible(b)
31+
True
32+
33+
# The same two majors, but B.minor < A.minor:
34+
>>> b = Version(1, 0, 0) # This is another "B"
35+
>>> a.is_compatible(b)
36+
False
37+
38+
# Checking compatibility between release and pre-release:
39+
>>> b = Version(1,0,0,'rc1.')
40+
>>> a.is_compatible(b)
41+
False
42+
43+
# But pre-release and release:
44+
>>> b.is_compatible(a)
45+
False
46+
47+
All major zero versions are incompatible with anything but itself:
48+
49+
.. code-block:: python
50+
51+
>>> Version(0,1,0).is_compatible(Version(0,1,1))
52+
False
53+
54+
# Only identical versions are compatible for major zero versions:
55+
>>> Version(0,1,0).is_compatible(Version(0,1,0))
56+
True

‎docs/usage/check-valid-semver-version.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ classmethod :func:`Version.isvalid <semver.version.Version.isvalid>`:
66

77
.. code-block:: python
88
9-
>>> Version.isvalid("1.0.0")
9+
>>> Version.is_valid("1.0.0")
1010
True
11-
>>> Version.isvalid("invalid")
11+
>>> Version.is_valid("invalid")
1212
False

‎docs/usage/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Using semver
88
create-a-version
99
parse-version-string
1010
check-valid-semver-version
11+
check-compatible-semver-version
1112
access-parts-of-a-version
1213
access-parts-through-index
1314
replace-parts-of-a-version

‎src/semver/cli.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ def cmd_check(args: argparse.Namespace) -> None:
5454
5555
:param args: The parsed arguments
5656
"""
57-
if Version.isvalid(args.version):
57+
if Version.is_valid(args.version):
5858
return None
5959
raise ValueError("Invalid version %r" % args.version)
6060

‎src/semver/version.py

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -642,7 +642,7 @@ def replace(self, **parts: Union[int, Optional[str]]) -> "Version":
642642
raise TypeError(error)
643643

644644
@classmethod
645-
def isvalid(cls, version: str) -> bool:
645+
def is_valid(cls, version: str) -> bool:
646646
"""
647647
Check if the string is a valid semver version.
648648
@@ -658,6 +658,38 @@ def isvalid(cls, version: str) -> bool:
658658
except ValueError:
659659
return False
660660

661+
def is_compatible(self, other: "Version") -> bool:
662+
"""
663+
Check if current version is compatible with other version.
664+
665+
The algorithm checks:
666+
667+
* if the two majors are different, it's incompatible
668+
* if the two majors are equal, but the minor of ``other``
669+
is lower than self.minor, it's incompatible
670+
* if both pre-releases are present and different,
671+
it's incompatible
672+
* otherwise it's compatible
673+
674+
The algorithm does *not* check patches.
675+
676+
:param other: the version to check for compatibility
677+
:return: True, if ``other`` is compatible with the old version,
678+
otherwise False
679+
"""
680+
if not isinstance(other, Version):
681+
raise TypeError(f"Expected a Version type but got {type(other)}")
682+
683+
# All major-0 versions should be incompatible with anything but itself
684+
if (0 == self.major == other.major) and (self[:4] != other[:4]):
685+
return False
686+
687+
return (
688+
(self.major == other.major)
689+
and (other.minor >= self.minor)
690+
and (self.prerelease == other.prerelease)
691+
)
692+
661693

662694
#: Keep the VersionInfo name for compatibility
663695
VersionInfo = Version

‎tests/test_semver.py

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,65 @@ def test_should_be_able_to_use_integers_as_prerelease_build():
7373

7474

7575
def test_should_versioninfo_isvalid():
76-
assert Version.isvalid("1.0.0") is True
77-
assert Version.isvalid("foo") is False
76+
assert Version.is_valid("1.0.0") is True
77+
assert Version.is_valid("foo") is False
7878

7979

8080
def test_versioninfo_compare_should_raise_when_passed_invalid_value():
8181
with pytest.raises(TypeError):
8282
Version(1, 2, 3).compare(4)
83+
84+
85+
@pytest.mark.parametrize(
86+
"old, new",
87+
[
88+
((1, 2, 3), (1, 2, 3)),
89+
((1, 2, 3), (1, 2, 4)),
90+
((1, 2, 4), (1, 2, 3)),
91+
((1, 2, 3, "rc.0"), (1, 2, 4, "rc.0")),
92+
((0, 1, 0), (0, 1, 0)),
93+
],
94+
)
95+
def test_should_succeed_compatible_match(old, new):
96+
old = Version(*old)
97+
new = Version(*new)
98+
assert old.is_compatible(new)
99+
100+
101+
@pytest.mark.parametrize(
102+
"old, new",
103+
[
104+
((1, 1, 0), (1, 0, 0)),
105+
((2, 0, 0), (1, 5, 0)),
106+
((1, 2, 3, "rc.1"), (1, 2, 3, "rc.0")),
107+
((1, 2, 3, "rc.1"), (1, 2, 4, "rc.0")),
108+
((0, 1, 0), (0, 1, 1)),
109+
((1, 0, 0), (1, 0, 0, "rc1")),
110+
((1, 0, 0, "rc1"), (1, 0, 0)),
111+
],
112+
)
113+
def test_should_fail_compatible_match(old, new):
114+
old = Version(*old)
115+
new = Version(*new)
116+
assert not old.is_compatible(new)
117+
118+
119+
@pytest.mark.parametrize(
120+
"wrongtype",
121+
[
122+
"wrongtype",
123+
dict(a=2),
124+
list(),
125+
],
126+
)
127+
def test_should_fail_with_incompatible_type_for_compatible_match(wrongtype):
128+
with pytest.raises(TypeError, match="Expected a Version type .*"):
129+
v = Version(1, 2, 3)
130+
v.is_compatible(wrongtype)
131+
132+
133+
def test_should_succeed_with_compatible_subclass_for_is_compatible():
134+
class CustomVersion(Version):
135+
...
136+
137+
assert CustomVersion(1, 0, 0).is_compatible(Version(1, 0, 0))

‎tox.ini

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ python =
1818

1919
[testenv]
2020
description = Run test suite for {basepython}
21-
allowlist_externals = make
2221
skip_install = true
22+
allowlist_externals = make
2323
commands = pytest {posargs:}
2424
deps =
2525
pytest

0 commit comments

Comments
 (0)
0