[Zope3-checkins] SVN: Zope3/branches/jim-adapter/src/zope/deferredimport/ Implement a deferred and deprecated module proxy (for module aliases)

[Philipp von Weitershausen]

Log message for revision 66619:
  Implement a deferred and deprecated module proxy (for module aliases)
  

Changed:
  U   Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt
  U   Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py
  U   Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py

-=-
Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt	2006-04-06 20:21:03 UTC (rev 66618)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt	2006-04-06 21:22:09 UTC (rev 66619)
@@ -283,3 +283,42 @@
 
 Note, as in the example above, that you can make multiple
 deferred-import calls in a module.
+
+Deprecated Module Aliases
+-------------------------
+
+Sometimes modules are renamed and they should be available under the
+old name for a little while.  Importing things from the old name,
+however, should generate deprecation warnings.  Such deferred and
+deprecated module aliases are installed using ``deprecatedModule``.
+This convenience function takes the old module name, the new one and a
+deprecation message:
+
+    >>> from zope.deferredimport import deprecatedModule
+    >>> deprecatedModule('deferredsample', 'zope.deferredimport',
+    ...                  'It is now available under zope.deferredimport.')
+
+We can now import things from the "old" location:
+
+    >>> from deferredsample import deprecated
+    ... doctest: +NORMALIZE_WHITESPACE
+    zope/deferredimport/README.txt:1: DeprecationWarning:
+            zope.deferredimport is deprecated. It is now available
+            under zope.deferredimport.
+      Deferred Import
+
+The deprecation warning won't be shown a second time:
+
+    >>> from deferredsample import deprecatedFrom
+
+The deprecated module alias works pretty much like a regular module.
+Of course, all of its information points to the original, for example:
+
+   >>> import deferredsample
+   >>> deferredsample.__name__
+   'zope.deferredimport'
+
+Before we end this, we should clean up:
+
+   >>> import sys
+   >>> del sys.modules['deferredsample']

Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py	2006-04-06 20:21:03 UTC (rev 66618)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py	2006-04-06 21:22:09 UTC (rev 66619)
@@ -1,3 +1,4 @@
 from zope.deferredimport.deferredmodule import initialize
 from zope.deferredimport.deferredmodule import define, defineFrom
 from zope.deferredimport.deferredmodule import deprecated, deprecatedFrom
+from zope.deferredimport.deferredmodule import deprecatedModule

Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py	2006-04-06 20:21:03 UTC (rev 66618)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py	2006-04-06 21:22:09 UTC (rev 66619)
@@ -111,4 +111,29 @@
         specifier = from_name + ':' + name
         __deferred_definitions__[name] = DeferredAndDeprecated(
             name, specifier, message)
-    
+
+class DeferredDeprecatedModule(object):
+    __slots__ = ('__module_name', '__message', '__orig_module')
+
+    def __init__(self, module_name, message):
+        self.__module_name = module_name
+        self.__message = message
+        self.__orig_module = None
+
+    def __getattribute__(self, name):
+        if name.startswith('_DeferredDeprecatedModule__'):
+            return object.__getattribute__(self, name)
+
+        if self.__orig_module is None:
+            self.__orig_module = __import__(
+                self.__module_name, {}, {}, ['*'])
+            warnings.warn(self.__message, DeprecationWarning, 2)
+        return getattr(self.__orig_module, name)
+
+    def __setattr__(self, name, value):
+        if name.startswith('_DeferredDeprecatedModule__'):
+            return object.__setattr__(self, name, value)
+        setattr(self.__orig_module, name, value)
+
+def deprecatedModule(old, new, message):
+    sys.modules[old] = DeferredDeprecatedModule(new, message)