collections.abc
— Abstract Base Classes for ContainersNew 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.
The collections module offers the following ABCs:
ABC | Inherits from | Abstract Methods | Mixin Methods |
---|---|---|---|
Container
|
__contains__
|
||
Hashable
|
__hash__
|
||
Iterable
|
__iter__
|
||
Iterator
|
Iterable
|
__next__
|
__iter__
|
Reversible
|
Iterable
|
__reversed__
|
|
Generator
|
Iterator
|
send , throw
|
close , __iter__ , __next__
|
Sized
|
__len__
|
||
Callable
|
__call__
|
||
Collection
|
Sized ,
|
__contains__ ,
|
|
Sequence
|
Reversible ,
|
__getitem__ ,
|
__contains__ , __iter__ , __reversed__ ,
|
MutableSequence
|
Sequence
|
__getitem__ ,
|
Inherited Sequence methods and
|
ByteString
|
Sequence
|
__getitem__ ,
|
Inherited Sequence methods
|
Set
|
Collection
|
__contains__ ,
|
__le__ , __lt__ , __eq__ , __ne__ ,
|
MutableSet
|
Set
|
__contains__ ,
|
Inherited Set methods and
|
Mapping
|
Collection
|
__getitem__ ,
|
__contains__ , keys , items , values ,
|
MutableMapping
|
Mapping
|
__getitem__ ,
|
Inherited Mapping methods and
|
MappingView
|
Sized
|
__len__
| |
ItemsView
|
MappingView ,
|
__contains__ ,
| |
KeysView
|
MappingView ,
|
__contains__ ,
| |
ValuesView
|
MappingView ,
|
__contains__ , __iter__
| |
Awaitable
|
__await__
|
||
Coroutine
|
Awaitable
|
send , throw
|
close
|
AsyncIterable
|
__aiter__
|
||
AsyncIterator
|
AsyncIterable
|
__anext__
|
__aiter__
|
AsyncGenerator
|
AsyncIterator
|
asend , athrow
|
aclose , __aiter__ , __anext__
|
collections.abc.
Container
__contains__()
method.collections.abc.
Hashable
__hash__()
method.collections.abc.
Sized
__len__()
method.collections.abc.
Callable
__call__()
method.collections.abc.
Iterable
ABC for classes that provide the __iter__()
method.
Checking isinstance(obj, Iterable)
detects classes that are registered
as Iterable
or that have an __iter__()
method, but it does
not detect classes that iterate with the __getitem__()
method.
The only reliable way to determine whether an object is iterable
is to call iter(obj)
.
collections.abc.
Collection
ABC for sized iterable container classes.
New in version 3.6.
collections.abc.
Iterator
__iter__()
and __next__()
methods. See also the definition of iterator.collections.abc.
Reversible
ABC for iterable classes that also provide the __reversed__()
method.
New in version 3.6.
collections.abc.
Generator
ABC for generator classes that implement the protocol defined in
PEP 342 that extends iterators with the send()
,
throw()
and close()
methods.
See also the definition of generator.
New in version 3.5.
collections.abc.
Sequence
collections.abc.
MutableSequence
collections.abc.
ByteString
ABCs for read-only and mutable sequences.
Implementation note: Some of the mixin methods, such as
__iter__()
, __reversed__()
and index()
, 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.
collections.abc.
Set
class collections.abc.
MutableSet
collections.abc.
Mapping
class collections.abc.
MutableMapping
collections.abc.
MappingView
class collections.abc.
ItemsView
class collections.abc.
KeysView
class collections.abc.
ValuesView
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()
or asyncio.coroutine()
) are
awaitables, even though they do not have an __await__()
method.
Using isinstance(gencoro, Awaitable)
for them will return False
.
Use inspect.isawaitable()
to detect them.
New in version 3.5.
collections.abc.
Coroutine
ABC for coroutine compatible classes. These implement the
following methods, defined in Coroutine Objects:
send()
, throw()
, and
close()
. Custom implementations must also implement
__await__()
. All Coroutine
instances are also instances of
Awaitable
. See also the definition of coroutine.
Note
In CPython, generator-based coroutines (generators decorated with
types.coroutine()
or asyncio.coroutine()
) are
awaitables, even though they do not have an __await__()
method.
Using isinstance(gencoro, Coroutine)
for them will return False
.
Use inspect.isawaitable()
to detect them.
New in version 3.5.
collections.abc.
AsyncIterable
ABC for classes that provide __aiter__
method. See also the
definition of asynchronous iterable.
New in version 3.5.
collections.abc.
AsyncIterator
ABC for classes that provide __aiter__
and __anext__
methods. See also the definition of asynchronous iterator.
New in version 3.5.
collections.abc.
AsyncGenerator
ABC for asynchronous generator classes that implement the protocol defined in PEP 525 and PEP 492.
New in version 3.6.
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:
ClassName(iterable)
. That assumption is factored-out to an internal classmethod called _from_iterable()
which calls cls(iterable)
to produce a new set. If the Set
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.__le__()
and __ge__()
, then the other operations will automatically follow suit.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 both Set()
and Hashable()
, then define __hash__ = Set._hash
.See also
MutableSet
.abc
module and PEP 3119.