collections.abc— Abstract Base Classes for Containers

Added in version 3.3:Formerly, this module was part of thecollectionsmodule.

Source code:Lib/_collections_abc.py

This module providesabstract base classesthat can be used to test whether a class provides a particular interface; for example, whether it ishashableor whether it is amapping.

Anissubclass()orisinstance()test for an interface works in one of three ways.

1) 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 inheritance
def__init__(self):...# Extra method not required by the ABC
def__getitem__(self,index):...# Required abstract method
def__len__(self):...# Required abstract method
defcount(self,value):...# Optionally override a mixin method

>>>issubclass(C,Sequence)
True
>>>isinstance(C(),Sequence)
True

2) 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 onissubclass()orisinstance()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 inheritance
def__init__(self):...# Extra method not required by the ABC
def__getitem__(self,index):...# Abstract method
def__len__(self):...# Abstract method
defcount(self,value):...# Mixin method
defindex(self,value):...# Mixin method

Sequence.register(D)# Register instead of inherit

>>>issubclass(D,Sequence)
True
>>>isinstance(D(),Sequence)
True

In this example, classDdoes not need to define __contains__,__iter__,and__reversed__because the in-operator,theiteration logic, and thereversed()function automatically fall back to using__getitem__and__len__.

3) Some simple interfaces are directly recognizable by the presence of the required methods (unless those methods have been set to None):

classE:
def__iter__(self):...
def__next__(self):...

>>>issubclass(E,Iterable)
True
>>>isinstance(E(),Iterable)
True

Complex 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 aSequencefrom aMapping.

Added in version 3.9:These abstract classes now support[].SeeGeneric Alias Type andPEP 585.

Collections Abstract Base Classes

The collections module offers the followingABCs:

ABC

Inherits from

Abstract Methods

Mixin Methods

Container[1]

__contains__

Hashable[1]

__hash__

Iterable[1][2]

__iter__

Iterator[1]

Iterable

__next__

__iter__

Reversible[1]

Iterable

__reversed__

Generator[1]

Iterator

send,throw

close,__iter__,__next__

Sized[1]

__len__

Callable[1]

__call__

Collection[1]

Sized, Iterable, Container

__contains__, __iter__, __len__

Sequence

Reversible, Collection

__getitem__, __len__

__contains__,__iter__,__reversed__, index,andcount

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

InheritedSequencemethods and append,clear,reverse,extend, pop,remove,and__iadd__

ByteString

Sequence

__getitem__, __len__

InheritedSequencemethods

Set

Collection

__contains__, __iter__, __len__

__le__,__lt__,__eq__,__ne__, __gt__,__ge__,__and__,__or__, __sub__,__xor__,andisdisjoint

MutableSet

Set

__contains__, __iter__, __len__, add, discard

InheritedSetmethods and clear,pop,remove,__ior__, __iand__,__ixor__,and__isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__,keys,items,values, get,__eq__,and__ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

InheritedMappingmethods and pop,popitem,clear,update, andsetdefault

MappingView

Sized

__len__

ItemsView

MappingView, Set

__contains__, __iter__

KeysView

MappingView, Set

__contains__, __iter__

ValuesView

MappingView, Collection

__contains__,__iter__

Awaitable[1]

__await__

Coroutine[1]

Awaitable

send,throw

close

AsyncIterable[1]

__aiter__

AsyncIterator[1]

AsyncIterable

__anext__

__aiter__

AsyncGenerator[1]

AsyncIterator

asend,athrow

aclose,__aiter__,__anext__

Buffer[1]

__buffer__

Footnotes

Collections Abstract Base Classes – Detailed Descriptions

classcollections.abc.Container

ABC for classes that provide the__contains__()method.

classcollections.abc.Hashable

ABC for classes that provide the__hash__()method.

classcollections.abc.Sized

ABC for classes that provide the__len__()method.

classcollections.abc.Callable

ABC for classes that provide the__call__()method.

SeeAnnotating callable objectsfor details on how to use Callablein type annotations.

classcollections.abc.Iterable

ABC for classes that provide the__iter__()method.

Checkingisinstance(obj,Iterable)detects classes that are registered asIterableor 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 isiterable is to calliter(obj).

classcollections.abc.Collection

ABC for sized iterable container classes.

Added in version 3.6.

classcollections.abc.Iterator

ABC for classes that provide the__iter__()and __next__()methods. See also the definition of iterator.

