Improve deprecated decorator

tomschr · tomschr · commit 08c71eb68f2c · 2020-04-10T23:45:20.000+02:00
Allow optional arguments replace and version
diff --git a/semver.py b/semver.py
@@ -3,7 +3,8 @@
 
 import argparse
 import collections
-from functools import wraps
+from functools import wraps, partial
+import inspect
 import re
 import sys
 import warnings
@@ -28,35 +29,62 @@ def cmp(a, b):
         return (a > b) - (a < b)
 
 
-def deprecated(replace=None):
+def deprecated(func=None, replace=None, version=None, category=DeprecationWarning):
     """
     Decorates a function to output a deprecation warning.
 
-    :param str replace: the name of the function which the deprecated
-                        function should be replaced with
-
     This function will be removed once major version 4 of semver is
     released.
-    """
 
-    def decorator(func):
-        r = replace or func.__name__  # __qualname__
+    :param str replace: the function to replace (use the full qualified
+        name like ``semver.VersionInfo.bump_major``.
+    :param str version: the first version when this function was deprecated.
+    :param category: allow you to specify the deprecation warning class
+        of your choice. By default, it's  :class:`DeprecationWarning`, but
+        you can choose :class:`PendingDeprecationWarning``or a custom class.
+    """
 
+    def decorator():
         @wraps(func)
         def wrapper(*args, **kwargs):
-            msg = (
-                "Function 'semver.{f}' is deprecated. "
-                "Use the respective 'semver.VersionInfo.{r}' instead."
+            msg = ["Function 'semver.{f}' is deprecated."]
+
+            if version:
+                msg.append("Deprecated since version {v}.")
+
+            if replace:
+                msg.append("Use {r!r} instead.")
+            else:
+                msg.append("Use the respective 'semver.VersionInfo.{r}' instead.")
+
+            # warnings.simplefilter('always', category)
+            frame = inspect.currentframe().f_back
+
+            msg = " ".join(msg)
+            msg = msg.format(f=func.__name__, r=replace, v=version)
+            warnings.warn_explicit(
+                msg,
+                category=category,
+                # stacklevel=2,
+                filename=inspect.getfile(frame.f_code),
+                lineno=frame.f_lineno,
             )
-            warnings.warn(msg.format(f=func.__name__, r=r), category=DeprecationWarning)
+            # warnings.simplefilter('default', category)
+            # As recommended in the Python documentation
+            # https://docs.python.org/3/library/inspect.html#the-interpreter-stack
+            # better remove the interpreter stack:
+            del frame
             return func(*args, **kwargs)
 
         return wrapper
 
-    return decorator
+    if callable(func):
+        return decorator()
+    else:
+        return partial(deprecated, replace=replace, version=version, category=category)
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def parse(version):
     """
     Parse version to major, minor, patch, pre-release, build parts.
@@ -229,8 +257,10 @@ def to_dict(self):
         )
 
     # For compatibility reasons:
-    _astuple = deprecated("to_tuple")(to_tuple)
-    _asdict = deprecated("to_dict")(to_dict)
+    _astuple = deprecated(replace="semver.VersionInfo.to_tuple", version="2.9.2")(
+        to_tuple
+    )
+    _asdict = deprecated(replace="semver.VersionInfo.to_dict", version="2.9.2")(to_dict)
 
     def __iter__(self):
         """Implement iter(self)."""
@@ -450,7 +480,7 @@ def _to_dict(obj):
     return obj
 
 
-@deprecated("parse")
+@deprecated(replace="semver.VersionInfo.parse", version="2.9.2")
 def parse_version_info(version):
     """
     Parse version string to a VersionInfo instance.
@@ -640,7 +670,7 @@ def min_ver(ver1, ver2):
         return ver2
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def format_version(major, minor, patch, prerelease=None, build=None):
     """
     Format a version string according to the Semantic Versioning specification.
@@ -676,7 +706,7 @@ def _increment_string(string):
     return string
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def bump_major(version):
     """
     Raise the major part of the version string.
@@ -694,7 +724,7 @@ def bump_major(version):
     return str(VersionInfo.parse(version).bump_major())
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def bump_minor(version):
     """
     Raise the minor part of the version string.
@@ -712,7 +742,7 @@ def bump_minor(version):
     return str(VersionInfo.parse(version).bump_minor())
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def bump_patch(version):
     """
     Raise the patch part of the version string.
@@ -730,7 +760,7 @@ def bump_patch(version):
     return str(VersionInfo.parse(version).bump_patch())
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def bump_prerelease(version, token="rc"):
     """
     Raise the prerelease part of the version string.
@@ -749,7 +779,7 @@ def bump_prerelease(version, token="rc"):
     return str(VersionInfo.parse(version).bump_prerelease(token))
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def bump_build(version, token="build"):
     """
     Raise the build part of the version string.
@@ -768,7 +798,7 @@ def bump_build(version, token="build"):
     return str(VersionInfo.parse(version).bump_build(token))
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def finalize_version(version):
     """
     Remove any prerelease and build metadata from the version string.
@@ -790,7 +820,7 @@ def finalize_version(version):
     return str(verinfo.finalize_version())
 
 
-@deprecated()
+@deprecated(version="2.9.2")
 def replace(version, **parts):
     """
     Replace one or more parts of a version and return the new string.
