[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