[Checkins] SVN: zodbupdate/branches/sylvain-persistent-load/src/zodbupdate/serialize.py Remove useless code, add comments.

[Sylvain Viollon]

Log message for revision 105499:
  Remove useless code, add comments.
  
  

Changed:
  U   zodbupdate/branches/sylvain-persistent-load/src/zodbupdate/serialize.py

-=-
Modified: zodbupdate/branches/sylvain-persistent-load/src/zodbupdate/serialize.py
===================================================================
--- zodbupdate/branches/sylvain-persistent-load/src/zodbupdate/serialize.py	2009-11-05 14:52:22 UTC (rev 105498)
+++ zodbupdate/branches/sylvain-persistent-load/src/zodbupdate/serialize.py	2009-11-05 18:51:03 UTC (rev 105499)
@@ -1,3 +1,16 @@
+##############################################################################
+#
+# Copyright (c) 2009 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
 
 from ZODB.broken import find_global
 import cPickle
@@ -13,9 +26,14 @@
 
 
 class ObjectRenamer:
-    """This load and save a record using persistent_id and
-    persistent_load methods defined in the ZODB code to change
-    information at that point as well.
+    """This load and save a ZODB record, modifying all references to
+    renamed class according the given renaming rules:
+
+    - in global symbols contained in the record,
+
+    - in persistent reference information,
+
+    - in class information (first pickle of the record).
     """
 
     def __init__(self, changes):
@@ -25,12 +43,22 @@
         self.__changed = False
 
     def __find_global(self, *names):
+        """Find a class with the given name, looking for a renaming
+        rule first.
+
+        Using ZODB find_global let us manage missing classes.
+        """
         if names in self.__changes:
             names = self.__changes[names]
             self.__changed = True
         return find_global(*names)
 
     def __persistent_load(self, reference):
+        """Load a persistent reference. The reference might changed
+        according a renaming rules. We give back a special object to
+        represent that reference, and not the real object designated
+        by the reference.
+        """
         if isinstance(reference, tuple):
             oid, klass = reference
             if klass in self.__changes:
@@ -41,23 +69,34 @@
         return ZODBReference(reference)
 
     def __unpickler(self, pickle):
+        """Create an unpickler with our custom global symbol loader
+        and reference resolver.
+        """
         unpickler = cPickle.Unpickler(pickle)
         unpickler.persistent_load = self.__persistent_load
         unpickler.find_global = self.__find_global
         return unpickler
 
     def __persistent_id(self, obj):
+        """Save the given object as a reference only if it was a
+        reference before. We re-use the same information.
+        """
         if not isinstance(obj, ZODBReference):
             return None
         return obj.ref
 
     def __pickler(self, output):
+        """Create a pickler able to save to the given file, objects we
+        loaded while paying attention to any reference we loaded.
+        """
         pickler = cPickle.Pickler(output, 1)
         pickler.persistent_id = self.__persistent_id
-        pickler.clear_memo()
         return pickler
 
     def __update_class_meta(self, class_meta):
+        """Update class information, which can contain information
+        about a renamed class.
+        """
         if isinstance(class_meta, tuple):
             klass, args = class_meta
             if isinstance(klass, tuple):
@@ -67,6 +106,11 @@
         return class_meta
 
     def rename(self, input_file):
+        """Take a ZODB record (as a file object) as input. We load it,
+        replace any reference to renamed class we know of. If any
+        modification are done, we save the record again and return it,
+        return None otherwise.
+        """
         self.__changed = False
 
         unpickler = self.__unpickler(input_file)