collections.abc
collections.abc — Abstract Base Classes for Containers
New in version 3.3: Formerly, this module was part of the collections
module.
Source code: Lib/_collections_abc.py
This module provides abstract base classes that can be used to test whether a class provides a particular interface; for example, whether it is hashable or whether it is a mapping.
1. Collections Abstract Base Classes
The collections module offers the following ABCs:
ABC | Inherits from | Abstract Methods | Mixin Methods |
---|---|---|---|
Container | __contains__ | ||
Hashable | __hash__ | ||
Iterable | __iter__ | ||
Iterator | Iterable | __next__ | __iter__ |
Generator | Iterator |
send , throw
|
close , __iter__ , __next__
|
Sized | __len__ | ||
Callable | __call__ | ||
Sequence |
Sized , Iterable , Container
|
__getitem__ , __len__
|
__contains__ , __iter__ , __reversed__ , index , and count
|
MutableSequence | Sequence |
__getitem__ , __setitem__ , __delitem__ , __len__ , insert
| Inherited Sequence methods and append , reverse , extend , pop , remove , and __iadd__
|
ByteString | Sequence |
__getitem__ , __len__
| Inherited Sequence methods |
Set |
Sized , Iterable , Container
|
__contains__ , __iter__ , __len__
|
__le__ , __lt__ , __eq__ , __ne__ , __gt__ , __ge__ , __and__ , __or__ , __sub__ , __xor__ , and isdisjoint
|
MutableSet | Set |
__contains__ , __iter__ , __len__ , add , discard
| Inherited Set methods and clear , pop , remove , __ior__ , __iand__ , __ixor__ , and __isub__
|
Mapping |
Sized , Iterable , Container
|
__getitem__ , __iter__ , __len__
|
__contains__ , keys , items , values , get , __eq__ , and __ne__
|
MutableMapping | Mapping |
__getitem__ , __setitem__ , __delitem__ , __iter__ , __len__
| Inherited Mapping methods and pop , popitem , clear , update , and setdefault
|
MappingView | Sized | __len__ | |
ItemsView |
MappingView , Set
|
__contains__ , __iter__
| |
KeysView |
MappingView , Set
|
__contains__ , __iter__
| |
ValuesView | MappingView |
__contains__ , __iter__
| |
Awaitable | __await__ | ||
Coroutine | Awaitable |
send , throw
| close |
AsyncIterable | __aiter__ | ||
AsyncIterator | AsyncIterable | __anext__ | __aiter__ |
-
class collections.abc.Container
-
class collections.abc.Hashable
-
class collections.abc.Sized
-
class collections.abc.Callable
-
ABCs for classes that provide respectively the methods
__contains__()
,__hash__()
,__len__()
, and__call__()
.
-
class collections.abc.Iterable
-
ABC for classes that provide the
__iter__()
method. See also the definition of iterable.
-
class collections.abc.Iterator
-
ABC for classes that provide the
__iter__()
and__next__()
methods. See also the definition of iterator.
-
class collections.abc.Generator
-
ABC for generator classes that implement the protocol defined in PEP 342 that extends iterators with the
send()
,throw()
andclose()
methods. See also the definition of generator.New in version 3.5.
-
class collections.abc.Sequence
-
class collections.abc.MutableSequence
-
class collections.abc.ByteString
-
ABCs for read-only and mutable sequences.
Implementation note: Some of the mixin methods, such as
__iter__()
,__reversed__()
andindex()
, make repeated calls to the underlying__getitem__()
method. Consequently, if__getitem__()
is implemented with constant access speed, the mixin methods will have linear performance; however, if the underlying method is linear (as it would be with a linked list), the mixins will have quadratic performance and will likely need to be overridden.Changed in version 3.5: The index() method added support for stop and start arguments.
-
class collections.abc.Set
-
class collections.abc.MutableSet
-
ABCs for read-only and mutable sets.
-
class collections.abc.Mapping
-
class collections.abc.MutableMapping
-
ABCs for read-only and mutable mappings.
-
class collections.abc.MappingView
-
class collections.abc.ItemsView
-
class collections.abc.KeysView
-
class collections.abc.ValuesView
-
ABCs for mapping, items, keys, and values views.
-
class collections.abc.Awaitable
-
ABC for awaitable objects, which can be used in
await
expressions. Custom implementations must provide the__await__()
method.Coroutine objects and instances of the
Coroutine
ABC are all instances of this ABC.Note
In CPython, generator-based coroutines (generators decorated with
types.coroutine()
orasyncio.coroutine()
) are awaitables, even though they do not have an__await__()
method. Usingisinstance(gencoro, Awaitable)
for them will returnFalse
. Useinspect.isawaitable()
to detect them.New in version 3.5.
-
class collections.abc.Coroutine
-
ABC for coroutine compatible classes. These implement the following methods, defined in Coroutine Objects:
send()
,throw()
, andclose()
. Custom implementations must also implement__await__()
. AllCoroutine
instances are also instances ofAwaitable
. See also the definition of coroutine.Note
In CPython, generator-based coroutines (generators decorated with
types.coroutine()
orasyncio.coroutine()
) are awaitables, even though they do not have an__await__()
method. Usingisinstance(gencoro, Coroutine)
for them will returnFalse
. Useinspect.isawaitable()
to detect them.New in version 3.5.
-
class collections.abc.AsyncIterable
-
ABC for classes that provide
__aiter__
method. See also the definition of asynchronous iterable.New in version 3.5.
-
class collections.abc.AsyncIterator
-
ABC for classes that provide
__aiter__
and__anext__
methods. See also the definition of asynchronous iterator.New in version 3.5.
These ABCs allow us to ask classes or instances if they provide particular functionality, for example:
size = None if isinstance(myvar, collections.abc.Sized): size = len(myvar)
Several of the ABCs are also useful as mixins that make it easier to develop classes supporting container APIs. For example, to write a class supporting the full Set
API, it is only necessary to supply the three underlying abstract methods: __contains__()
, __iter__()
, and __len__()
. The ABC supplies the remaining methods such as __and__()
and isdisjoint()
:
class ListBasedSet(collections.abc.Set): ''' Alternate set implementation favoring space over speed and not requiring the set elements to be hashable. ''' def __init__(self, iterable): self.elements = lst = [] for value in iterable: if value not in lst: lst.append(value) def __iter__(self): return iter(self.elements) def __contains__(self, value): return value in self.elements def __len__(self): return len(self.elements) s1 = ListBasedSet('abcdef') s2 = ListBasedSet('defghi') overlap = s1 & s2 # The __and__() method is supported automatically
Notes on using Set
and MutableSet
as a mixin:
- Since some set operations create new sets, the default mixin methods need a way to create new instances from an iterable. The class constructor is assumed to have a signature in the form
ClassName(iterable)
. That assumption is factored-out to an internal classmethod called_from_iterable()
which callscls(iterable)
to produce a new set. If theSet
mixin is being used in a class with a different constructor signature, you will need to override_from_iterable()
with a classmethod that can construct new instances from an iterable argument. - To override the comparisons (presumably for speed, as the semantics are fixed), redefine
__le__()
and__ge__()
, then the other operations will automatically follow suit. - The
Set
mixin provides a_hash()
method to compute a hash value for the set; however,__hash__()
is not defined because not all sets are hashable or immutable. To add set hashability using mixins, inherit from bothSet()
andHashable()
, then define__hash__ = Set._hash
.
See also
-
OrderedSet recipe for an example built on
MutableSet
. - For more about ABCs, see the
abc
module and PEP 3119.
© 2001–2017 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.5/library/collections.abc.html