Commit ad5591e2 authored by Tim Peters's avatar Tim Peters

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.
parent 2f8dd658
......@@ -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
-------
......
......@@ -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,113 +101,109 @@ 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
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
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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment