Collections Abstract Base Classes¶

The collections module offers the followingABCs:

註腳

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.

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.

See註釋 callable 物件 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.

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

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

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

在 3.5 版的變更:The index() method added support forstop andstartarguments.

Deprecated since version 3.12, will be removed in version 3.14:TheByteString ABC has been deprecated.For use in typing, prefer a union, likebytes|bytearray, orcollections.abc.Buffer.For use as an ABC, preferSequence orcollections.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 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.

備註

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.

在 3.5 版被加入.

classcollections.abc.Coroutine¶

ABC forcoroutine compatible classes. These implement thefollowing methods, defined in協程物件:send(),throw(), andclose(). Custom implementations must also implement__await__(). AllCoroutine instances are alsoinstances ofAwaitable.

備註

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.

在 3.5 版被加入.

classcollections.abc.AsyncIterable¶

ABC for classes that provide an__aiter__ method. See also thedefinition ofasynchronous iterable.

在 3.5 版被加入.

classcollections.abc.AsyncIterator¶

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

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

在 3.6 版被加入.

classcollections.abc.Buffer¶

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

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