Fix #225: Deprecate module level functions

tomschr · tomschr · commit ac4b7ce4cd3f · 2020-04-10T10:48:04.000+02:00
* Add test cases
* In `setup.cfg`, add deprecation warnings filter for pytest
* Implement DeprecationWarning with warnings module and
  the new decorator `deprecated`
* Output a DeprecationWarning for the following functions:
  - semver.parse
  - semver.parse_version_info
  - semver.format_version
  - semver.bump_{major,minor,patch,prerelease,build}
  - semver.finalize_version
  - semver.replace
  Add also a deprecation notice in the docstrings of these
  functions
* Update CHANGELOG.rst
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -18,8 +18,12 @@ Features
 Bug Fixes
 ---------
 
+<<<<<<< HEAD
 * :gh:`224` (:pr:`226`): In ``setup.py``, replaced in class ``clean``,
   ``super(CleanCommand, self).run()`` with ``CleanCommand.run(self)``
+=======
+* :gh:`224` (:pr:`226`): Replaced in class ``clean``, ``super(CleanCommand, self).run()`` with ``CleanCommand.run(self)``
+>>>>>>> Fix #225: Deprecate module level functions
 
 
 Additions
@@ -29,6 +33,17 @@ Additions
 
 Removals
 --------
+* :gh:`225` (:pr:`229`): Output a DeprecationWarning for the following functions:
+
+  - ``semver.parse``
+  - ``semver.parse_version_info``
+  - ``semver.format_version``
+  - ``semver.bump_{major,minor,patch,prerelease,build}``
+  - ``semver.finalize_version``
+  - ``semver.replace``
+
+  These functions will be removed in major 3 of semver.
+
 
 
 Version 2.9.1
diff --git a/semver.py b/semver.py
@@ -6,6 +6,7 @@
 from functools import wraps
 import re
 import sys
+import warnings
 
 
 __version__ = "2.9.1"
@@ -27,10 +28,44 @@ def cmp(a, b):
         return (a > b) - (a < b)
 
 
+def deprecated(replace=None):
+    """
+    Decorates a function to output a deprecation warning.
+
+    This function will be removed once major version 3 of semver is
+    released.
+    """
+    # we can't use the 'nonlocal' keyword in Python2, so we need
+    # to circumvent that with a dictionary:
+    r = {"r": replace}
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # nonlocal replace
+            replace = r["r"] if r["r"] is not None else func.__name__
+            msg = (
+                "Function 'semver.{f}' is deprecated. "
+                "Use the respective 'semver.VersionInfo.{r}' instead."
+            )
+            warnings.warn(
+                msg.format(f=func.__name__, r=replace), category=DeprecationWarning
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+@deprecated()
 def parse(version):
     """
     Parse version to major, minor, patch, pre-release, build parts.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.format_parse` instead.
+
     :param version: version string
     :return: dictionary with the keys 'build', 'major', 'minor', 'patch',
              and 'prerelease'. The prerelease or build keys can be None
@@ -186,7 +221,7 @@ def bump_major(self):
         VersionInfo(major=4, minor=0, patch=0, prerelease=None, build=None)
         """
         cls = type(self)
-        return cls(self._major+1)
+        return cls(self._major + 1)
 
     def bump_minor(self):
         """
@@ -201,7 +236,7 @@ def bump_minor(self):
         VersionInfo(major=3, minor=5, patch=0, prerelease=None, build=None)
         """
         cls = type(self)
-        return cls(self._major, self._minor+1)
+        return cls(self._major, self._minor + 1)
 
     def bump_patch(self):
         """
@@ -216,7 +251,7 @@ def bump_patch(self):
         VersionInfo(major=3, minor=4, patch=6, prerelease=None, build=None)
         """
         cls = type(self)
-        return cls(self._major, self._minor, self._patch+1)
+        return cls(self._major, self._minor, self._patch + 1)
 
     def bump_prerelease(self, token="rc"):
         """
@@ -233,9 +268,7 @@ def bump_prerelease(self, token="rc"):
 build=None)
         """
         cls = type(self)
-        prerelease = _increment_string(
-            self._prerelease or (token or "rc") + ".0"
-        )
+        prerelease = _increment_string(self._prerelease or (token or "rc") + ".0")
         return cls(self._major, self._minor, self._patch, prerelease)
 
     def bump_build(self, token="build"):
@@ -253,9 +286,7 @@ def bump_build(self, token="build"):
 build='build.10')
         """
         cls = type(self)
-        build = _increment_string(
-            self._build or (token or "build") + ".0"
-        )
+        build = _increment_string(self._build or (token or "build") + ".0")
         return cls(self._major, self._minor, self._patch, self._prerelease, build)
 
     @comparator
@@ -395,13 +426,17 @@ def _to_dict(obj):
     return obj
 
 
+@deprecated("parse")
 def parse_version_info(version):
     """
     Parse version string to a VersionInfo instance.
 
     .. versionadded:: 2.7.2
        Added :func:`parse_version_info`
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.parse` instead.
+
     :param version: version string
     :return: a :class:`VersionInfo` instance
     :rtype: :class:`VersionInfo`
@@ -578,10 +613,14 @@ def min_ver(ver1, ver2):
         return ver2
 
 
+@deprecated()
 def format_version(major, minor, patch, prerelease=None, build=None):
     """
     Format a version string according to the Semantic Versioning specification.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.format_version` instead.
