Added in version 3.3: Formerly, this module was part of the
module.
Source code:
———
This module provides
that can be used to test whether a class provides a particular interface; for example, whether it is
or whether it is a
.
An
or
test for an interface works in one of three ways.
A newly written class can inherit directly from one of the abstract base classes. The class must supply the required abstract methods. The remaining mixin methods come from inheritance and can be overridden if desired. Other methods may be added as needed:
classC(Sequence):# Direct inheritancedef__init__(self):...# Extra method not required by the ABCdef__getitem__(self,index):...# Required abstract methoddef__len__(self):...# Required abstract methoddefcount(self,value):...# Optionally override a mixin method>>> issubclass(C,Sequence)True>>> isinstance(C(),Sequence)True
Existing classes and built-in classes can be registered as “virtual subclasses” of the ABCs. Those classes should define the full API including all of the abstract methods and all of the mixin methods. This lets users rely on
or
tests to determine whether the full interface is supported. The exception to this rule is for methods that are automatically inferred from the rest of the API:
classD:# No inheritancedef__init__(self):...# Extra method not required by the ABCdef__getitem__(self,index):...# Abstract methoddef__len__(self):...# Abstract methoddefcount(self,value):...# Mixin methoddefindex(self,value):...# Mixin methodSequence.register(D)# Register instead of inherit>>> issubclass(D,Sequence)True>>> isinstance(D(),Sequence)TrueIn this example, class D does not need to define __contains__, __iter__, and __reversed__ because the
, the
logic, and the
function automatically fall back to using __getitem__ and __len__.
Some simple interfaces are directly recognizable by the presence of the required methods (unless those methods have been set to
):
classE:def__iter__(self):...def__next__(self):...>>> issubclass(E,Iterable)True>>> isinstance(E(),Iterable)TrueComplex interfaces do not support this last technique because an interface is more than just the presence of method names. Interfaces specify semantics and relationships between methods that cannot be inferred solely from the presence of specific method names. For example, knowing that a class supplies __getitem__, __len__, and __iter__ is insufficient for distinguishing a
from a
.
Collections Abstract Base Classes
The collections module offers the following
:
ABC
Inherits from
Abstract Methods
Mixin Methods
__contains__
__hash__
__iter__
__next__
__iter__
__reversed__
send, throw
close, __iter__, __next__
__len__
__call__
,
,
__contains__, __iter__, __len__
,
__getitem__, __len__
__contains__, __iter__, __reversed__, index, and count
__getitem__, __setitem__, __delitem__, __len__, insert
Inherited
methods and append, clear, reverse, extend, pop, remove, and __iadd__
__getitem__, __len__
Inherited
methods
__contains__, __iter__, __len__
__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __rsub__, __xor__, __rxor__ and isdisjoint
__contains__, __iter__, __len__, add, discard
Inherited
methods and clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__
__getitem__, __iter__, __len__
__contains__, keys, items, values, get, __eq__, and __ne__
__getitem__, __setitem__, __delitem__, __iter__, __len__
Inherited
methods and pop, popitem, clear, update, and setdefault
__init__, __len__ and __repr__
,
__contains__, __iter__
,
__contains__, __iter__
,
__contains__, __iter__
__await__
send, throw
close
__aiter__
__anext__
__aiter__
asend, athrow
aclose, __aiter__, __anext__
__buffer__
Footnotes
Collections Abstract Base Classes – Detailed Descriptions
classcollections.abc.Container
ABC for classes that provide the
method.
classcollections.abc.Hashable
ABC for classes that provide the
method.
classcollections.abc.Sized
ABC for classes that provide the
method.
classcollections.abc.Callable
ABC for classes that provide the
method.
See
for details on how to use Callable in type annotations.
classcollections.abc.Iterable
ABC for classes that provide the
method.
Checking isinstance(obj,Iterable) detects classes that are registered as Iterable or that have an
method, but it does not detect classes that iterate with the
method. The only reliable way to determine whether an object is
is to call iter(obj).
classcollections.abc.Collection
ABC for sized iterable container classes.
Added in version 3.6.
classcollections.abc.Iterator
ABC for classes that provide the
and
methods. See also the definition of
.
classcollections.abc.Reversible
ABC for iterable classes that also provide the
method.
Added in version 3.6.
classcollections.abc.Generator
ABC for
classes that implement the protocol defined in
that extends
with the
,
and
methods.
See
Annotating generators and coroutines
for details on using Generator in type annotations.
Added in version 3.5.
classcollections.abc.Sequence
classcollections.abc.MutableSequence
classcollections.abc.ByteString
ABCs for read-only and mutable
.
Implementation note: Some of the mixin methods, such as
,
, and
make repeated calls to the underlying
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.
index(value, start=0, stop=None)
Return first index of value.
Raises
if the value is not present.
Supporting the start and stop arguments is optional, but recommended.
Changed in version 3.5: The
method gained support for the stop and start arguments.
Deprecated since version 3.12, will be removed in version 3.17: The ByteString ABC has been deprecated.
Use isinstance(obj,collections.abc.Buffer) to test if obj implements the
at runtime. For use in type annotations, either use
or a union that explicitly specifies the types your code supports (e.g., bytes|bytearray|memoryview).
ByteString was originally intended to be an abstract class that would serve as a supertype of both
and
. However, since the ABC never had any methods, knowing that an object was an instance of ByteString never actually told you anything useful about the object. Other common buffer types such as
were also never understood as subtypes of ByteString (either at runtime or by static type checkers).
See
for more details.
classcollections.abc.Set
classcollections.abc.MutableSet
ABCs for read-only and mutable
.
classcollections.abc.Mapping
classcollections.abc.MutableMapping
ABCs for read-only and mutable
.
classcollections.abc.MappingView
classcollections.abc.ItemsView
classcollections.abc.KeysView
classcollections.abc.ValuesView
ABCs for mapping, items, keys, and values
.
classcollections.abc.Awaitable
ABC for
objects, which can be used in
expressions. Custom implementations must provide the
method.
objects and instances of the
ABC are all instances of this ABC.
Added in version 3.5.
classcollections.abc.Coroutine
ABC for
compatible classes. These implement the following methods, defined in
:
,
, and
. Custom implementations must also implement
. All Coroutine instances are also instances of
.
See
Annotating generators and coroutines
for details on using Coroutine in type annotations. The variance and order of type parameters correspond to those of
.
Added in version 3.5.
classcollections.abc.AsyncIterable
ABC for classes that provide an __aiter__ method. See also the definition of
.
Added in version 3.5.
classcollections.abc.AsyncIterator
ABC for classes that provide __aiter__ and __anext__ methods. See also the definition of
.
Added in version 3.5.
classcollections.abc.AsyncGenerator
ABC for
classes that implement the protocol defined in
and
.
See
Annotating generators and coroutines
for details on using AsyncGenerator in type annotations.
Added in version 3.6.
classcollections.abc.Buffer
ABC for classes that provide the
method, implementing the
. See
.
Added in version 3.12.
Examples and Recipes
ABCs allow us to ask classes or instances if they provide particular functionality, for example:
size=Noneifisinstance(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
API, it is only necessary to supply the three underlying abstract methods:
,
, and
. The ABC supplies the remaining methods such as __and__() and
:
classListBasedSet(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=[]forvalueiniterable:ifvaluenotinlst:lst.append(value)def__iter__(self):returniter(self.elements)def__contains__(self,value):returnvalueinself.elementsdef__len__(self):returnlen(self.elements)s1=ListBasedSet('abcdef')s2=ListBasedSet('defghi')overlap=s1&s2# The __and__() method is supported automaticallyNotes on using
and
as a mixin:
Since some set operations create new sets, the default mixin methods need a way to create new instances from an
. The class constructor is assumed to have a signature in the form ClassName(iterable). That assumption is factored-out to an internal
called _from_iterable() which calls cls(iterable) to produce a new set. If the
mixin is being used in a class with a different constructor signature, you will need to override _from_iterable() with a classmethod or regular method that can construct new instances from an iterable argument.
To override the comparisons (presumably for speed, as the semantics are fixed), redefine
and
, then the other operations will automatically follow suit.
The
mixin provides a _hash() method to compute a hash value for the set; however,
is not defined because not all sets are
or immutable. To add set hashability using mixins, inherit from both Set and
, then define __hash__=Set._hash.
See also
for an example built on
.
For more about ABCs, see the
module and
.