add depreciation.renamed to rename callable

2 files changed, 42 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.
diff --git a/test/unittest_deprecation.py b/test/unittest_deprecation.py
index be64e07..d82c2bc 100644
--- a/test/unittest_deprecation.py
+++ b/test/unittest_deprecation.py
@@ -71,6 +71,16 @@ class RawInputTC(TestCase):
         self.assertEqual(self.messages,
                          ['The function "any_func" is deprecated', 'message'])
 
+    def test_renamed(self):
+        def any_func():
+            pass
+
+        old_func = deprecation.renamed("old_func", any_func)
+        old_func()
+
+        self.assertEqual(self.messages,
+                         ['old_func has been renamed and is deprecated, uses any_func instead'])
+
     def test_moved(self):
         module = 'data.deprecation'
         any_func = deprecation.moved(module, 'moving_target')