[Zodb-checkins] SVN: ZODB/branches/3.3/ Document exclude{min,max}.

Tim Peters tim.one at comcast.net
Sun Mar 20 14:39:51 EST 2005


Log message for revision 29592:
  Document exclude{min,max}.
  
  The ZODB4 BTrees excludemin/excludemax arguments got implemented
  in 3.3, but the corresponding changes to the BTrees interface
  file got dropped on the floor.
  

Changed:
  U   ZODB/branches/3.3/NEWS.txt
  U   ZODB/branches/3.3/src/BTrees/Interfaces.py

-=-
Modified: ZODB/branches/3.3/NEWS.txt
===================================================================
--- ZODB/branches/3.3/NEWS.txt	2005-03-20 17:50:11 UTC (rev 29591)
+++ ZODB/branches/3.3/NEWS.txt	2005-03-20 19:39:51 UTC (rev 29592)
@@ -98,7 +98,14 @@
 - ``from ZODB.PersistentList import PersistentList``
 - ``from ZODB.PersistentMapping import PersistentMapping``
 
+BTrees
+------
 
+The BTrees interface file neglected to document the optional
+``excludemin`` and ``excludemax`` arguments to the ``keys()``, ``values()``
+and ``items()`` methods.  Appropriate changes were merged in from the
+ZODB4 BTrees interface file.
+
 fsIndex
 -------
 

Modified: ZODB/branches/3.3/src/BTrees/Interfaces.py
===================================================================
--- ZODB/branches/3.3/src/BTrees/Interfaces.py	2005-03-20 17:50:11 UTC (rev 29591)
+++ ZODB/branches/3.3/src/BTrees/Interfaces.py	2005-03-20 19:39:51 UTC (rev 29592)
@@ -12,9 +12,9 @@
 #
 ##############################################################################
 
-import OOBTree, Interface
-from Interface import Interface
+from zope.interface import Interface
 
+
 class ICollection(Interface):
 
     def clear():
@@ -43,24 +43,35 @@
         to, but not including, index2.
         """
 
+
 class IKeyed(ICollection):
 
     def has_key(key):
-        """Check whether the object has an item with the given key"""
+        """Check whether the object has an item with the given key.
 
-    def keys(min=None, max=None):
-        """Return an IReadSequence containing the keys in the collection
+        Return a true value if the key is present, else a false value.
+        """
 
-        The type of the IReadSequence is not specified. It could be a
-        list or a tuple or some other type.
+    def keys(min=None, max=None, excludemin=False, excludemax=False):
+        """Return an IReadSequence containing the keys in the collection.
 
-        If a min is specified, then output is constrained to
-        items having keys greater than or equal to the given min.
-        A min value of None is ignored.
+        The type of the IReadSequence is not specified. It could be a list
+        or a tuple or some other type.
 
-        If a max is specified, then output is constrained to
-        items having keys less than or equal to the given min.
-        A max value of None is ignored.
+        All arguments are optional, and may be specified as keyword
+        arguments, or by position.
+
+        If a min is specified, then output is constrained to keys greater
+        than or equal to the given min, and, if excludemin is specified and
+        true, is further constrained to keys strictly greater than min.  A
+        min value of None is ignored.  If min is None or not specified, and
+        excludemin is true, the smallest key is excluded.
+
+        If a max is specified, then output is constrained to keys less than
+        or equal to the given max, and, if excludemax is specified and
+        true, is further constrained to keys strictly less than max.  A max
+        value of None is ignored.  If max is None or not specified, and
+        excludemax is true, the largest key is excluded.
         """
 
     def maxKey(key=None):
@@ -77,6 +88,7 @@
         greater than or equal to the argument.
         """
 
+
 class ISetMutable(IKeyed):
 
     def insert(key):
@@ -89,113 +101,109 @@
         """Remove the key from the set."""
 
     def update(seq):
-        """Add the items from the given sequence to the set"""
+        """Add the items from the given sequence to the set."""
 
+
 class ISized(Interface):
-    "anything supporting __len"
+    """An object that supports __len__."""
 
     def __len__():
-        """Return the number of items in the container"""
+        """Return the number of items in the container."""
 
+
 class IKeySequence(IKeyed, ISized):
 
     def __getitem__(index):
-        """Return the key in the given index position
+        """Return the key in the given index position.
 
         This allows iteration with for loops and use in functions,
         like map and list, that read sequences.
         """
 
+
 class ISet(IKeySequence, ISetMutable):
     pass
 
+
 class ITreeSet(IKeyed, ISetMutable):
     pass
 
-class IMinimalDictionary(ISized):
 
-    def has_key(key):
-        """Check whether the object has an item with the given key"""
+class IMinimalDictionary(ISized, IKeyed):
 
-
     def get(key, default):
         """Get the value for the given key
 
-        Return the default if the key is not in the  collection.
+        Return the default if the key is not in the collection.
         """
 
     def __setitem__(key, value):
-        """Set the value for the given key"""
+        """Set the value for the given key."""
 
     def __delitem__(key):
-        """delete the value for the given key
+        """Delete the value for the given key.
 
