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.

NEWS.txt

@@ -98,6 +98,13 @@ but these work again too:
 - ``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
 -------

src/BTrees/Interfaces.py

@@ -12,8 +12,8 @@
 #
 ##############################################################################
 
-import OOBTree, Interface
-from Interface import Interface
+from zope.interface import Interface
+
 
 class ICollection(Interface):
 
@@ -43,24 +43,35 @@ class IReadSequence(Interface):
         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.
+
+        Return a true value if the key is present, else a false value.
+        """
+
+    def keys(min=None, max=None, excludemin=False, excludemax=False):
+        """Return an IReadSequence containing the keys in the collection.
 
-    def keys(min=None, max=None):
-        """Return an IReadSequence containing the keys 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.
+        All arguments are optional, and may be specified as keyword
+        arguments, or by position.
 
-        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 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
-        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 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 @@ class IKeyed(ICollection):
         greater than or equal to the argument.
         """
 
+
 class ISetMutable(IKeyed):
 
     def insert(key):
@@ -89,34 +101,35 @@ class ISetMutable(IKeyed):
         """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
@@ -125,77 +138,72 @@ class IMinimalDictionary(ISized):
         """
 
     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
-
-        Raise a key error if the key if not in the collection."""
+        """Delete the value for the given key.
 
-    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.
-        """
-
-    def values(min=None, max=None):
-        """Return a IReadSequence containing the values in the collection
+        All arguments are optional, and may be specified as keyword
+        arguments, or by position.
 
-        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 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.
 
-        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
-
-        An item is a key-value tuple.
+class IDictionaryIsh(IMinimalDictionary):
 
-        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.
+    def update(collection):
+        """Add the items from the given collection object to the collection.
 
-        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 @@ class IDictionaryIsh(IKeyed, IMinimalDictionary):
         integer values, the normalization is division.
         """
 
+
 class IBTree(IDictionaryIsh):
 
     def insert(key, value):
@@ -227,6 +236,7 @@ class IBTree(IDictionaryIsh):
               key=generate_key()
         """
 
+
 class IMerge(Interface):
     """Object with methods for merging sets, buckets, and trees.
 
@@ -238,7 +248,7 @@ class IMerge(Interface):
 
     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 @@ class IIMerge(IMerge):
                   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 @@ class IMergeIntegerKey(IMerge):
 # 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