classcollections.abc.Reversible

ABC for iterable classes that also provide the__reversed__() method.

Added in version 3.6.

classcollections.abc.Generator

ABC forgeneratorclasses that implement the protocol defined in PEP 342that extendsiteratorswith the send(), throw()andclose()methods.

SeeAnnotating generators and coroutines for details on usingGeneratorin type annotations.

Added in version 3.5.

classcollections.abc.Sequence
classcollections.abc.MutableSequence
classcollections.abc.ByteString

ABCs for read-only and mutablesequences.

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 forstopandstart arguments.

Deprecated since version 3.12, will be removed in version 3.14:TheByteStringABC has been deprecated. For use in typing, prefer a union, likebytes|bytearray,or collections.abc.Buffer. For use as an ABC, preferSequenceorcollections.abc.Buffer.

classcollections.abc.Set
classcollections.abc.MutableSet

ABCs for read-only and mutablesets.

classcollections.abc.Mapping
classcollections.abc.MutableMapping

ABCs for read-only and mutablemappings.

classcollections.abc.MappingView
classcollections.abc.ItemsView
classcollections.abc.KeysView
classcollections.abc.ValuesView

ABCs for mapping, items, keys, and valuesviews.

classcollections.abc.Awaitable

ABC forawaitableobjects, which can be used inawait expressions. Custom implementations must provide the __await__()method.

Coroutineobjects and instances of the CoroutineABC are all instances of this ABC.

Note

In CPython, generator-based coroutines (generators decorated with@types.coroutine) are awaitables,even though they do not have an__await__()method. Usingisinstance(gencoro,Awaitable)for them will returnFalse. Useinspect.isawaitable()to detect them.

Added in version 3.5.

classcollections.abc.Coroutine

ABC forcoroutinecompatible classes. These implement the following methods, defined inCoroutine Objects: send(),throw(),and close().Custom implementations must also implement __await__().AllCoroutineinstances are also instances ofAwaitable.

Note

In CPython, generator-based coroutines (generators decorated with@types.coroutine) are awaitables,even though they do not have an__await__()method. Usingisinstance(gencoro,Coroutine)for them will returnFalse. Useinspect.isawaitable()to detect them.

SeeAnnotating generators and coroutines for details on usingCoroutinein type annotations. The variance and order of type parameters correspond to those of Generator.

Added in version 3.5.

classcollections.abc.AsyncIterable

ABC for classes that provide an__aiter__method. See also the definition ofasynchronous iterable.

Added in version 3.5.

classcollections.abc.AsyncIterator

ABC for classes that provide__aiter__and__anext__ methods. See also the definition ofasynchronous iterator.

Added in version 3.5.

classcollections.abc.AsyncGenerator

ABC forasynchronous generatorclasses that implement the protocol defined inPEP 525andPEP 492.

SeeAnnotating generators and coroutines for details on usingAsyncGeneratorin type annotations.

Added in version 3.6.

classcollections.abc.Buffer

ABC for classes that provide the__buffer__()method, implementing thebuffer protocol.SeePEP 688.

Added in version 3.12.

Examples and Recipes

ABCs allow us to ask classes or instances if they provide particular functionality, for example:

size=None
ifisinstance(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 fullSetAPI, it is only necessary to supply the three underlying abstract methods:__contains__(),__iter__(),and __len__().The ABC supplies the remaining methods such as __and__()andisdisjoint():

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.elements

def__len__(self):
returnlen(self.elements)

s1=ListBasedSet('abcdef')
s2=ListBasedSet('defghi')
overlap=s1&s2# The __and__() method is supported automatically

Notes on usingSetandMutableSetas a mixin:

  1. Since some set operations create new sets, the default mixin methods need a way to create new instances from aniterable.The class constructor is assumed to have a signature in the formClassName(iterable). That assumption is factored-out to an internalclassmethodcalled _from_iterable()which callscls(iterable)to produce a new set. If theSetmixin 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.

  2. To override the comparisons (presumably for speed, as the semantics are fixed), redefine__le__()and __ge__(), then the other operations will automatically follow suit.

  3. TheSetmixin provides a_hash()method to compute a hash value for the set; however,__hash__()is not defined because not all sets arehashableor immutable. To add set hashability using mixins, inherit from bothSet()andHashable(),then define __hash__=Set._hash.

See also