[Zope-CVS] CVS: Products/AdaptableStorage/mapper/interfaces - IAspectEvent.py:1.2 IClassifier.py:1.3 IDeserializationEvent.py:1.2 IFullDeserializationEvent.py:1.2 IFullSerializationEvent.py:1.2 IKeychainGenerator.py:1.2 IKeyedObjectSystem.py:1.2 IMapperEvent.py:1.3 IObjectSerializer.py:1.3 ISchema.py:1.2 ISerializationEvent.py:1.3

Shane Hathaway shane@zope.com
Fri, 14 Feb 2003 12:41:36 -0500


Update of /cvs-repository/Products/AdaptableStorage/mapper/interfaces
In directory cvs.zope.org:/tmp/cvs-serv24454/mapper/interfaces

Modified Files:
	IAspectEvent.py IClassifier.py IDeserializationEvent.py 
	IFullDeserializationEvent.py IFullSerializationEvent.py 
	IKeychainGenerator.py IKeyedObjectSystem.py IMapperEvent.py 
	IObjectSerializer.py ISchema.py ISerializationEvent.py 
Log Message:
Clarified some of the interface docstrings.


=== Products/AdaptableStorage/mapper/interfaces/IAspectEvent.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/IAspectEvent.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/IAspectEvent.py	Fri Feb 14 12:41:36 2003
@@ -35,11 +35,12 @@
     def addUnmanagedPersistentObjects(obs):
         """Notifies that there are unmanaged persistent objects in the object.
 
-        If no attention is paid to unmanaged persistent objects, they
-        will not notify ZODB when they are changed, and hence can be a
-        challenge for the application programmer.  Use this method to
-        tell ZODB about the unmanaged persistent objects so that ZODB
-        can deal with them specially.
+        If no attention is paid to unmanaged persistent objects
+        (UPOs), they will not notify ZODB when they are changed, and
+        hence can be a challenge for the application programmer.  Use
+        this method to tell ZODB about the UPOs so that ZODB will see
+        changes made to them and save the corresponding managed
+        persistent object.
         """
 
     def getUnmanagedPersistentObjects():


=== Products/AdaptableStorage/mapper/interfaces/IClassifier.py 1.2 => 1.3 ===
--- Products/AdaptableStorage/mapper/interfaces/IClassifier.py:1.2	Thu Jan 16 12:19:21 2003
+++ Products/AdaptableStorage/mapper/interfaces/IClassifier.py	Fri Feb 14 12:41:36 2003
@@ -29,7 +29,7 @@
     objects to create for a stored state (like a biologist showing you
     a creature of a certain genus and species).
 
-    The keys in the classification mapping are implementation-dependent.
+    The keys in classifications are implementation-dependent.
     """
 
     def classifyObject(value, keychain):


=== Products/AdaptableStorage/mapper/interfaces/IDeserializationEvent.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/IDeserializationEvent.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/IDeserializationEvent.py	Fri Feb 14 12:41:36 2003
@@ -20,8 +20,11 @@
 
 
 class IDeserializationEvent(IAspectEvent):
-    """Aspect deserializers call methods of this interface to restore
-    internal and external references.
+    """A helper in the object deserialization process.
+
+    Implementations of IAspectSerializer.deserialize() call
+    methods of this interface to restore internal and external
+    references.
     """
 
     def notifyDeserialized(name, value):


=== Products/AdaptableStorage/mapper/interfaces/IFullDeserializationEvent.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/IFullDeserializationEvent.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/IFullDeserializationEvent.py	Fri Feb 14 12:41:36 2003
@@ -20,10 +20,14 @@
 
 
 class IFullDeserializationEvent(IDeserializationEvent):
-    """Deserialization event with features for deserializing internal refs
+    """Deserialization event with features for deserializing internal refs.
+
+    Used for unpickling a 'remainder pickle'.
     """
 
     def loadInternalRef(ref):
-        """Returns an object for a reference of the form (aspect_name, name).
+        """Returns an object already deserialized by another aspect.
+
+        'ref' is a tuple containing (aspect_name, name).
         """
 


=== Products/AdaptableStorage/mapper/interfaces/IFullSerializationEvent.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/IFullSerializationEvent.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/IFullSerializationEvent.py	Fri Feb 14 12:41:36 2003
@@ -20,7 +20,9 @@
 
 
 class IFullSerializationEvent(ISerializationEvent):
