"collections.abc" --- コンテナの抽象基底クラス
**********************************************

Added in version 3.3: 以前はこのモジュールは "collections" モジュール
の一部でした。

**ソースコード:** Lib/_collections_abc.py

======================================================================

このモジュールは、 *抽象基底クラス* を提供します。抽象基底クラスは、ク
ラスが特定のインターフェースを提供しているか、例えば *ハッシュ可能* で
あるかや *マッピング* であるかを判定します。

"issubclass()" や "isinstance()" を使ったインターフェースに対するテス
トは、以下の3つのいずれかの方法で動作します。

1. 新しく作るクラスは、抽象基底クラスのいずれかを直接継承できます。 そ
   のクラスでは、必須の抽象メソッドを実装しなければなりません。 残りの
   mixin メソッドは継承され、必要に応じてオーバーライドできます。 他の
   メソッドも必要に応じて追加できます:

      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 の「仮想サブクラス」として登録
   できます。 それらのクラスでは、すべての抽象メソッドとすべての mixin
   メソッドを含む完全な 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

   この例では、クラス "D" は "__contains__", "__iter__",
   "__reversed__" を定義する必要がありません。なぜなら in 演算子, the
   *反復* ロジック, および "reversed()" 関数は自動的に "__getitem__"
   と "__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" を区
   別するには不十分です。

Added in version 3.9: これらの抽象クラスは "[]" をサポートするようにな
りました。 ジェネリックエイリアス型 および **PEP 585** を参照してくだ
さい。


コレクション抽象基底クラス
==========================

collections モジュールは以下の *ABC (抽象基底クラス)* を提供します:

+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| ABC                            | 継承しているクラス     | 抽象メソッド            | mixin メソッド                                       |
|================================|========================|=========================|======================================================|
| "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",   | "__contains__",         |                                                      |
|                                | "Container"            | "__iter__", "__len__"   |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Sequence"                     | "Reversible",          | "__getitem__",          | "__contains__", "__iter__", "__reversed__", "index", |
|                                | "Collection"           | "__len__"               | "count"                                              |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSequence"              | "Sequence"             | "__getitem__",          | "Sequence" から継承したメソッドと、 "append",        |
|                                |                        | "__setitem__",          | "clear", "reverse", "extend", "pop", "remove",       |
|                                |                        | "__delitem__",          | "__iadd__"                                           |
|                                |                        | "__len__", "insert"     |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ByteString"                   | "Sequence"             | "__getitem__",          | "Sequence" から継承したメソッド                      |
|                                |                        | "__len__"               |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Set"                          | "Collection"           | "__contains__",         | "__le__", "__lt__", "__eq__", "__ne__", "__gt__",    |
|                                |                        | "__iter__", "__len__"   | "__ge__", "__and__", "__or__", "__sub__",            |
|                                |                        |                         | "__rsub__", "__xor__", "__rxor__", "isdisjoint"      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSet"                   | "Set"                  | "__contains__",         | "Set" から継承したメソッドと、 "clear", "pop",       |
|                                |                        | "__iter__", "__len__",  | "remove", "__ior__", "__iand__", "__ixor__",         |
|                                |                        | "add", "discard"        | "__isub__"                                           |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Mapping"                      | "Collection"           | "__getitem__",          | "__contains__", "keys", "items", "values", "get",    |
|                                |                        | "__iter__", "__len__"   | "__eq__", "__ne__"                                   |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableMapping"               | "Mapping"              | "__getitem__",          | "Mapping" から継承したメソッドと、 "pop", "popitem", |
|                                |                        | "__setitem__",          | "clear", "update", "setdefault"                      |
|                                |                        | "__delitem__",          |                                                      |
|                                |                        | "__iter__", "__len__"   |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MappingView"                  | "Sized"                |                         | "__init__", "__len__", "__repr__"                    |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ItemsView"                    | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "KeysView"                     | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ValuesView"                   | "MappingView",         |                         | "__contains__", "__iter__"                           |
|                                | "Collection"           |                         |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "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__"            |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+

-[ 脚注 ]-

[1] これらの抽象基底クラスは "__subclasshook__()" をオーバーライドして
    、必要なメソッドが存在し、かつ "None" に指定されていないことを確か
    めることによってインターフェースをテストすることをサポートします。
    このテストは単純なインターフェースに対してのみ有効に働きます。より
    複雑なインターフェースは基底クラスへの登録や直接派生することが必要
    になります。

[2] "isinstance(obj, Iterable)" によるチェックは "Iterable" として登録
    されたクラスや "__iter__()" メソッドを持つクラスを検出しますが、
    "__getitem__()" メソッドにより反復処理を行うクラスは検出しません。
    オブジェクトがイテラブル (*iterable*) かどうかを確認する唯一の信頼
    できる方法は "iter(obj)" を呼び出すことです。


