diff options
| -rw-r--r-- | Lib/collections/abc.py | 68 |
1 files changed, 68 insertions, 0 deletions
diff --git a/Lib/collections/abc.py b/Lib/collections/abc.py index c23b7dd..7939268 100644 --- a/Lib/collections/abc.py +++ b/Lib/collections/abc.py @@ -90,6 +90,7 @@ class Iterator(Iterable): @abstractmethod def __next__(self): + 'Return the next item from the iterator. When exhausted, raise StopIteration' raise StopIteration def __iter__(self): @@ -230,6 +231,7 @@ class Set(Sized, Iterable, Container): return self._from_iterable(value for value in other if value in self) def isdisjoint(self, other): + 'Return True if two sets have a null intersection.' for value in other: if value in self: return False @@ -292,6 +294,16 @@ Set.register(frozenset) class MutableSet(Set): + """A mutable set is a finite, iterable container. + + This class provides concrete generic implementations of all + methods except for __contains__, __iter__, __len__, + add(), and discard(). + + To override the comparisons (presumably for speed, as the + semantics are fixed), all you have to do is redefine __le__ and + then the other operations will automatically follow suit. + """ __slots__ = () @@ -370,11 +382,20 @@ class Mapping(Sized, Iterable, Container): __slots__ = () + """A Mapping is a generic container for associating key/value + pairs. + + This class provides concrete generic implementations of all + methods except for __getitem__, __iter__, and __len__. + + """ + @abstractmethod def __getitem__(self, key): raise KeyError def get(self, key, default=None): + 'D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.' try: return self[key] except KeyError: @@ -389,12 +410,15 @@ class Mapping(Sized, Iterable, Container): return True def keys(self): + "D.keys() -> a set-like object providing a view on D's keys" return KeysView(self) def items(self): + "D.items() -> a set-like object providing a view on D's items" return ItemsView(self) def values(self): + "D.values() -> an object providing a view on D's values" return ValuesView(self) def __eq__(self, other): @@ -477,6 +501,15 @@ class MutableMapping(Mapping): __slots__ = () + """A MutableMapping is a generic container for associating + key/value pairs. + + This class provides concrete generic implementations of all + methods except for __getitem__, __setitem__, __delitem__, + __iter__, and __len__. + + """ + @abstractmethod def __setitem__(self, key, value): raise KeyError @@ -488,6 +521,9 @@ class MutableMapping(Mapping): __marker = object() def pop(self, key, default=__marker): + '''D.pop(k[,d]) -> v, remove specified key and return the corresponding value. + If key is not found, d is returned if given, otherwise KeyError is raised. + ''' try: value = self[key] except KeyError: @@ -499,6 +535,9 @@ class MutableMapping(Mapping): return value def popitem(self): + '''D.popitem() -> (k, v), remove and return some (key, value) pair + as a 2-tuple; but raise KeyError if D is empty. + ''' try: key = next(iter(self)) except StopIteration: @@ -508,6 +547,7 @@ class MutableMapping(Mapping): return key, value def clear(self): + 'D.clear() -> None. Remove all items from D.' try: while True: self.popitem() @@ -515,6 +555,11 @@ class MutableMapping(Mapping): pass def update(*args, **kwds): + ''' D.update([E, ]**F) -> None. Update D from mapping/iterable E and F. + If E present and has a .keys() method, does: for k in E: D[k] = E[k] + If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v + In either case, this is followed by: for k, v in F.items(): D[k] = v + ''' if len(args) > 2: raise TypeError("update() takes at most 2 positional " "arguments ({} given)".format(len(args))) @@ -536,6 +581,7 @@ class MutableMapping(Mapping): self[key] = value def setdefault(self, key, default=None): + 'D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D' try: return self[key] except KeyError: @@ -583,12 +629,16 @@ class Sequence(Sized, Iterable, Container): yield self[i] def index(self, value): + '''S.index(value) -> integer -- return first index of value. + Raises ValueError if the value is not present. + ''' for i, v in enumerate(self): if v == value: return i raise ValueError def count(self, value): + 'S.count(value) -> integer -- return number of occurrences of value' return sum(1 for v in self if v == value) Sequence.register(tuple) @@ -613,6 +663,13 @@ class MutableSequence(Sequence): __slots__ = () + """All the operations on a read-only sequence. + + Concrete subclasses must provide __new__ or __init__, + __getitem__, __setitem__, __delitem__, __len__, and insert(). + + """ + @abstractmethod def __setitem__(self, index, value): raise IndexError @@ -623,12 +680,15 @@ class MutableSequence(Sequence): @abstractmethod def insert(self, index, value): + 'S.insert(index, value) -- insert value before index' raise IndexError def append(self, value): + 'S.append(value) -- append value to the end of the sequence' self.insert(len(self), value) def clear(self): + 'S.clear() -> None -- remove all items from S' try: while True: self.pop() @@ -636,20 +696,28 @@ class MutableSequence(Sequence): pass def reverse(self): + 'S.reverse() -- reverse *IN PLACE*' n = len(self) for i in range(n//2): self[i], self[n-i-1] = self[n-i-1], self[i] def extend(self, values): + 'S.extend(iterable) -- extend sequence by appending elements from the iterable' for v in values: self.append(v) def pop(self, index=-1): + '''S.pop([index]) -> item -- remove and return item at index (default last). + Raise IndexError if list is empty or index is out of range. + ''' v = self[index] del self[index] return v def remove(self, value): + '''S.remove(value) -- remove first occurrence of value. + Raise ValueError if the value is not present. + ''' del self[self.index(value)] def __iadd__(self, values): |