[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):