diff --git a/docs/usage.rst b/docs/usage.rst index b61e2847..be40c86c 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -11,9 +11,9 @@ are met. Knowing the Implemented semver.org Version ------------------------------------------ -The semver.org page is the authorative specification of how semantical -versioning is definied. -To know which version of semver.org is implemented in the semver libary, +The semver.org page is the authoritative specification of how semantic +versioning is defined. +To know which version of semver.org is implemented in the semver library, use the following constant:: >>> semver.SEMVER_SPEC_VERSION @@ -445,7 +445,11 @@ To compare two versions depends on your type: Other types cannot be compared. -If you need to convert some types into other, refer to :ref:`sec.convert.versions`. +If you need to convert some types into others, refer to :ref:`sec.convert.versions`. + +The use of these comparison operators also implies that you can use builtin +functions that leverage this capability; builtins including, but not limited to: :func:`max`, :func:`min` +(for examples, see :ref:`sec_max_min`) and :func:`sorted`. @@ -476,17 +480,30 @@ That gives you the following possibilities to express your condition: >>> semver.match("1.0.0", ">1.0.0") False +.. _sec_max_min: -Getting Minimum and Maximum of two Versions +Getting Minimum and Maximum of Multiple Versions ------------------------------------------- +.. versionchanged:: 2.10.2 + The functions :func:`semver.max_ver` and :func:`semver.min_ver` are deprecated in + favor of their builtin counterparts :func:`max` and :func:`min`. + +Since :class:`semver.VersionInfo` implements :func:`__gt__()` and :func:`__lt__()`, it can be used with builtins requiring .. code-block:: python - >>> semver.max_ver("1.0.0", "2.0.0") + >>> str(max(semver.VersionInfo.parse("1.0.0"), semver.VersionInfo.parse("2.0.0"))) '2.0.0' - >>> semver.min_ver("1.0.0", "2.0.0") + >>> str(min(semver.VersionInfo.parse("1.0.0"), semver.VersionInfo.parse("2.0.0"))) '1.0.0' +.. code-block:: python + + >>> max([semver.VersionInfo(0, 1, 0), semver.VersionInfo(0, 2, 0), semver.VersionInfo(0, 1, 3)]) + VersionInfo(major=0, minor=2, patch=0, prerelease=None, build=None) + >>> min([semver.VersionInfo(0, 1, 0), semver.VersionInfo(0, 2, 0), semver.VersionInfo(0, 1, 3)]) + VersionInfo(major=0, minor=1, patch=0, prerelease=None, build=None) + Dealing with Invalid Versions ----------------------------- diff --git a/test_semver.py b/test_semver.py index 015cb7d2..b5e5109c 100644 --- a/test_semver.py +++ b/test_semver.py @@ -409,20 +409,88 @@ def test_should_ignore_extensions_for_bump(): assert bump_patch("3.4.5-rc1+build4") == "3.4.6" -def test_should_get_max(): - assert max_ver("3.4.5", "4.0.2") == "4.0.2" - - -def test_should_get_max_same(): - assert max_ver("3.4.5", "3.4.5") == "3.4.5" - - -def test_should_get_min(): - assert min_ver("3.4.5", "4.0.2") == "3.4.5" - - -def test_should_get_min_same(): - assert min_ver("3.4.5", "3.4.5") == "3.4.5" +@pytest.mark.parametrize("func", (max_ver, min_ver)) +@pytest.mark.parametrize( + "args, expected", + [ + pytest.param( + ("1.2.3", "1.2.4"), + {"max_ver": "1.2.4", "min_ver": "1.2.3"}, + marks=[pytest.mark.xfail], + ), + pytest.param( + ( + {"major": 1, "minor": 2, "patch": 3}, + {"major": 1, "minor": 2, "patch": 4}, + ), + { + "max_ver": {"major": 1, "minor": 2, "patch": 4}, + "min_ver": {"major": 1, "minor": 2, "patch": 3}, + }, + marks=[pytest.mark.xfail], + ), + pytest.param( + ((1, 2, 3), (1, 2, 4)), + {"max_ver": (1, 2, 4), "min_ver": (1, 2, 3)}, + marks=[pytest.mark.xfail], + ), + pytest.param( + ("1.2.3", "1.2.4", "1.2.5"), + {"max_ver": "1.2.5", "min_ver": "1.2.3"}, + marks=[pytest.mark.xfail], + ), + pytest.param( + ( + {"major": 1, "minor": 2, "patch": 3}, + {"major": 1, "minor": 2, "patch": 4}, + {"major": 1, "minor": 2, "patch": 5}, + ), + { + "max_ver": {"major": 1, "minor": 2, "patch": 5}, + "min_ver": {"major": 1, "minor": 2, "patch": 3}, + }, + marks=[pytest.mark.xfail], + ), + pytest.param( + ((1, 2, 3), (1, 2, 4), (1, 2, 5)), + {"max_ver": (1, 2, 5), "min_ver": (1, 2, 3)}, + marks=[pytest.mark.xfail], + ), + pytest.param( + ((1, 2, 3), (1, 2, 4)), + {"max_ver": (1, 2, 4), "min_ver": (1, 2, 3)}, + marks=[pytest.mark.xfail], + ), + pytest.param( + (("1.2.3", "1.2.4", "1.2.5"),), + {"max_ver": "1.2.5", "min_ver": "1.2.3"}, + marks=[pytest.mark.xfail], + ), + pytest.param( + ( + ( + {"major": 1, "minor": 2, "patch": 3}, + {"major": 1, "minor": 2, "patch": 4}, + {"major": 1, "minor": 2, "patch": 5}, + ), + ), + { + "max_ver": {"major": 1, "minor": 2, "patch": 5}, + "min_ver": {"major": 1, "minor": 2, "patch": 3}, + }, + marks=[pytest.mark.xfail], + ), + pytest.param( + (((1, 2, 3), (1, 2, 4), (1, 2, 5)),), + {"max_ver": (1, 2, 5), "min_ver": (1, 2, 3)}, + marks=[pytest.mark.xfail], + ), + ], +) +def test_max_ver_and_min_ver(func, args, expected): + result = func(*args) + assert type(result) == type(expected) + assert result == expected[func.__name__] def test_should_get_more_rc1():