+
     :param int major: the required major part of a version
     :param int minor: the required minor part of a version
     :param int patch: the required patch part of a version
@@ -610,10 +649,14 @@ def _increment_string(string):
     return string
 
 
+@deprecated()
 def bump_major(version):
     """
     Raise the major part of the version string.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.bump_major` instead.
+
     :param: version string
     :return: the raised version string
     :rtype: str
@@ -624,10 +667,14 @@ def bump_major(version):
     return str(VersionInfo.parse(version).bump_major())
 
 
+@deprecated()
 def bump_minor(version):
     """
     Raise the minor part of the version string.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.bump_minor` instead.
+
     :param: version string
     :return: the raised version string
     :rtype: str
@@ -638,10 +685,14 @@ def bump_minor(version):
     return str(VersionInfo.parse(version).bump_minor())
 
 
+@deprecated()
 def bump_patch(version):
     """
     Raise the patch part of the version string.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.bump_patch` instead.
+
     :param: version string
     :return: the raised version string
     :rtype: str
@@ -652,10 +703,14 @@ def bump_patch(version):
     return str(VersionInfo.parse(version).bump_patch())
 
 
+@deprecated()
 def bump_prerelease(version, token="rc"):
     """
     Raise the prerelease part of the version string.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.bump_prerelease` instead.
+
     :param version: version string
     :param token: defaults to 'rc'
     :return: the raised version string
@@ -667,10 +722,14 @@ def bump_prerelease(version, token="rc"):
     return str(VersionInfo.parse(version).bump_prerelease(token))
 
 
+@deprecated()
 def bump_build(version, token="build"):
     """
     Raise the build part of the version string.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.bump_build` instead.
+
     :param version: version string
     :param token: defaults to 'build'
     :return: the raised version string
@@ -682,13 +741,17 @@ def bump_build(version, token="build"):
     return str(VersionInfo.parse(version).bump_build(token))
 
 
+@deprecated()
 def finalize_version(version):
     """
     Remove any prerelease and build metadata from the version string.
 
     .. versionadded:: 2.7.9
        Added :func:`finalize_version`
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.bump_format_version` instead.
+
     :param version: version string
     :return: the finalized version string
     :rtype: str
@@ -700,10 +763,14 @@ def finalize_version(version):
     return VersionInfo.format_version(verinfo.major, verinfo.minor, verinfo.patch)
 
 
+@deprecated()
 def replace(version, **parts):
     """
     Replace one or more parts of a version and return the new string.
 
+    .. deprecated:: 2.9.2
+       Use :func:`semver.VersionInfo.replace` instead.
+
     :param str version: the version string to replace
     :param dict parts: the parts to be updated. Valid keys are:
       ``major``, ``minor``, ``patch``, ``prerelease``, or ``build``
diff --git a/setup.cfg b/setup.cfg
@@ -1,6 +1,8 @@
 [tool:pytest]
 norecursedirs = .git build .env/ env/ .pyenv/ .tmp/ .eggs/
 testpaths = . docs
+filterwarnings =
+    ignore:Function 'semver.*:DeprecationWarning
 addopts =
     --no-cov-on-fail
     --cov=semver
diff --git a/test_semver.py b/test_semver.py
@@ -827,3 +827,22 @@ def test_replace_raises_ValueError_for_non_numeric_values():
 def test_should_versioninfo_isvalid():
     assert VersionInfo.isvalid("1.0.0") is True
     assert VersionInfo.isvalid("foo") is False
+
+
+@pytest.mark.parametrize(
+    "func, args, kwargs",
+    [
+        (bump_build, ("1.2.3",), {}),
+        (bump_major, ("1.2.3",), {}),
+        (bump_minor, ("1.2.3",), {}),
+        (bump_patch, ("1.2.3",), {}),
+        (bump_prerelease, ("1.2.3",), {}),
+        (format_version, (3, 4, 5), {}),
+        (parse, ("1.2.3",), {}),
+        (parse_version_info, ("1.2.3",), {}),
+        (replace, ("1.2.3",), dict(major=2, patch=10)),
+    ],
+)
+def test_should_raise_deprecation_warnings(func, args, kwargs):
+    with pytest.deprecated_call():
+        func(*args, **kwargs)
