[Checkins] SVN: zope.copy/trunk/ Include tests of the LocationCopyHook from zope.location.

[Hanno Schlichting]

Log message for revision 107319:
  Include tests of the LocationCopyHook from zope.location.
  

Changed:
  U   zope.copy/trunk/CHANGES.txt
  U   zope.copy/trunk/src/zope/copy/README.txt
  A   zope.copy/trunk/src/zope/copy/pickling.txt
  U   zope.copy/trunk/src/zope/copy/tests.py

-=-
Modified: zope.copy/trunk/CHANGES.txt
===================================================================
--- zope.copy/trunk/CHANGES.txt	2009-12-29 22:12:02 UTC (rev 107318)
+++ zope.copy/trunk/CHANGES.txt	2009-12-29 22:42:30 UTC (rev 107319)
@@ -5,7 +5,7 @@
 3.5.1 (unreleased)
 ------------------
 
-- ...
+- Include tests of the LocationCopyHook from zope.location.
 
 3.5.0 (2009-02-09)
 ------------------

Modified: zope.copy/trunk/src/zope/copy/README.txt
===================================================================
--- zope.copy/trunk/src/zope/copy/README.txt	2009-12-29 22:12:02 UTC (rev 107318)
+++ zope.copy/trunk/src/zope/copy/README.txt	2009-12-29 22:42:30 UTC (rev 107319)
@@ -186,7 +186,7 @@
 -----------------------
 
 One thing we didn't examine yet is the use of ResumeCopy exception in
-the copy hooks. For example, when copying located objects we don't want
+the copy hooks. For example, when copying located objects we want
 to copy referenced subobjects that are not located in the object that
 is being copied. Imagine, we have a content object that has an image object,
 referenced by the ``cover`` attribute, but located in an independent
@@ -202,16 +202,14 @@
 
     >>> content.cover = image
   
-Without any hooks, the image object will be cloned as well:
+With the standard hook from zope.location the image object will be copied:
 
     >>> new = zope.copy.copy(content)
-    >>> new.cover is image
+    >>> new.cover is not image
     False
 
-That's not what we'd expect though, so, let's provide a copy hook
-to deal with that. The copy hook for this case is provided by zope.location
-package, but we'll create one from scratch as we want to check out the
-usage of the ResumeCopy. 
+Now we can see how the ResumeCopy exception works, by creating a copy hook
+from scratch.
 
     >>> @zope.component.adapter(zope.location.interfaces.ILocation)
     ... @zope.interface.implementer(zope.copy.interfaces.ICopyHook)

Added: zope.copy/trunk/src/zope/copy/pickling.txt
===================================================================
--- zope.copy/trunk/src/zope/copy/pickling.txt	                        (rev 0)
+++ zope.copy/trunk/src/zope/copy/pickling.txt	2009-12-29 22:42:30 UTC (rev 107319)
@@ -0,0 +1,39 @@
+LocationCopyHook
+================
+
+The location copy hook is defined in zope.location but only activated if this
+package is installed.
+
+It's job is to allow copying referenced objects that are not located inside
+object that's being copied.
+
+To see the problem, imagine we want to copy an ILocation object that
+contains an attribute-based reference to another ILocation object
+and the referenced object is not contained inside object being copied. 
+
+Without this hook, the referenced object will be cloned:
+
+  >>> from zope.location.location import Location, locate
+  >>> root = Location()
+  >>> page = Location()
+  >>> locate(page, root, 'page')
+  >>> image = Location()
+  >>> locate(page, root, 'image')
+  >>> page.thumbnail = image
+
+  >>> from zope.copy import copy
+  >>> page_copy = copy(page)
+  >>> page_copy.thumbnail is image
+  False
+
+But if we will provide a hook, the attribute will point to the
+original object as we might want.
+
+  >>> from zope.component import provideAdapter
+  >>> from zope.location.pickling import LocationCopyHook
+  >>> provideAdapter(LocationCopyHook)
+
+  >>> from zope.copy import copy
+  >>> page_copy = copy(page)
+  >>> page_copy.thumbnail is image
+  True


Property changes on: zope.copy/trunk/src/zope/copy/pickling.txt
___________________________________________________________________
Added: svn:eol-style
   + native

Modified: zope.copy/trunk/src/zope/copy/tests.py
===================================================================
--- zope.copy/trunk/src/zope/copy/tests.py	2009-12-29 22:12:02 UTC (rev 107318)
+++ zope.copy/trunk/src/zope/copy/tests.py	2009-12-29 22:42:30 UTC (rev 107319)
@@ -26,6 +26,10 @@
 
 def test_suite():
     return unittest.TestSuite((
+        doctest.DocFileSuite('pickling.txt',
+            setUp=setUp,
+            tearDown=tearDown,
+            optionflags=doctest.ELLIPSIS|doctest.NORMALIZE_WHITESPACE),
         doctest.DocFileSuite('README.txt',
             setUp=setUp,
             tearDown=tearDown,