Deprecate max_ver and min_ver (#264)

tlaferriere · tomschr · web-flow · commit 772a7a61a6e4 · 2020-06-15T17:32:28.000+02:00
* Deprecate functions max_ver and min_ver

* Fix typos in docs

* Document use of builtins max() and min()

* Fix bad doc link and change section name

* Improve documentation with examples of how to use the builtin max and min. Keep the old way of doing for reference.

* Test that max_ver and min_ver are deprecated.

* Add deprecation to CHANGELOG.rst

* Rename removals to deprecations and clean up the CHANGELOG.rst


Co-authored-by: Tom Schraitle &lt;tomschr@users.noreply.github.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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):

Original file line number	Diff line number	Diff line change
`@@ -1036,6 +1036,8 @@ def test_should_versioninfo_isvalid():`
`1036`	`1036`	`(parse, ("1.2.3",), {}),`
`1037`	`1037`	`(parse_version_info, ("1.2.3",), {}),`
`1038`	`1038`	`(replace, ("1.2.3",), dict(major=2, patch=10)),`
	`1039`	`+ (max_ver, ("1.2.3", "1.2.4"), {}),`
	`1040`	`+ (min_ver, ("1.2.3", "1.2.4"), {}),`
`1039`	`1041`	`],`
`1040`	`1042`	`)`
`1041`	`1043`	`def test_should_raise_deprecation_warnings(func, args, kwargs):`