Skip to content

Z
ZODB
Commit ad5591e2 authored by Tim Peters's avatar Tim Peters
Browse files
Options

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
Show whitespace changes
Inline Side-by-side
Showing with 91 additions and 83 deletions
NEWS.txt
View file @ ad5591e2
...@@ -98,6 +98,13 @@ but these work again too: ...@@ -98,6 +98,13 @@ but these work again too:
- ``from ZODB.PersistentList import PersistentList`` - ``from ZODB.PersistentList import PersistentList``
- ``from ZODB.PersistentMapping import PersistentMapping`` - ``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 fsIndex
------- -------
......
src/BTrees/Interfaces.py
View file @ ad5591e2
...@@ -12,8 +12,8 @@ ...@@ -12,8 +12,8 @@
# #
############################################################################## ##############################################################################
import OOBTree, Interface from zope.interface import Interface
from Interface import Interface
class ICollection(Interface): class ICollection(Interface):
...@@ -43,24 +43,35 @@ class IReadSequence(Interface): ...@@ -43,24 +43,35 @@ class IReadSequence(Interface):
to, but not including, index2. to, but not including, index2.
""" """
class IKeyed(ICollection): class IKeyed(ICollection):
def has_key(key): 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): The type of the IReadSequence is not specified. It could be a list
"""Return an IReadSequence containing the keys in the collection or a tuple or some other type.
The type of the IReadSequence is not specified. It could be a All arguments are optional, and may be specified as keyword
list or a tuple or some other type. arguments, or by position.
If a min is specified, then output is constrained to If a min is specified, then output is constrained to keys greater
items having keys greater than or equal to the given min. than or equal to the given min, and, if excludemin is specified and
A min value of None is ignored. 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 If a max is specified, then output is constrained to keys less than
items having keys less than or equal to the given min. or equal to the given max, and, if excludemax is specified and
A max value of None is ignored. 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): def maxKey(key=None):
...@@ -77,6 +88,7 @@ class IKeyed(ICollection): ...@@ -77,6 +88,7 @@ class IKeyed(ICollection):
greater than or equal to the argument. greater than or equal to the argument.
""" """
class ISetMutable(IKeyed): class ISetMutable(IKeyed):
def insert(key): def insert(key):
...@@ -89,34 +101,35 @@ class ISetMutable(IKeyed): ...@@ -89,34 +101,35 @@ class ISetMutable(IKeyed):
"""Remove the key from the set.""" """Remove the key from the set."""
def update(seq): 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): class ISized(Interface):
"anything supporting __len" """An object that supports __len__."""
def __len__(): def __len__():
"""Return the number of items in the container""" """Return the number of items in the container."""
class IKeySequence(IKeyed, ISized): class IKeySequence(IKeyed, ISized):
def __getitem__(index): 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, This allows iteration with for loops and use in functions,
like map and list, that read sequences. like map and list, that read sequences.
""" """
class ISet(IKeySequence, ISetMutable): class ISet(IKeySequence, ISetMutable):
pass pass
class ITreeSet(IKeyed, ISetMutable): class ITreeSet(IKeyed, ISetMutable):
pass 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): def get(key, default):
"""Get the value for the given key """Get the value for the given key
...@@ -125,77 +138,72 @@ class IMinimalDictionary(ISized): ...@@ -125,77 +138,72 @@ class IMinimalDictionary(ISized):
""" """
def __setitem__(key, value): def __setitem__(key, value):
"""Set the value for the given key""" """Set the value for the given key."""
def __delitem__(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(): Raise KeyError if the key if not in the collection.
"""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.
""" """
def keys(): def values(min=None, max=None, excludemin=False, excludemax=False):
"""Return an Sequence containing the keys 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
list or a tuple or some other type. or a tuple or some other type.
"""
def items(): All arguments are optional, and may be specified as keyword
"""Return a IReadSequence containing the items in the collection 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 If a max is specified, then output is constrained to values whose
list or a tuple or some other type. 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): The type of the IReadSequence is not specified. It could be a list
"""Add the items from the given collection object to the collection or a tuple or some other type.
The input collection must be a sequence of key-value tuples, All arguments are optional, and may be specified as keyword
or an object with an 'items' method that returns a sequence of arguments, or by position.
key-value tuples.
"""
def values(min=None, max=None):
"""Return a IReadSequence containing the values in the collection
The type of the IReadSequence is not specified. It could be a If a min is specified, then output is constrained to items whose
list or a tuple or some other type. 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 If a max is specified, then output is constrained to items whose
items having keys greater than or equal to the given min. keys are less than or equal to the given max, and, if excludemax is
A min value of None is ignored. 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
If a max is specified, then output is constrained to None or not specified, and excludemax is true, the item with the
items having keys less than or equal to the given min. largest key is excluded.
A max value of None is ignored.
""" """
def items(min=None, max=None): class IDictionaryIsh(IMinimalDictionary):
"""Return a IReadSequence containing the items in the collection
An item is a key-value tuple.
The type of the IReadSequence is not specified. It could be a def update(collection):
list or a tuple or some other type. """Add the items from the given collection object to 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.
If a max is specified, then output is constrained to The input collection must be a sequence of key-value tuples,
items having keys less than or equal to the given min. or an object with an 'items' method that returns a sequence of
A max value of None is ignored. key-value tuples.
""" """
def byValue(minValue): def byValue(minValue):
...@@ -206,6 +214,7 @@ class IDictionaryIsh(IKeyed, IMinimalDictionary): ...@@ -206,6 +214,7 @@ class IDictionaryIsh(IKeyed, IMinimalDictionary):
integer values, the normalization is division. integer values, the normalization is division.
""" """
class IBTree(IDictionaryIsh): class IBTree(IDictionaryIsh):
def insert(key, value): def insert(key, value):
...@@ -227,6 +236,7 @@ class IBTree(IDictionaryIsh): ...@@ -227,6 +236,7 @@ class IBTree(IDictionaryIsh):
key=generate_key() key=generate_key()
""" """
class IMerge(Interface): class IMerge(Interface):
"""Object with methods for merging sets, buckets, and trees. """Object with methods for merging sets, buckets, and trees.
...@@ -238,7 +248,7 @@ class IMerge(Interface): ...@@ -238,7 +248,7 @@ class IMerge(Interface):
The implementing module has a value type. The IOBTree and OOBTree The implementing module has a value type. The IOBTree and OOBTree
modules have object value type. The IIBTree and OIBTree modules 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. future that have other value types.
The individual types are classified into set (Set and TreeSet) and The individual types are classified into set (Set and TreeSet) and
...@@ -315,7 +325,6 @@ class IIMerge(IMerge): ...@@ -315,7 +325,6 @@ class IIMerge(IMerge):
c2[key] if the key is in c2 and c2 is a mapping c2[key] if the key is in c2 and c2 is a mapping
Note that c1 and c2 must be collections. Note that c1 and c2 must be collections.
""" """
def weightedIntersection(c1, c2, weight1=1, weight2=1): def weightedIntersection(c1, c2, weight1=1, weight2=1):
...@@ -390,11 +399,3 @@ class IMergeIntegerKey(IMerge): ...@@ -390,11 +399,3 @@ class IMergeIntegerKey(IMerge):
# Eventually, I need to express this through the interfaces. # 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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7