-    """Serialization event with features for ensuring complete serialization
+    """Serialization event with features for ensuring complete serialization.
+
+    Used for generating a 'remainder pickle'.
     """
 
     def getSerializedAttributeNames():


=== Products/AdaptableStorage/mapper/interfaces/IKeychainGenerator.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/IKeychainGenerator.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/IKeychainGenerator.py	Fri Feb 14 12:41:36 2003
@@ -20,7 +20,12 @@
 
 
 class IKeychainGenerator (Interface):
-    """A utility for generating sub-keychains.
+    """A utility for generating keychains.
+
+    Many aspect serializers encode references to other objects, but it
+    is desirable to not hard code the format of keychains into
+    IAspectSerializers.  This utility, normally accessed through an
+    IMapperEvent, allows keychain knowledge to be kept in one place.
     """
 
     def makeKeychain(event, name, stored):


=== Products/AdaptableStorage/mapper/interfaces/IKeyedObjectSystem.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/IKeyedObjectSystem.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/IKeyedObjectSystem.py	Fri Feb 14 12:41:36 2003
@@ -19,7 +19,11 @@
 from Interface import Interface
 
 class IKeyedObjectSystem (Interface):
-    """A collection of objects identifiable by keychain."""
+    """A collection of objects identifiable by keychain.
+
+    In AdaptableStorage, the ZODB Connection object (the _p_jar) is
+    an IKeyedObjectSystem.
+    """
 
     def loadStub(keychain, hints=None):
         """Returns a class instance, possibly ghosted.


=== Products/AdaptableStorage/mapper/interfaces/IMapperEvent.py 1.2 => 1.3 ===
--- Products/AdaptableStorage/mapper/interfaces/IMapperEvent.py:1.2	Thu Jan  9 09:34:04 2003
+++ Products/AdaptableStorage/mapper/interfaces/IMapperEvent.py	Fri Feb 14 12:41:36 2003
@@ -19,6 +19,7 @@
 from Interface import Interface
 
 class IMapperEvent (Interface):
+    """The base interface for events in this package."""
 
     def getObjectMapper():
         """Returns the object mapper for the object being (de)serialized."""


=== Products/AdaptableStorage/mapper/interfaces/IObjectSerializer.py 1.2 => 1.3 ===
--- Products/AdaptableStorage/mapper/interfaces/IObjectSerializer.py:1.2	Mon Jan  6 10:36:46 2003
+++ Products/AdaptableStorage/mapper/interfaces/IObjectSerializer.py	Fri Feb 14 12:41:36 2003
@@ -20,10 +20,15 @@
 
 
 class IObjectSerializer(IAspectSerializer):
-    """Serializes/deserializes objects.
+    """Serializes/deserializes the full state of objects.
 
     The serialized state does not need to include the class of the object,
     which is maintained separately.
+
+    IObjectSerializers usually delegate to multiple IAspectSerializers
+    to do the actual work of (de)serialization.  The schema of
+    IObjectSerializers is usually a dictionary containing the name
+    and schema of its constituent IAspectSerializers.
     """
 
     def createEmptyInstance(classification=None):


=== Products/AdaptableStorage/mapper/interfaces/ISchema.py 1.1 => 1.2 ===
--- Products/AdaptableStorage/mapper/interfaces/ISchema.py:1.1	Tue Dec 31 16:47:46 2002
+++ Products/AdaptableStorage/mapper/interfaces/ISchema.py	Fri Feb 14 12:41:36 2003
@@ -24,6 +24,7 @@
     def __eq__(other):
         """Checks equality with another schema.
 
-        The idea is that serializers and data gateways need to agree
-        on schemas, and this method allows you to check compatibility.
+        This is the only method common to all schema objects.  The
+        idea is that serializers and data gateways need only agree on
+        schemas, and this method allows you to check compatibility.
         """


=== Products/AdaptableStorage/mapper/interfaces/ISerializationEvent.py 1.2 => 1.3 ===
--- Products/AdaptableStorage/mapper/interfaces/ISerializationEvent.py:1.2	Mon Feb  3 13:26:49 2003
+++ Products/AdaptableStorage/mapper/interfaces/ISerializationEvent.py	Fri Feb 14 12:41:36 2003
@@ -20,10 +20,11 @@
 
 
 class ISerializationEvent(IAspectEvent):
-    """Serialization event.
+    """A helper in the object serialization process.
 
-    Aspect serializers call methods of this interface to create
-    internal and external references.
+    Implementations of IAspectSerializer.serialize() call
+    methods of this interface to create internal and external
+    references.
     """
 
     def notifySerialized(name, value, is_attribute):