コレクションの抽象基底クラス -- 詳細な説明
==========================================

class collections.abc.Container

   "__contains__()" メソッドを提供するクラスの ABC です。

class collections.abc.Hashable

   "__hash__()" メソッドを提供するクラスの ABC です。

class collections.abc.Sized

   "__len__()" メソッドを提供するクラスの ABC です。

class collections.abc.Callable

   "__call__()" メソッドを提供するクラスの ABC です。

   "Callable" を型アノテーションで使う方法の詳細は、 呼び出し可能オブ
   ジェクトのアノテーション を参照してください。

class collections.abc.Iterable

   "__iter__()" メソッドを提供するクラスの ABC です。

   "isinstance(obj, Iterable)" によるチェックは "Iterable" として登録
   されたクラスや "__iter__()" メソッドを持つクラスを検出しますが、
   "__getitem__()" メソッドにより反復処理を行うクラスは検出しません。
   オブジェクトがイテラブル (*iterable*) かどうかを確認する唯一の信頼
   できる方法は "iter(obj)" を呼び出すことです。

class collections.abc.Collection

   サイズ付きのイテラブルなコンテナクラスの ABC です。

   Added in version 3.6.

class collections.abc.Iterator

   "__iter__()" メソッドと "__next__()" メソッドを提供するクラスの ABC
   です。 *iterator* の定義も参照してください。

class collections.abc.Reversible

   "__reversed__()" メソッドを提供するイテラブルクラスの ABC です。

   Added in version 3.6.

class collections.abc.Generator

   **PEP 342** で定義された、*イテレータ* を "send()", "throw()",
   "close()" の各メソッドに拡張するプロトコルを実装する、*ジェネレータ
   * クラスの ABC です。

   "Generator" を型アノテーションで使う方法の詳細は、 ジェネレータとコ
   ルーチンのアノテーション を参照してください。

   Added in version 3.5.

class collections.abc.Sequence
class collections.abc.MutableSequence
class collections.abc.ByteString

   読み出し専用の *シーケンス* およびミュータブルなシーケンスの ABC で
   す。

   実装上の注意: "__iter__()"、"__reversed__()"、"index()" などの
   mixin メソッドは、基となる "__getitem__()" メソッドを繰り返し呼び出
   します。 そのため、"__getitem__()" が定数時間でアクセスできるように
   実装されていれば、mixin メソッドの実行時間は線形になります。 しかし
   、基となるメソッドの実行時間が (連結リストの場合のように) 線形なら
   、mixin メソッドの実行時間は二次になり、オーバーライドが必要になる
   可能性が高くなります。

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

      *value* が最初に現れるインデックスを返します。

      値が存在しない場合は "ValueError" を送出します。

      *start* と *stop* 引数のサポートは任意ですが、推奨されます。

      バージョン 3.5 で変更: "index()" メソッドが *stop* と *start* 引
      数をサポートするようになりました。

   バージョン 3.12 で非推奨、バージョン 3.17 で削除予定: "ByteString"
   ABC は非推奨になりました。実行時に "obj" が バッファプロトコル を実
   装しているかどうかを調べるには、"isinstance(obj,
   collections.abc.Buffer)" を使ってください。 型アノテーションでは、
   "Buffer" を使うか、コードがサポートする型を明示した共用体 (例:
   "bytes | bytearray | memoryview") を使ってください。"ByteString" は
   当初、"bytes" と "bytearray" の両方の上位型となる抽象クラスとして意
   図されていました。 しかし、この ABC はメソッドを一つも持たないため
   、あるオブジェクトが "ByteString" のインスタンスだと分かっても、そ
   のオブジェクトに関する有用な情報は何も得られませんでした。
   "memoryview" など、他の一般的なバッファ型も、実行時にも静的型チェッ
   カーによっても "ByteString" のサブタイプとして認識されることはあり
   ませんでした。詳しくは **PEP 688** を参照してください。

class collections.abc.Set
class collections.abc.MutableSet

   読み出し専用の 集合 とミュータブルな集合のための ABC です。

class collections.abc.Mapping
class collections.abc.MutableMapping

   読み出し専用の *マッピング* およびミュータブルなマッピングの ABC で
   す。

class collections.abc.MappingView
class collections.abc.ItemsView
class collections.abc.KeysView
class collections.abc.ValuesView

   マッピング、要素、キー、値の *ビュー* の ABC です。

