[Zope3-checkins] CVS: Zope3/src/zope/proxy/context - __init__.py:1.8.2.3

[Steve Alexander]

Update of /cvs-repository/Zope3/src/zope/proxy/context
In directory cvs.zope.org:/tmp/cvs-serv5159/src/zope/proxy/context

Modified Files:
      Tag: stevea-decorators-branch
	__init__.py 
Log Message:
Added a docstring to ensureContextWrapped.


=== Zope3/src/zope/proxy/context/__init__.py 1.8.2.2 => 1.8.2.3 ===
--- Zope3/src/zope/proxy/context/__init__.py:1.8.2.2	Fri May 16 12:18:41 2003
+++ Zope3/src/zope/proxy/context/__init__.py	Fri May 16 12:32:15 2003
@@ -59,7 +59,27 @@
     return _ob
 
 def ensureContextWrapped(_ob, _parent, **kw):
-    # XXX Test me, document me!
+    """Preserve an existing wrapper, but change parent and dict items.
+
+    In code that uses context wrapping, we have two situations:
+
+    * Code such as traversal code wants to ensure that there is a context-
+      wrapper, and set the parent and items in the context dict.
+      If there is no context wrapper, it should create one, but if there
+      is one already, it should be preserved.
+
+    * Code that is the primary source of some information, and wants to
+      wrap it and add minimal information (name, usually) before allowing
+      the world to see the information. The zopecontainerdecorator is an
+      example of this.
+
+    To resolve these situations, the former code should use
+    ensureContextWrapped, which keeps an existing context wrapper if possible,
+    and updates the context and adds/overwrites items in the context dict.
+
+    The latter code can continue to use ContextWrapper.
+    """
+    # XXX Test me!
     if type(_ob) is Proxy:
         unproxied_ob = getObject(_ob)
     else: