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

集合抽象基底類別的詳細描述¶

classcollections.abc.Container¶

有提供__contains__() 方法之類別的 ABC。

classcollections.abc.Hashable¶

有提供__hash__() 方法之類別的 ABC。

classcollections.abc.Sized¶

有提供__len__() 方法之類別的 ABC。

classcollections.abc.Callable¶

有提供__call__() 方法之類別的 ABC。

See註釋 callable 物件 for details on how to useCallable in type annotations.

classcollections.abc.Iterable¶

有提供__iter__() 方法之類別的 ABC。

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¶

有提供__iter__() 和__next__() 方法之類別的 ABC。另請參閱iterator 的定義。

classcollections.abc.Reversible¶

亦有提供__reversed__() 方法之可疊代類別的 ABC。

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

唯讀且可變序列的 ABC。

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

index(value,start=0,stop=None)¶

回傳value 的第一個索引。

如果找不到該值，則引發ValueError。

建議要支援start 和stop 引數，但並非必要。

在 3.5 版的變更:Theindex() method gained support forthestop andstart arguments.

Deprecated since version 3.12, will be removed in version 3.17:ByteString ABC 已被棄用。

Useisinstance(obj,collections.abc.Buffer) to test ifobjimplements thebuffer protocol at runtime. For usein type annotations, either useBuffer or a union thatexplicitly specifies the types your code supports (e.g.,bytes|bytearray|memoryview).

ByteString 最初被設計為一個抽象類別，以作為bytes 和bytearray 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是ByteString 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如memoryview 也從未被理解為ByteString 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多詳細資訊請參閱PEP 688。

classcollections.abc.Set¶

classcollections.abc.MutableSet¶

唯讀且可變集合的 ABC。

classcollections.abc.Mapping¶

classcollections.abc.MutableMapping¶

唯讀且可變對映的 ABC。

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.