collections.abc — Abstract Base Classes for Containers

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

Source code:Lib/_collections_abc.py

This module providesabstract base classes thatcan be used to test whether a class provides a particular interface; forexample, whether it ishashable or whether it is amapping.

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

  1. A newly written class can inherit directly from one of theabstract base classes. The class must supply the required abstractmethods. The remaining mixin methods come from inheritance and can beoverridden 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

  2. Existing classes and built-in classes can be registered as “virtualsubclasses” of the ABCs. Those classes should define the full APIincluding all of the abstract methods and all of the mixin methods.This lets users rely onissubclass() orisinstance() teststo determine whether the full interface is supported. The exception tothis rule is for methods that are automatically inferred from the restof 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)True

    In this example, classD does not need to define__contains__,__iter__, and__reversed__ because thein-operator, theiterationlogic, and thereversed() function automatically fall back tousing__getitem__ and__len__.

  3. Some simple interfaces are directly recognizable by the presence ofthe required methods (unless those methods have been set toNone):

    classE:def__iter__(self):...def__next__(self):...
    >>>issubclass(E,Iterable)True>>>isinstance(E(),Iterable)True

    Complex interfaces do not support this last technique because aninterface is more than just the presence of method names. Interfacesspecify semantics and relationships between methods that cannot beinferred solely from the presence of specific method names. Forexample, knowing that a class supplies__getitem__,__len__, and__iter__ is insufficient for distinguishing aSequence fromaMapping.

Added in version 3.9:These abstract classes now support[]. SeeGeneric Alias TypeandPEP 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

InheritedSequence methods andappend,clear,reverse,extend,pop,remove, and__iadd__

Set

Collection

__contains__,__iter__,__len__

__le__,__lt__,__eq__,__ne__,__gt__,__ge__,__and__,__or__,__sub__,__rsub__,__xor__,__rxor__andisdisjoint

MutableSet

Set

__contains__,__iter__,__len__,add,discard

InheritedSet methods andclear,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__

InheritedMapping methods andpop,popitem,clear,update,andsetdefault

MappingView

Sized

__init__,__len__ and__repr__

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

[1](1,2,3,4,5,6,7,8,9,10,11,12,13,14,15)

These ABCs override__subclasshook__() to supporttesting an interface by verifying the required methods are presentand have not been set toNone. This only works for simpleinterfaces. More complex interfaces require registration or directsubclassing.

[2]

Checkingisinstance(obj,Iterable) detects classes that areregistered asIterable or that have an__iter__()method, but it does not detect classes that iterate with the__getitem__() method. The only reliable way to determinewhether an object isiterable is to calliter(obj).

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 objects for details on how to useCallable in type annotations.

classcollections.abc.Iterable

ABC for classes that provide the__iter__() method.

Checkingisinstance(obj,Iterable) detects classes that are registeredasIterable or that have an__iter__() method,but it doesnot detect classes that iterate with the__getitem__() method.The only reliable way to determine whether an object isiterableis 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 ofiterator.

classcollections.abc.Reversible

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

Added in version 3.6.

classcollections.abc.Generator

ABC forgenerator classes that implement the protocol defined inPEP 342 that extendsiterators with thesend(),throw() andclose() methods.

SeeAnnotating generators and coroutinesfor details on usingGenerator in type annotations.

Added in version 3.5.

classcollections.abc.Sequence
classcollections.abc.MutableSequence

ABCs for read-only and mutablesequences.

Implementation note: Some of the mixin methods, such as__iter__(),__reversed__() andindex(), makerepeated calls to the underlying__getitem__() method.Consequently, if__getitem__() is implemented with constantaccess speed, the mixin methods will have linear performance;however, if the underlying method is linear (as it would be with alinked list), the mixins will have quadratic performance and willlikely need to be overridden.

Changed in version 3.5:The index() method added support forstop andstartarguments.

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 forawaitable objects, which can be used inawaitexpressions. Custom implementations must provide the__await__() method.

Coroutine objects and instances of theCoroutine ABC are all instances of this ABC.

Note

In CPython, generator-based coroutines (generatorsdecorated with@types.coroutine) areawaitables, 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 forcoroutine compatible classes. These implement thefollowing methods, defined inCoroutine Objects:send(),throw(), andclose(). Custom implementations must also implement__await__(). AllCoroutine instances are alsoinstances ofAwaitable.

Note

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

SeeAnnotating generators and coroutinesfor details on usingCoroutine in type annotations.The variance and order of type parameters correspond to those ofGenerator.

Added in version 3.5.

classcollections.abc.AsyncIterable

ABC for classes that provide an__aiter__ method. See also thedefinition 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 generator classes that implement the protocoldefined inPEP 525 andPEP 492.

SeeAnnotating generators and coroutinesfor details on usingAsyncGenerator in 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 provideparticular 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 developclasses supporting container APIs. For example, to write a class supportingthe fullSet API, it is only necessary to supply the three underlyingabstract 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.elementsdef__len__(self):returnlen(self.elements)s1=ListBasedSet('abcdef')s2=ListBasedSet('defghi')overlap=s1&s2# The __and__() method is supported automatically

Notes on usingSet andMutableSet as a mixin:

  1. Since some set operations create new sets, the default mixin methods needa way to create new instances from aniterable. The class constructor isassumed to have a signature in the formClassName(iterable).That assumption is factored-out to an internalclassmethod called_from_iterable() which callscls(iterable) to produce a new set.If theSet mixin is being used in a class with a differentconstructor signature, you will need to override_from_iterable()with a classmethod or regular method that can construct new instances froman iterable argument.

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

  3. TheSet mixin provides a_hash() method to compute a hash valuefor the set; however,__hash__() is not defined because not all setsarehashable or immutable. To add set hashability using mixins,inherit from bothSet() andHashable(), then define__hash__=Set._hash.

See also