add depreciation.renamed to rename callable

1 files changed, 32 insertions, 0 deletions

diff --git a/logilab/common/deprecation.py b/logilab/common/deprecation.py
index 1c81b63..3ad42d0 100644
--- a/logilab/common/deprecation.py
+++ b/logilab/common/deprecation.py
@@ -21,6 +21,7 @@ __docformat__ = "restructuredtext en"
 
 import sys
 from warnings import warn
+from functools import wraps
 
 from logilab.common.changelog import Version
 
@@ -115,6 +116,21 @@ class DeprecationManager(object):
             return getattr(m, objname)(*args, **kwargs)
         return callnew
 
+    def renamed(self, old_name, new_function):
+        """use to tell that a callable has been renamed.
+
+        It returns a callable wrapper, so that when its called a warning is printed
+        telling what is the object new name.
+        """
+        @wraps(new_function)
+        def wrapped(*args, **kwargs):
+            self.warn(None, (
+                f"{old_name} has been renamed and is deprecated, uses {new_function.__name__} "
+                f"instead"
+            ), stacklevel=3)
+            return new_function(*args, **kwargs)
+        return wrapped
+
     def class_renamed(self, version, old_name, new_class, message=None):
         clsdict = {}
         if message is None:
@@ -171,6 +187,22 @@ def moved(modpath, objname):
     return _defaultdeprecator.moved(None, modpath, objname)
 moved.__doc__ = _defaultdeprecator.moved.__doc__
 
+
+def renamed(old_name, new_function):
+    """use to tell that a callable has been renamed.
+
+    It returns a callable wrapper, so that when its called a warning is printed
+    telling what is the object new name.
+
+    >>> old_function = renamed('old_function', new_function)
+    >>> old_function()
+    sample.py:57: DeprecationWarning: old_function has been renamed and is deprecated, uses new_function instead
+    old_function()
+    >>>
+    """
+    return _defaultdeprecator.renamed(old_name, new_function)
+
+
 def class_renamed(old_name, new_class, message=None):
     """automatically creates a class which fires a DeprecationWarning
     when instantiated.