Collections Abstract Base Classes¶

The collections module offers the followingABCs:

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.

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.

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

New in version 3.6.

classcollections.abc.Generator¶

ABC for generator classes that implement the protocol defined inPEP 342 that extends iterators with thesend(),throw() andclose() methods.See also the definition ofgenerator.

New 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(), 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 mutable sets.

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 (generators decorated withtypes.coroutine() orasyncio.coroutine()) areawaitables, 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.

classcollections.abc.Coroutine¶

ABC for coroutine compatible classes. These implement thefollowing methods, defined inCoroutine Objects:send(),throw(), andclose(). Custom implementations must also implement__await__(). AllCoroutine instances are also instances ofAwaitable. See also the definition ofcoroutine.

Note

In CPython, generator-based coroutines (generators decorated withtypes.coroutine() orasyncio.coroutine()) areawaitables, 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.

classcollections.abc.AsyncIterable¶

ABC for classes that provide__aiter__ method. See also thedefinition ofasynchronous iterable.

New in version 3.5.

classcollections.abc.AsyncIterator¶

ABC for classes that provide__aiter__ and__anext__methods. See also the definition ofasynchronous iterator.

New in version 3.5.

classcollections.abc.AsyncGenerator¶

ABC for asynchronous generator classes that implement the protocoldefined inPEP 525 andPEP 492.

New in version 3.6.

These 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 an iterable. The class constructor isassumed to have a signature in the formClassName(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 differentconstructor signature, you will need to override_from_iterable()with a classmethod 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 setsare hashable or immutable. To add set hashability using mixins,inherit from bothSet() andHashable(), then define__hash__=Set._hash.