diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2671ef2e..4cd18b66 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -29,10 +29,12 @@ Additions n/a -Removals +Deprecations -------- -n/a +* :gh:`160` (:pr:`264`): + * :func:`semver.max_ver` + * :func:`semver.min_ver` Version 2.10.1 @@ -58,14 +60,6 @@ Bug Fixes to always return a ``VersionInfo`` instance. -Additions ---------- - - -Removals --------- - - Version 2.10.0 ============== @@ -95,7 +89,7 @@ Additions * :pr:`228`: Added better doctest integration -Removals +Deprecations -------- * :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions: @@ -139,12 +133,6 @@ Bug Fixes * :gh:`192` (:pr:`193`): Fixed "pysemver" and "pysemver bump" when called without arguments -Removals --------- - -not available - - Version 2.9.0 ============= :Released: 2019-10-30 @@ -184,7 +172,7 @@ Bug Fixes Removals -------- -* :gh:`111` (:pr:`110`): Droped Python 3.3 +* :gh:`111` (:pr:`110`): Dropped Python 3.3 * :gh:`148` (:pr:`149`): Removed and replaced ``python setup.py test`` diff --git a/docs/usage.rst b/docs/usage.rst index b61e2847..2f23e571 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,9 +480,47 @@ 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 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 + + >>> 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) + +Incidentally, using :func:`map`, you can get the min or max version of any number of versions of the same type +(convertible to :class:`semver.VersionInfo`). + +For example, here are the maximum and minimum versions of a list of version strings: + +.. code-block:: python + + >>> str(max(map(semver.VersionInfo.parse, ['1.1.0', '1.2.0', '2.1.0', '0.5.10', '0.4.99']))) + '2.1.0' + >>> str(min(map(semver.VersionInfo.parse, ['1.1.0', '1.2.0', '2.1.0', '0.5.10', '0.4.99']))) + '0.4.99' + +And the same can be done with tuples: + +.. code-block:: python + + >>> max(map(lambda v: semver.VersionInfo(*v), [(1, 1, 0), (1, 2, 0), (2, 1, 0), (0, 5, 10), (0, 4, 99)])).to_tuple() + (2, 1, 0, None, None) + >>> min(map(lambda v: semver.VersionInfo(*v), [(1, 1, 0), (1, 2, 0), (2, 1, 0), (0, 5, 10), (0, 4, 99)])).to_tuple() + (0, 4, 99, None, None) -Getting Minimum and Maximum of two Versions -------------------------------------------- +For dictionaries, it is very similar to finding the max version tuple: see :ref:`sec.convert.versions`. + +The "old way" with :func:`semver.max_ver` or :func:`semver.min_ver` is still available, but not recommended: .. code-block:: python @@ -575,6 +617,28 @@ them with code which is compatible for future versions: >>> s1 == s2 True +* :func:`semver.max_ver` + + Replace it with ``max(version1, version2, ...)`` or ``max([version1, version2, ...])``: + + .. code-block:: python + + >>> s1 = semver.max_ver("1.2.3", "1.2.4") + >>> s2 = str(max(map(semver.VersionInfo.parse, ("1.2.3", "1.2.4")))) + >>> s1 == s2 + True + +* :func:`semver.min_ver` + + Replace it with ``min(version1, version2, ...)`` or ``min([version1, version2, ...])``: + + .. code-block:: python + + >>> s1 = semver.min_ver("1.2.3", "1.2.4") + >>> s2 = str(min(map(semver.VersionInfo.parse, ("1.2.3", "1.2.4")))) + >>> s1 == s2 + True + * :func:`semver.parse` Replace it with :func:`semver.VersionInfo.parse` and diff --git a/semver.py b/semver.py index 0c98af97..2571684c 100644 --- a/semver.py +++ b/semver.py @@ -812,6 +812,7 @@ def match(version, match_expr): return ver.match(match_expr) +@deprecated(replace="max", version="2.10.2") def max_ver(ver1, ver2): """ Returns the greater version of two versions strings. @@ -835,6 +836,7 @@ def max_ver(ver1, ver2): return ver2 +@deprecated(replace="min", version="2.10.2") def min_ver(ver1, ver2): """ Returns the smaller version of two versions strings. diff --git a/test_semver.py b/test_semver.py index 015cb7d2..b23576d5 100644 --- a/test_semver.py +++ b/test_semver.py @@ -1036,6 +1036,8 @@ def test_should_versioninfo_isvalid(): (parse, ("1.2.3",), {}), (parse_version_info, ("1.2.3",), {}), (replace, ("1.2.3",), dict(major=2, patch=10)), + (max_ver, ("1.2.3", "1.2.4"), {}), + (min_ver, ("1.2.3", "1.2.4"), {}), ], ) def test_should_raise_deprecation_warnings(func, args, kwargs):