class collections.abc.Awaitable

   "await" で使用できる *awaitable* オブジェクトの ABC です。カスタム
   の実装は、"__await__()" メソッドを提供しなければなりません。

   *コルーチン* オブジェクトと "Coroutine" ABC のインスタンスは、いず
   れもこの ABC のインスタンスです。

   注釈:

     CPython では、ジェネレータベースのコルーチン ("@types.coroutine"
     でデコレートされた *ジェネレータ*) は、"__await__()" メソッドを持
     たなくても *awaitable* です。 それらに対して "isinstance(gencoro,
     Awaitable)" を使うと "False" が返ります。 検出には
     "inspect.isawaitable()" を使ってください。

   Added in version 3.5.

class collections.abc.Coroutine

   *コルーチン* と互換性のあるクラスの ABC です。これらは、コルーチン
   オブジェクト で定義された "send()", "throw()", "close()" のメソッド
   を実装します。カスタムの実装は、"__await__()" も実装しなければなり
   ません。"Coroutine" のすべてのインスタンスは、 "Awaitable" のインス
   タンスでもあります。

   注釈:

     CPython では、ジェネレータベースのコルーチン ("@types.coroutine"
     でデコレートされた *ジェネレータ*) は、"__await__()" メソッドを持
     たなくても *awaitable* です。 それらに対して "isinstance(gencoro,
     Coroutine)" を使うと "False" が返ります。 検出には
     "inspect.isawaitable()" を使ってください。

   "Coroutine" を型アノテーションで使う方法の詳細は、 ジェネレータとコ
   ルーチンのアノテーション を参照してください。 型パラメータの変性と
   順序は "Generator" と同様です。

   Added in version 3.5.

class collections.abc.AsyncIterable

   "__aiter__" メソッドを提供するクラスの ABC です。*asynchronous
   iterable* の定義も参照してください。

   Added in version 3.5.

class collections.abc.AsyncIterator

   "__aiter__" および "__anext__" メソッドを提供するクラスの ABC です
   。*asynchronous iterator* の定義も参照してください。

   Added in version 3.5.

class collections.abc.AsyncGenerator

   **PEP 525** と **PEP 492** に定義されているプロトコルを実装した *非
   同期ジェネレータ*  クラスの ABC です。

   "AsyncGenerator" を型アノテーションで使う方法の詳細は、 ジェネレー
   タとコルーチンのアノテーション を参照してください。

   Added in version 3.6.

class collections.abc.Buffer

   buffer protocol を実装する "__buffer__()" メソッドを提供するクラス
   のABCです。**PEP 688** を参照してください。

   Added in version 3.12.


例とレシピ
==========

抽象基底クラスは、クラスやインスタンスが特定の機能を提供しているかどう
かを調べることを可能にします。例えば:

   size = None
   if isinstance(myvar, collections.abc.Sized):
       size = len(myvar)

幾つかの ABC はコンテナ型 API を提供するクラスを開発するのを助ける
mixin 型としても使えます。例えば、 "Set" API を提供するクラスを作る場
合、3つの基本になる抽象メソッド "__contains__()", "__iter__()",
"__len__()" だけが必要です。ABC が残りの "__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 型として利用するときの注意点:

1. 幾つかの set の操作は新しい set を作るので、デフォルトの mixin メソ
   ッドは *イテラブル* から新しいインスタンスを作成する方法を必要とし
   ます。クラスのコンストラクタは "ClassName(iterable)" の形のシグネチ
   ャを持つと仮定されます。内部の "_from_iterable()" という
   "classmethod" が "cls(iterable)" を呼び出して新しい set を作る部分
   でこの仮定が使われています。コンストラクタのシグネチャが異なるクラ
   スで "Set" を使う場合は、 iterable 引数から新しいインスタンスを生成
   できるクラスメソッドあるいは仕様に沿ったメソッドで
   "_from_iterable()" をオーバーライドする必要があります。

2. (たぶん意味はそのままに速度を向上する目的で)比較をオーバーライドす
   る場合、 "__le__()" と "__ge__()" だけを再定義すれば、その他の演算
   は自動的に追随します。

3. "Set" mixin は集合のハッシュ値を計算する "_hash()" メソッドを提供し
   ます。 しかし、すべての集合が *ハッシュ可能* またはイミュータブルで
   あるとは限らないため、"__hash__()" は定義されていません。 mixin を
   使って集合をハッシュ可能にするには、"Set" と "Hashable" の両方を継
   承し、"__hash__ = Set._hash" を定義してください。

参考:

  * "MutableSet" を使った例として OrderedSet recipe。

  * ABCs についての詳細は、 "abc" モジュールと **PEP 3119** を参照して
    ください。
