[Zope-CVS] CVS: Packages/pypes/pypes - interfaces.py:1.7

[Casey Duncan]

Update of /cvs-repository/Packages/pypes/pypes
In directory cvs.zope.org:/tmp/cvs-serv2259

Modified Files:
	interfaces.py 
Log Message:
Define interfaces for extents


=== Packages/pypes/pypes/interfaces.py 1.6 => 1.7 ===
--- Packages/pypes/pypes/interfaces.py:1.6	Wed Feb  4 22:31:33 2004
+++ Packages/pypes/pypes/interfaces.py	Thu Feb  5 00:35:51 2004
@@ -26,7 +26,8 @@
     """
 
 class IIdentityService(IPersistentService):
-    """
+    """Registry of "identified" objects known to pypes.
+    
     - Creates unique identifiers for persistent objects in a database.
 
     - Guarantees access to an object by its identifier as long as it 
@@ -59,10 +60,11 @@
         """
 
     def register(obj):
-        """Register obj a class instance with the identity tool. Return the
-        persistent unique identifier for obj. The service must guarantee that
-        so long as the object remains registered, it can be retrieved using the
-        identifier returned upon registration.
+        """Register obj with the identity service. Identity registered objects
+        are considered "identified". Return the persistent unique identifier
+        for obj. The service must guarantee that so long as the object remains
+        registered, it can be retrieved using the identifier returned upon
+        registration.
 
         If obj is already registered or cannot
         be registered for any reason, raise an IdentityError.
@@ -109,7 +111,7 @@
         """Return an identity set of all registered objects."""
 
 class IIdentitySet(Interface):
-    """A set of unique identity-registered objects. Since the set relies
+    """A set of unique identified objects. Since the set relies
     on persistent identity, its members may be mutable. Identity sets 
     weakly reference their members, so being a member of a set does not
     guarantee continued persistence. Implementations may use the event
@@ -118,7 +120,7 @@
     def add(obj):
         """Add obj to the set. Return true if obj was not a member already,
         false if so. In the latter case insert does not change the set. Raise
-        IdentityError if obj is not id-registered
+        IdentityError if obj is not identified
         """
     
     def remove(obj):
@@ -246,7 +248,105 @@
     """A message concerning the identity of an object"""
     
     id = Attribute('id', 'The identity of the object in question')
+
+
+class IExtentService(Interface):
+    """Service providing global extent sets of identified objects by class and 
+    interface.
+    
+    Extents are typically used as top-level collections by applications. They
+    are generally analogous to tables in a traditional relational database. A
+    strong difference however, is that extents are not directly modified.
+    Objects are added and removed from extents automatically as they are
+    registered and unregistered from the identity service or modified (in terms
+    of interfaces provided) and signaled through the event service. 
+
+    XXX Once the query service is documented, explain how they work together
+    """
+    
+    def __getitem__(key):
+        """Return the canonical extent for key. For class extents the key is a 
+        class. For interface extents it is an interface object.  
+        """
+
+    def __contains__(key):
+        """Return true if key is an identifier of an extent, false otherwise"""
+    
+    def __iter__():
+        """Return an iterator of all extents in the service"""
+
+
+class IExtent(Interface):
+    """Automated set of identified objects.
+    
+    Extents are either provided by the extent service or derived from other
+    extents. Extents behave like read-only sets in most respects. They are
+    updated automatically as objects are manipulated and registered with pypes.
     
+    Although extents may be arbitrarily large, operations between them  (such
+    as union and intersection) are designed to be efficient, especially between
+    extents of the same type (class or interface). Operations between extents
+    and identity sets are also supported; resulting in a new identity set.
+    """
+    
+    def __contains__(obj):
+        """Return true if obj is in the extent"""
+    
+    def __len__():
+        """Return extent member count"""
+    
+    def __iter__():
+        """Return an iterator of the members of the extent"""
+    
+    def union(other):
+        """Return a derived extent or identity set whos members are the union 
+        of self and other"""
+        
+    def __or__(other):
+        """Alias for union in an expression"""
+        
+    def difference(other):
+        """return a derived extent or identity set whos members are in self 
+        but not in other"""
+    
+    def __sub__(other):
+        """Alias for difference"""
+        
+    def intersection(other):
+        """Return a derived extent or identity set whos members are in both 
+        self and other"""
+    
+    def __and__(other):
+        """Compute the intersection between self and other and return the 
+        resulting derived extent or identity set
+        """
+    
+    def issubset(other):
+        """Return true if all members of self are also in other"""
+    
+    def issuperset(other):
+        """Return true if all members of other are also in self"""
+        
+    def __eq__(other):
+        """Return true if this extent and other contain the same members"""
+
+
+class ICanonicalExtent(IExtent):
+    """An extent of a single interface or class provided directly by the
+    extent service
+    """
+    
+    key = Attribute('key',
+        """Key for this extent in the extent service""")
+    
+    def subExtents():
+        """Return the direct sub-extents of the extent, if any, which are
+        disjoint canonical sets which are subsets of the extent. 
+        """
+
+class IDerivedExtent(IExtent):
+    """An extent derived by combining one or more extents"""
+
 
 class IGraphNodes(Interface):
     """Collection of nodes in a graph"""