Fix #225: Deprecate module level functions

tomschr · tomschr · commit c2a5ce3f03f4 · 2020-03-15T21:28:11.000+01: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
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,6 +28,37 @@ 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.
@@ -186,7 +218,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 +233,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 +248,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 +265,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 +283,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
@@ -389,6 +417,7 @@ def _to_dict(obj):
     return obj
 
 
+@deprecated("parse")
 def parse_version_info(version):
     """
     Parse version string to a VersionInfo instance.
@@ -569,6 +598,7 @@ def min_ver(ver1, ver2):
         return ver2
 
 
+@deprecated()
 def format_version(major, minor, patch, prerelease=None, build=None):
     """
     Format a version according to the Semantic Versioning specification.
@@ -601,6 +631,7 @@ def _increment_string(string):
     return string
 
 
+@deprecated()
 def bump_major(version):
     """
     Raise the major part of the version.
@@ -615,6 +646,7 @@ def bump_major(version):
     return str(VersionInfo.parse(version).bump_major())
 
 
+@deprecated()
 def bump_minor(version):
     """
     Raise the minor part of the version.
@@ -629,6 +661,7 @@ def bump_minor(version):
     return str(VersionInfo.parse(version).bump_minor())
 
 
+@deprecated()
 def bump_patch(version):
     """
     Raise the patch part of the version.
@@ -643,6 +676,7 @@ 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.
@@ -658,6 +692,7 @@ 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.
@@ -673,6 +708,7 @@ 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.
@@ -688,6 +724,7 @@ 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.
diff --git a/setup.cfg b/setup.cfg
@@ -1,5 +1,7 @@
 [tool:pytest]
 norecursedirs = .git build .env/ env/ .pyenv/ .tmp/ .eggs/
+filterwarnings =
+    ignore:Function 'semver.*:DeprecationWarning
 addopts =
     --ignore=.eggs/
     --no-cov-on-fail
@@ -17,4 +19,4 @@ exclude =
     .git,
     __pycache__,
     build,
-    dist
+    dist
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)