-        Raise a key error if the key if not in the collection."""
-
-    def values():
-        """Return a IReadSequence containing the values in the collection
-
-        The type of the IReadSequence is not specified. It could be a
-        list or a tuple or some other type.
+        Raise KeyError if the key if not in the collection.
         """
 
-    def keys():
-        """Return an Sequence containing the keys in the collection
+    def values(min=None, max=None, excludemin=False, excludemax=False):
+        """Return an IReadSequence containing the values in the collection.
 
-        The type of the IReadSequence is not specified. It could be a
-        list or a tuple or some other type.
-        """
+        The type of the IReadSequence is not specified. It could be a list
+        or a tuple or some other type.
 
-    def items():
-        """Return a IReadSequence containing the items in the collection
+        All arguments are optional, and may be specified as keyword
+        arguments, or by position.
 
-        An item is a key-value tuple.
+        If a min is specified, then output is constrained to values whose
+        keys are greater than or equal to the given min, and, if excludemin
+        is specified and true, is further constrained to values whose keys
+        are strictly greater than min.  A min value of None is ignored.  If
+        min is None or not specified, and excludemin is true, the value
+        corresponding to the smallest key is excluded.
 
-        The type of the IReadSequence is not specified. It could be a
-        list or a tuple or some other type.
+        If a max is specified, then output is constrained to values whose
+        keys are less than or equal to the given max, and, if excludemax is
+        specified and true, is further constrained to values whose keys are
+        strictly less than max.  A max value of None is ignored.  If max is
+        None or not specified, and excludemax is true, the value
+        corresponding to the largest key is excluded.
         """
 
+    def items(min=None, max=None, excludemin=False, excludemax=False):
+        """Return an IReadSequence containing the items in the collection.
 
-class IDictionaryIsh(IKeyed, IMinimalDictionary):
+        An item is a 2-tuple, a (key, value) pair.
 
-    def update(collection):
-        """Add the items from the given collection object to the collection
+        The type of the IReadSequence is not specified.  It could be a list
+        or a tuple or some other type.
 
-        The input collection must be a sequence of key-value tuples,
-        or an object with an 'items' method that returns a sequence of
-        key-value tuples.
-        """
+        All arguments are optional, and may be specified as keyword
+        arguments, or by position.
 
-    def values(min=None, max=None):
-        """Return a IReadSequence containing the values in the collection
+        If a min is specified, then output is constrained to items whose
+        keys are greater than or equal to the given min, and, if excludemin
+        is specified and true, is further constrained to items whose keys
+        are strictly greater than min.  A min value of None is ignored.  If
+        min is None or not specified, and excludemin is true, the item with
+        the smallest key is excluded.
 
-        The type of the IReadSequence is not specified. It could be a
-        list or a tuple or some other type.
-
-        If a min is specified, then output is constrained to
-        items having keys greater than or equal to the given min.
-        A min value of None is ignored.
-
-        If a max is specified, then output is constrained to
-        items having keys less than or equal to the given min.
-        A max value of None is ignored.
+        If a max is specified, then output is constrained to items whose
+        keys are less than or equal to the given max, and, if excludemax is
+        specified and true, is further constrained to items whose keys are
+        strictly less than max.  A max value of None is ignored.  If max is
+        None or not specified, and excludemax is true, the item with the
+        largest key is excluded.
         """
 
-    def items(min=None, max=None):
-        """Return a IReadSequence containing the items in the collection
+class IDictionaryIsh(IMinimalDictionary):
 
-        An item is a key-value tuple.
+    def update(collection):
+        """Add the items from the given collection object to the collection.
 
-        The type of the IReadSequence is not specified. It could be a
-        list or a tuple or some other type.
-
-        If a min is specified, then output is constrained to
-        items having keys greater than or equal to the given min.
-        A min value of None is ignored.
-
-        If a max is specified, then output is constrained to
-        items having keys less than or equal to the given min.
-        A max value of None is ignored.
+        The input collection must be a sequence of key-value tuples,
+        or an object with an 'items' method that returns a sequence of
+        key-value tuples.
         """
 
     def byValue(minValue):
@@ -206,6 +214,7 @@
         integer values, the normalization is division.
         """
 
+
 class IBTree(IDictionaryIsh):
 
     def insert(key, value):
@@ -227,6 +236,7 @@
               key=generate_key()
         """
 
+
 class IMerge(Interface):
     """Object with methods for merging sets, buckets, and trees.
 
@@ -238,7 +248,7 @@
 
     The implementing module has a value type. The IOBTree and OOBTree
     modules have object value type. The IIBTree and OIBTree modules
-    have integer value tyoes. Other modules may be defined in the
+    have integer value types. Other modules may be defined in the
     future that have other value types.
 
     The individual types are classified into set (Set and TreeSet) and
@@ -315,7 +325,6 @@
                   c2[key]  if the key is in c2 and c2 is a mapping
 
         Note that c1 and c2 must be collections.
-
         """
 
     def weightedIntersection(c1, c2, weight1=1, weight2=1):
@@ -390,11 +399,3 @@
 # Eventually, I need to express this through the interfaces.
 #
 ################################################################
-
-# XXX Need to use the new declaration syntax once it is available
-# for Zope 2.
-
-## OOBTree.OOSet.__implements__=ISet
-## OOBTree.OOTreeSet.__implements__=ITreeSet
-## OOBTree.OOBucket.__implements__=IDictionaryIsh
-## OOBTree.OOBTree.__implements__=IBTree



More information about the Zodb-checkins mailing list