[gnue] r9765 - trunk/gnue-common/src/base

[reinhard]

Author: reinhard
Date: 2007-07-24 15:56:18 -0500 (Tue, 24 Jul 2007)
New Revision: 9765

Modified:
   trunk/gnue-common/src/base/log.py
Log:
Added function decorators to declare function as deprecated.


Modified: trunk/gnue-common/src/base/log.py
===================================================================
--- trunk/gnue-common/src/base/log.py   2007-07-24 20:40:03 UTC (rev 9764)
+++ trunk/gnue-common/src/base/log.py   2007-07-24 20:56:18 UTC (rev 9765)
@@ -35,12 +35,14 @@
 
 from gnue.common.base import utils
 
-__all__ = ['logged_f', 'logged_f_n', 'debug', 'info', 'warning', 'deprecated',
-        'error', 'critical', 'exception', 'debug_n', 'info_n', 'warning_n',
-        'deprecated_n', 'error_n', 'critical_n', 'exception_n']
+__all__ = ['logged_f', 'deprecated_f',
+        'logged_f_n', 'deprecated_f_n',
+        'debug', 'info', 'warning', 'deprecated', 'error', 'critical',
+        'exception',
+        'debug_n', 'info_n', 'warning_n', 'deprecated_n', 'error_n',
+        'critical_n', 'exception_n']
 
 # TODO:
-# - function to declare function as deprecated, maybe as decorator?
 # - Exception hook
 # - allow for __gnue_logger__ module global variable to use as a logger name
 #   instead of the module name (make a function in utils.py to search and cache
@@ -48,7 +50,7 @@
 
 
 # -----------------------------------------------------------------------------
-# Log function entry and exit
+# Function decorators
 # -----------------------------------------------------------------------------
 
 def logged_f(func):
@@ -83,6 +85,36 @@
 
 # -----------------------------------------------------------------------------
 
+def deprecated_f(func):
+    """
+    Decorator to mark a function as deprecated.
+
+    If this decorator is applied to a function, every call to that function
+    issues a deprecation warning.
+
+    Usage with Python 2.4 or later::
+        @deprecated_f
+        myfunction(self, foo, bar):
+            :
+
+    Usage with Python 2.3::
+        myfunction(self, foo, bar):
+            :
+        myfunction=deprecated_f(myfunction)
+
+    @param func: Function to put the deprecation warning wrapper around.
+    @type func: function
+    @return: Function with the deprecation warning wrapper.
+    @rtype: function
+    """
+    def __new_f(*args, **kwargs):
+        name = func.func_globals['__name__']
+        __deprecated(name, func)
+        return func(*args, **kwargs)
+    return __new_f
+
+# -----------------------------------------------------------------------------
+
 def logged_f_n(name):
     """
     Decorator to activate logging for a function using a specific logger.
@@ -118,6 +150,39 @@
 
 # -----------------------------------------------------------------------------
 
+def deprecated_f_n(name):
+    """
+    Decorator to mark a function as deprecated using a specific logger.
+
+    If this decorator is applied to a function, every call to that function
+    issues a deprecation warning.
+
+    Usage with Python 2.4 or later::
+        @deprecated_f_n('my.logger.name')
+        myfunction(self, foo, bar):
+            :
+
+    Usage with Python 2.3::
+        myfunction(self, foo, bar):
+            :
+        myfunction=deprecated_f_n('my.logger.name')(myfunction)
+
+    @param name: Logger name to use.
+    @type name: string
+    @return: A function that accepts a function as argument and returns the
+        function with a deprecation warning wrapper around it (look at the
+        usage example above to understand this).
+    @rtype: function
+    """
+    def __deprecated_f(func):
+        def __new_f(*args, **kwargs):
+            __deprecated(name, func)
+            return func(*args, **kwargs)
+        return __new_f
+    return __deprecated_f
+
+# -----------------------------------------------------------------------------
+
 def __enter(name, func):
 
     # Get the caller's frame
@@ -186,10 +251,31 @@
   
 # -----------------------------------------------------------------------------
 
+def __deprecated(name, func):
+
+    # Get the caller's frame
+    frame = inspect.currentframe().f_back
+    while not frame.f_code.co_name == '__new_f':
+        frame = frame.f_back
+
+    try:
+        msg = "Function " + __func_name(func, frame) + "() is deprecated"
+    finally:
+        # Frame object has to be deleted manually.
+        del frame
+
+    deprecated_n(name, msg)
+    return True
+  
+# -----------------------------------------------------------------------------
+
 def __func_name(func, frame):
     # It seems like there is no way to find out the name of the class that
-    # defined a method. To print out the class name in the log, we need to
-    # inspect the 'self' parameter.
+    # defined a method.  To print out the class name in the log, we need to
+    # inspect the 'self' parameter.  This is a pity, because we can only do
+    # this at function execution, not at function definition.  If we could find
+    # out the class name at function definition time, we could save this whole
+    # function here.
     fname = func.__name__
     code = func.func_code
     if code.co_argcount > 0 and code.co_varnames[0] == 'self':