[Zope3-checkins] SVN: Zope3/branches/jim-adapter/src/zope/deferredimport/ Added a new convenience function, deprecatedFrom, for depecating many

[Jim Fulton]

Log message for revision 65930:
  Added a new convenience function, deprecatedFrom, for depecating many
  names imported from a common module. This will often be used when
  moving things to a backward-compatibility module.
  

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
  U   Zope3/branches/jim-adapter/src/zope/deferredimport/sample1.py.in
  U   Zope3/branches/jim-adapter/src/zope/deferredimport/sample2.py.in

-=-
Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt	2006-03-12 20:48:21 UTC (rev 65929)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/README.txt	2006-03-12 21:46:52 UTC (rev 65930)
@@ -14,7 +14,22 @@
 
 To see how this works, see the sample modules, sample1 and sample2.
 The sample1 module defines several values as deferred imports of and
-from sample 2.  The sample2 module prints a message when it is
+from sample 2 using the define function::
+
+ zope.deferredimport.define(
+    sample2 = 'zope.deferredimport.sample2',
+    one = 'zope.deferredimport.sample2:x',
+    two = 'zope.deferredimport.sample2:C.y',
+    )
+
+The define function defines names that will be satisfied by later
+importing modules and importing names from them.  In this example, we
+defined the name 'sample2' and the module
+zope.deferredimport.sample2. The module isn't imported immediately,
+but will be imported when needed.  Similarly, the name 'one' is
+defined as the 'x' attribute of sample2.
+
+The sample2 module prints a message when it is
 imported.  When we import sample1, we don't see a message until we
 access a variable:
 
@@ -41,14 +56,52 @@
     True
 
 Deferred attributes can also be marked as deprecated, in which case, a
-message will be printed the first time they are accessed:
+message will be printed the first time they are accessed.
 
+The sample1 module defines deprecated attribute using two
+functions. The deprecated function is used like the define function::
+
+  zope.deferredimport.deprecated(
+    "Will go away in 2007.",
+    three = 'zope.deferredimport.sample2:C',
+    )
+
+except that the first argument is a depecation message.  The
+deprecated function causes deprecation warnings to be printed when the
+defined variable is accessed the first time:
+
     >>> zope.deferredimport.sample1.three is zope.deferredimport.sample2.C
     README.txt:1: 
     DeprecationWarning: three is deprecated. Will go away in 2007.
       Deferred Import
     True
 
+The deprecatedFrom function handles the common case that we want to
+depecate multiple variables that we import from another module.  We pass
+the deprecation message, the name of the module that we want to import
+from, and one or more names to be imported::
+
+  zope.deferredimport.deprecatedFrom(
+    "Will go away in 2007.",
+    'zope.deferredimport.sample2',
+    'z', 'q',
+    )
+
+As with the deprecated function, warnings will be generated when the
+variables are accessed the first time.
+
+    >>> zope.deferredimport.sample1.z is zope.deferredimport.sample2.z
+    README.txt:1: 
+    DeprecationWarning: z is deprecated. Will go away in 2007.
+      Deferred Import
+    True
+
+    >>> zope.deferredimport.sample1.q is zope.deferredimport.sample2.q
+    README.txt:1: 
+    DeprecationWarning: q is deprecated. Will go away in 2007.
+      Deferred Import
+    True
+
 Of course, non-deferred variables are accessible as usuall:
 
     >>> print zope.deferredimport.sample1.four

Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py	2006-03-12 20:48:21 UTC (rev 65929)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/__init__.py	2006-03-12 21:46:52 UTC (rev 65930)
@@ -1 +1,3 @@
-from zope.deferredimport.deferredmodule import define, deprecated
+from zope.deferredimport.deferredmodule import (
+    define, deprecated, deprecatedFrom,
+    )

Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py	2006-03-12 20:48:21 UTC (rev 65929)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/deferredmodule.py	2006-03-12 21:46:52 UTC (rev 65930)
@@ -15,7 +15,7 @@
 
 $Id$
 """
-
+import types
 import sys
 import warnings
 
@@ -76,7 +76,7 @@
     module = sys.modules[__name__]
     cls = module.__class__
     if not issubclass(cls, Module):
-        cls = type(__name__ + 'Class', (Module, ), {})
+        cls = type('Module', (Module, ), {})
         module = cls(module)
         sys.modules[__name__] = module
     return cls
@@ -90,4 +90,10 @@
     cls = getClass()
     for name, specifier in names.iteritems():
         setattr(cls, name, DeferredAndDeprecated(name, specifier, message))
+
+def deprecatedFrom(message, module, *names):
+    cls = getClass()
+    for name in names:
+        specifier = module + ':' + name
+        setattr(cls, name, DeferredAndDeprecated(name, specifier, message))
     

Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/sample1.py.in
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/sample1.py.in	2006-03-12 20:48:21 UTC (rev 65929)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/sample1.py.in	2006-03-12 21:46:52 UTC (rev 65930)
@@ -13,4 +13,10 @@
     three = 'zope.deferredimport.sample2:C',
     )
 
+zope.deferredimport.deprecatedFrom(
+    "Will go away in 2007.",
+    'zope.deferredimport.sample2',
+    'z', 'q',
+    )
+
 five = 5

Modified: Zope3/branches/jim-adapter/src/zope/deferredimport/sample2.py.in
===================================================================
--- Zope3/branches/jim-adapter/src/zope/deferredimport/sample2.py.in	2006-03-12 20:48:21 UTC (rev 65929)
+++ Zope3/branches/jim-adapter/src/zope/deferredimport/sample2.py.in	2006-03-12 21:46:52 UTC (rev 65930)
@@ -4,3 +4,6 @@
 
 class C:
     y = 2
+
+z = 3
+q = 4