[Zope-Checkins] CVS: Packages/BTrees - Interfaces.py:1.18.90.1

[Tim Peters]

Update of /cvs-repository/Packages/BTrees
In directory cvs.zope.org:/tmp/cvs-serv29503/BTrees

Modified Files:
      Tag: Zope-2_7-branch
	Interfaces.py 
Log Message:
Collector 1829.

Clarified that the ``minKey()`` and ``maxKey()`` methods raise an exception
if no key exists satsifying the constraints.

Also improved the English in other interface docstrings.


=== Packages/BTrees/Interfaces.py 1.18 => 1.18.90.1 ===
--- Packages/BTrees/Interfaces.py:1.18	Tue Jun 25 18:46:42 2002
+++ Packages/BTrees/Interfaces.py	Fri Jul  1 15:55:07 2005
@@ -18,40 +18,43 @@
 class ICollection(Interface):
 
     def clear():
-        """Remove all of the items from the collection"""
+        """Remove all of the items from the collection."""
 
     def __nonzero__():
         """Check if the collection is non-empty.
 
         Return a true value if the collection is non-empty and a
-        false otherwise.
+        false value otherwise.
         """
 
 
 class IReadSequence(Interface):
 
     def __getitem__(index):
-        """Return a value at the givem index
+        """Return the value at the given index.
 
         An IndexError is raised if the index cannot be found.
         """
 
     def __getslice__(index1, index2):
-        """Return a subsequence from the original sequence
+        """Return a subsequence from the original sequence.
 
-        Such that the subsequence includes the items from index1 up
-        to, but not including, index2.
+        The subsequence includes the items from index1 up 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 so, else a false value.
+        """
 
     def keys(min=None, max=None):
-        """Return an IReadSequence containing the keys in the collection
+        """Return an IReadSequence containing the keys in the collection.
 
-        The type of the IReadSequence is not specified. It could be a
+        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
@@ -66,15 +69,17 @@
     def maxKey(key=None):
         """Return the maximum key
 
-        If a key argument if provided, return the largest key that is
-        less than or equal to the argument.
+        If a key argument if provided and not None, return the largest key
+        that is less than or equal to the argument.  Raise an exception if
+        no such key exists.
         """
 
     def minKey(key=None):
         """Return the minimum key
 
-        If a key argument if provided, return the smallest key that is
-        greater than or equal to the argument.
+        If a key argument if provided and not None, return the smallest key
+        that is greater than or equal to the argument.  Raise an exception
+        if no such key exists.
         """
 
 class ISetMutable(IKeyed):
@@ -89,18 +94,18 @@
         """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"
 
     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.
@@ -115,43 +120,47 @@
 class IMinimalDictionary(ISized):
 
     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 so, else a false value.
+        """
 
 
     def get(key, default):
-        """Get the value for the given key
+        """Get the value associated with the given key.
 
-        Return the default if the key is not in the  collection.
+        Return the default if has_key(key) is false.
         """
 
     def __setitem__(key, value):
-        """Set the value for the given key"""
+        """Set the value associated with the given key."""
 
     def __delitem__(key):
-        """delete the value for the given key
+        """Delete the value associated with the given key.
 
-        Raise a key error if the key if not in the collection."""
+        Raise a KeyError if has_key(key) is false.
+        """
 
     def values():
-        """Return a IReadSequence containing the values in the collection
+        """Return an IReadSequence containing the values in the collection.
 
-        The type of the IReadSequence is not specified. It could be a
+        The type of the IReadSequence is not specified.  It could be a
         list or a tuple or some other type.
         """
 
     def keys():
-        """Return an Sequence containing the keys in the collection
+        """Return an IReadSequence containing the keys in the collection.
 
-        The type of the IReadSequence is not specified. It could be a
+        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
+        """Return an IReadSequence containing the items in the collection.
 
-        An item is a key-value tuple.
+        An item is a (key, value) 2-tuple.
 
-        The type of the IReadSequence is not specified. It could be a
+        The type of the IReadSequence is not specified.  It could be a
         list or a tuple or some other type.
         """
 
@@ -159,50 +168,46 @@
 class IDictionaryIsh(IKeyed, IMinimalDictionary):
 
     def update(collection):
-        """Add the items from the given collection object to the collection
+        """Add the items from the given collection object to the collection.
 
-        The input collection must be a sequence of key-value tuples,
+        The input collection must be a sequence of (key, value) 2-tuples,
         or an object with an 'items' method that returns a sequence of
-        key-value tuples.
+        (key, value) 2-tuples.
         """
 
     def values(min=None, max=None):
-        """Return a IReadSequence containing the values in the collection
+        """Return an IReadSequence containing the values in the collection.
 
-        The type of the IReadSequence is not specified. It could be a
+        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
+        If a min is specified and not None, 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 and not None, then output is constrained to
+        items having keys less than or equal to the given max.
         """
 
     def items(min=None, max=None):
-        """Return a IReadSequence containing the items in the collection
+        """Return an IReadSequence containing the items in the collection.
 
-        An item is a key-value tuple.
+        An item is a (key, value) 2-tuple.
 
-        The type of the IReadSequence is not specified. It could be a
+        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
+        If a min is specified and not None, 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
+        If a max is specified and not None, then output is constrained to
         items having keys less than or equal to the given min.
-        A max value of None is ignored.
         """
 
     def byValue(minValue):
-        """Return a sequence of value-key pairs, sorted by value
+        """Return a sequence of (value, key) pairs, sorted by value.
 
-        Values < min are ommitted and other values are "normalized" by
-        the minimum value. This normalization may be a noop, but, for
+        Values < minValue are omitted and other values are "normalized" by
+        the minimum value.  This normalization may be a noop, but, for
         integer values, the normalization is division.
         """
 
@@ -222,7 +227,7 @@
 
         A standard idiom for generating new keys will be::
 
-          key=generate_key()
+          key = generate_key()
           while not t.insert(key, value):
               key=generate_key()
         """
@@ -246,8 +251,7 @@
     """
 
     def difference(c1, c2):
-        """Return the keys or items in c1 for which there is no key in
-        c2.
+        """Return the keys or items in c1 for which there is no key in c2.
 
         If c1 is None, then None is returned.  If c2 is None, then c1
         is returned.