[Zope3-checkins] SVN: Zope3/branches/jim-adapter/src/zope/deprecation/ Provide an easy way of deprecating whole modules. It is now possible to say::

[Philipp von Weitershausen]

Log message for revision 66263:
  Provide an easy way of deprecating whole modules.  It is now possible to say::
    sys.modules['oldname'] = zope.deprecation.deprecated(newmodule, "oldname is now newmodule")
  

Changed:
  U   Zope3/branches/jim-adapter/src/zope/deprecation/README.txt
  U   Zope3/branches/jim-adapter/src/zope/deprecation/deprecation.py

-=-
Modified: Zope3/branches/jim-adapter/src/zope/deprecation/README.txt
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deprecation/README.txt	2006-03-29 20:50:59 UTC (rev 66262)
+++ Zope3/branches/jim-adapter/src/zope/deprecation/README.txt	2006-03-30 08:42:17 UTC (rev 66263)
@@ -8,6 +8,9 @@
 provides a simple function called `deprecated(names, reason)` to deprecate the
 previously mentioned Python objects.
 
+Deprecating objects inside a module
+-----------------------------------
+
 Let's start with a demonstration of deprecating any name inside a module. To
 demonstrate the functionality, I have placed the following code inside the
 `tests.py` file of this package:
@@ -60,6 +63,9 @@
   >>> tests.demo1
   1
 
+Deprecating methods and properties
+----------------------------------
+
 New let's see how properties and methods can be deprecated. We are going to
 use the same function as before, except that this time, we do not pass in names
 as first argument, but the method or attribute itself. The function then
@@ -107,8 +113,33 @@
   ...
   5
 
+Deprecating modules
+-------------------
 
-Temporarily Turning Off Deprecation Warnings
+It is also possible to deprecate whole modules.  This is useful when
+creating module aliases for backward compatibility.  Let's imagine,
+the ``zope.deprecation`` module used to be called ``zope.wanda`` and
+we'd like to retain backward compatibility:
+
+  >>> import zope.deprecation
+  >>> import sys
+  >>> sys.modules['zope.wanda'] = deprecation.deprecated(
+  ...     zope.deprecation, 'A module called Wanda is now zope.deprecation.')
+
+Now we can import ``wanda``, but when accessing things from it, we get
+our deprecation message as expected:
+
+  >>> from zope.wanda import deprecated
+  From tests.py's showwarning():
+  ...README.txt:1: DeprecationWarning: A module called Wanda is now zope.deprecation.
+  ...
+
+Before we move on, we should clean up:
+
+  >>> del deprecated
+  >>> del sys.modules['zope.wanda']
+
+Temporarily turning off deprecation warnings
 --------------------------------------------
 
 In some cases it is desireable to turn off the deprecation warnings for a

Modified: Zope3/branches/jim-adapter/src/zope/deprecation/deprecation.py
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deprecation/deprecation.py	2006-03-29 20:50:59 UTC (rev 66262)
+++ Zope3/branches/jim-adapter/src/zope/deprecation/deprecation.py	2006-03-30 08:42:17 UTC (rev 66263)
@@ -90,7 +90,35 @@
 
         delattr(self.__original_module, name)
         
+class DeprecatedModule(object):
 
+    def __init__(self, module, msg):
+        self.__original_module = module
+        self.__msg = msg
+
+    def __getattribute__(self, name):
+        if name.startswith('_DeprecatedModule__'):
+            return ogetattr(self, name)
+
+        if name == '__class__':
+            return types.ModuleType
+        
+        if zope.deprecation.__show__():
+            warnings.warn(self.__msg, DeprecationWarning, 2)
+
+        return getattr(ogetattr(self, '_DeprecatedModule__original_module'),
+                       name)
+
+    def __setattr__(self, name, value):
+        if name.startswith('_DeprecatedModule__'):
+            return object.__setattr__(self, name, value)
+        setattr(self.__original_module, name, value)
+
+    def __delattr__(self, name):
+        if name.startswith('_DeprecatedModule__'):
+            return object.__delattr__(self, name)
+        delattr(self.__original_module, name)
+
 class DeprecatedGetProperty(object):
 
     def __init__(self, prop, message):
@@ -129,7 +157,9 @@
 def deprecated(specifier, message):
     """Deprecate the given names."""
 
-    # We are inside a module
+    # A string specifier (or list of strings) means we're called
+    # top-level in a module and are to deprecate things inside this
+    # module
     if isinstance(specifier, (str, unicode, list, tuple)):
         locals = sys._getframe(1).f_locals
         if '__name__' in locals:
@@ -140,9 +170,12 @@
         sys.modules[modname].deprecate(specifier, message)
 
 
-    # ... that means the specifier is a method or attribute of the class
-    if isinstance(specifier, types.FunctionType):
+    # Anything else can mean the specifier is a function/method,
+    # module, or just an attribute of a class
+    elif isinstance(specifier, types.FunctionType):
         return DeprecatedMethod(specifier, message)
+    elif isinstance(specifier, types.ModuleType):
+        return DeprecatedModule(specifier, message)
     else:
         prop = specifier
         if hasattr(prop, '__get__') and hasattr(prop, '__set__') and \