collections.abc
--- コレクションの抽象基底クラス¶
バージョン 3.3 で追加: 以前はこのモジュールは collections
モジュールの一部でした。
ソースコード: Lib/_collections_abc.py
This module provides abstract base classes that can be used to test whether a class provides a particular interface; for example, whether it is hashable or whether it is a mapping.
issubclass()
や isinstance()
を使ったインターフェースに対するテストは、以下の3つのいずれかの方法で動作します。
1) 新しく定義したクラスは抽象基底クラスのいずれかを直接継承することができます。その場合クラスは必要な抽象メソッドを提供しなければなりません。残りのミックスインメソッドは継承により引き継がれますが、必要ならオーバーライドすることができます。その他のメソッドは必要に応じて追加することができます:
class C(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
def count(self, value): ... # Optionally override a mixin method
>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True
2) 既存のクラスや組み込みのクラスを "仮想派生クラス" として ABC に登録することができます。これらのクラスは、全ての抽象メソッドとミックスインメソッドを含む完全な API を定義する必要があります。これにより、そのクラスが完全なインターフェースをサポートしているかどうかを、ユーザーが issubclass()
や isinstance()
で判断できるようになります。このルールの例外は、残りの API から自動的に推測ができるようなメソッドです:
class D: # No inheritance
def __init__(self): ... # Extra method not required by the ABC
def __getitem__(self, index): ... # Abstract method
def __len__(self): ... # Abstract method
def count(self, value): ... # Mixin method
def index(self, value): ... # Mixin method
Sequence.register(D) # Register instead of inherit
>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True
In this example, class D
does not need to define
__contains__
, __iter__
, and __reversed__
because the
in-operator, the iteration
logic, and the reversed()
function automatically fall back to
using __getitem__
and __len__
.
3) いくつかの単純なインターフェースは、必要なメソッドの存在だけで (それらのメソッドが None
に設定されていなければ) 直接認識されます:
class E:
def __iter__(self): ...
def __next__(self): ...
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
複雑なインターフェースは、単に特定のメソッドが存在すること以上の定義を持つため、3番目のテクニックをサポートしていません。それらのインターフェースはメソッドの意味やメソッド間の関係まで指定するので、特定のメソッド名の存在からだけではインターフェースの推測ができません。たとえば、あるクラスが __getitem__
, __len__
, および __iter__
を提供するというだけでは、 Sequence
と Mapping
を区別するには不十分です。
バージョン 3.9 で追加: これらの抽象クラスは []
をサポートするようになりました。 ジェネリックエイリアス型 および PEP 585 を参照してください。
コレクション抽象基底クラス¶
collections モジュールは以下の ABC (抽象基底クラス) を提供します:
ABC |
継承しているクラス |
抽象メソッド |
mixin メソッド |
---|---|---|---|
|
|||
|
|||
|
|||
|
|
||
|
|||
|
|
||
|
|||
|
|||
|
|||
|
|
||
|
Inherited |
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|
||
|
|||
|
|
||
|
|
||
|
脚注
コレクションの抽象基底クラス -- 詳細な説明¶
- class collections.abc.Container¶
ABC for classes that provide the
__contains__()
method.
- class collections.abc.Hashable¶
ABC for classes that provide the
__hash__()
method.
- class collections.abc.Callable¶
ABC for classes that provide the
__call__()
method.
- class collections.abc.Iterable¶
ABC for classes that provide the
__iter__()
method.Checking
isinstance(obj, Iterable)
detects classes that are registered asIterable
or 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 is iterable is to calliter(obj)
.
- class collections.abc.Collection¶
サイズ付きのイテラブルなコンテナクラスの ABC です。
バージョン 3.6 で追加.
- class collections.abc.Iterator¶
__iter__()
メソッドと__next__()
メソッドを提供するクラスの ABC です。 iterator の定義も参照してください。
- class collections.abc.Reversible¶
ABC for iterable classes that also provide the
__reversed__()
method.バージョン 3.6 で追加.
- class collections.abc.Generator¶
ABC for generator classes that implement the protocol defined in PEP 342 that extends iterators with the
send()
,throw()
andclose()
methods.バージョン 3.5 で追加.
- class collections.abc.Sequence¶
- class collections.abc.MutableSequence¶
- class collections.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 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.バージョン 3.5 で変更: index() メソッドは stop と start 引数をサポートしました。
バージョン 3.12 で非推奨、バージョン 3.14 で削除予定: The
ByteString
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
.
- class collections.abc.MappingView¶
- class collections.abc.ItemsView¶
- class collections.abc.KeysView¶
- class collections.abc.ValuesView¶
マッピング、要素、キー、値の ビュー の ABC です。
- class collections.abc.Awaitable¶
ABC for awaitable objects, which can be used in
await
expressions. Custom implementations must provide the__await__()
method.Coroutine
ABC の Coroutine オブジェクトとインスタンスは、すべてこの ABC のインスタンスです。注釈
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.バージョン 3.5 で追加.
- class collections.abc.Coroutine¶
ABC for coroutine compatible classes. These implement the following methods, defined in コルーチンオブジェクト:
send()
,throw()
, andclose()
. Custom implementations must also implement__await__()
. AllCoroutine
instances are also instances ofAwaitable
.注釈
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.バージョン 3.5 で追加.
- class collections.abc.AsyncIterable¶
ABC for classes that provide an
__aiter__
method. See also the definition of asynchronous iterable.バージョン 3.5 で追加.
- class collections.abc.AsyncIterator¶
__aiter__
および__anext__
メソッドを提供するクラスの ABC です。asynchronous iterator の定義も参照してください。バージョン 3.5 で追加.
- class collections.abc.AsyncGenerator¶
ABC for asynchronous generator classes that implement the protocol defined in PEP 525 and PEP 492.
バージョン 3.6 で追加.
- class collections.abc.Buffer¶
ABC for classes that provide the
__buffer__()
method, implementing the buffer protocol. See PEP 688.バージョン 3.12 で追加.
例とレシピ¶
抽象基底クラスは、クラスやインスタンスが特定の機能を提供しているかどうかを調べることを可能にします。例えば:
size = None
if isinstance(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 full Set
API, it is only necessary to supply the three underlying
abstract methods: __contains__()
, __iter__()
, and
__len__()
. The ABC supplies the remaining methods such as
__and__()
and isdisjoint()
:
class ListBasedSet(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 = []
for value in iterable:
if value not in lst:
lst.append(value)
def __iter__(self):
return iter(self.elements)
def __contains__(self, value):
return value in self.elements
def __len__(self):
return len(self.elements)
s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2 # The __and__() method is supported automatically
Set
と MutableSet
を mixin 型として利用するときの注意点:
Since some set operations create new sets, the default mixin methods need a way to create new instances from an iterable. The class constructor is assumed to have a signature in the form
ClassName(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 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.To override the comparisons (presumably for speed, as the semantics are fixed), redefine
__le__()
and__ge__()
, then the other operations will automatically follow suit.The
Set
mixin provides a_hash()
method to compute a hash value for the set; however,__hash__()
is not defined because not all sets are hashable or immutable. To add set hashability using mixins, inherit from bothSet()
andHashable()
, then define__hash__ = Set._hash
.
参考
MutableSet
を使った例として OrderedSet recipe。