# `collections.abc` --- 容器的抽象基类

在 3.3 版新加入: 该模块曾是 `collections` 模块的组成部分。

原始碼：Lib/_collections_abc.py

本模块提供了一些 抽象基类，它们可被用于测试一个类是否提供某个特定的接口；例如，它是否为 hashable 或是否为 mapping 等。

一个接口的 `issubclass()` 或 `isinstance()` 测试采用以下三种方式之一。

1) A newly written class can inherit directly from one of the abstract base classes. The class must supply the required abstract methods. The remaining mixin methods come from inheritance and can be overridden if desired. Other methods may be added as needed:

    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) Existing classes and built-in classes can be registered as "virtual subclasses" of the ABCs. Those classes should define the full API including all of the abstract methods and all of the mixin methods. This lets users rely on `issubclass()` or `isinstance()` tests to determine whether the full interface is supported. The exception to this rule is for methods that are automatically inferred from the rest of the 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 运算符, 迭代 逻辑和 `reversed()` 函数会自动回退为使用 `__getitem__` 和 `__len__`。

3) Some simple interfaces are directly recognizable by the presence of the required methods (unless those methods have been set to `None`):

    class E:
        def __iter__(self): ...
        def __next__(self): ...

    >>> issubclass(E, Iterable)
    True
    >>> isinstance(E(), Iterable)
    True

复杂的接口不支持最后这种技术手段因为接口并不只是作为方法名称存在。 接口指明了方法之间的语义和关系，这些是无法根据特定方法名称的存在推断出来的。 例如，知道一个类提供了 `__getitem__`, `__len__` 和 `__iter__` 并不足以区分 `Sequence` 和 `Mapping`。

在 3.9 版新加入: 这些抽象类现在都支持 `[]`。 参见 GenericAlias 类型 和 PEP 585。

## 容器抽象基类

这个容器模块提供了以下 ABCs:

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`、`Container` | `__contains__`、`__iter__`、`__len__` |
`Sequence` | `Reversible`, `Collection` | `__getitem__`、`__len__` | `__contains__`、`__iter__`、`__reversed__`、`index` 和 `count`
`MutableSequence` | `Sequence` | `__getitem__`、`__setitem__`、`__delitem__`、`__len__`、`insert` | 继承了 `Sequence` 的方法以及 `append`, `clear`, `reverse`, `extend`, `pop`, `remove` 和 `__iadd__`
`ByteString` | `Sequence` | `__getitem__`、`__len__` | 继承自 `Sequence` 的方法
`Set` | `Collection` | `__contains__`、`__iter__`、`__len__` | `__le__`、`__lt__`、`__eq__`、`__ne__`、`__gt__`、`__ge__`、`__and__`、`__or__`、`__sub__`、`__xor__` 與 `isdisjoint`
`MutableSet` | `Set` | `__contains__`、`__iter__`、`__len__`、`add`、`discard` | 继承自 `Set` 的方法以及 `clear`, `pop`, `remove`, `__ior__`, `__iand__`, `__ixor__`，和 `__isub__`
`Mapping` | `Collection` | `__getitem__`、`__iter__`、`__len__` | `__contains__`、`keys`、`items`、`values`、`get`、`__eq__` 和 `__ne__`
`MutableMapping` | `Mapping` | `__getitem__`、`__setitem__`、`__delitem__`、`__iter__`、`__len__` | 继承自 `Mapping` 的方法以及 `pop`, `popitem`, `clear`, `update`，和 `setdefault`
`MappingView` | `Sized` |  | `__len__`
`ItemsView` | `MappingView`、`Set` |  | `__contains__`、`__iter__`
`KeysView` | `MappingView`、`Set` |  | `__contains__`、`__iter__`
`ValuesView` | `MappingView`、`Collection` |  | `__contains__`、`__iter__`
`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__`

註解

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14)

这些 ABC 重写了 `__subclasshook__()` 以便支持通过验证所需的方法是否存在并且没有被设为 `None` 来测试一个接口。 这只适用于简单的接口。 更复杂的接口需要注册或者直接子类化。

[2]

检查 `isinstance(obj, Iterable)` 是否侦测到被注册为 `Iterable` 或者具有 `__iter__()` 方法的类，但它不能侦测到使用 `__getitem__()` 方法进行迭代的类。 确定一个对象是否为 iterable 的唯一可靠方式是调用 `iter(obj)`。

## 多项集抽象基类 -- 详细描述

class collections.abc.Container

  提供了 `__contains__()` 方法的抽象基类。

class collections.abc.Hashable

  提供了 `__hash__()` 方法的抽象基类。

class collections.abc.Sized

  用于提供 `__len__()` 方法的类的 ABC

class collections.abc.Callable

  用于提供 `__call__()` 方法的类的 ABC

class collections.abc.Iterable

  用于提供 `__iter__()` 方法的类的 ABC

  检查 `isinstance(obj, Iterable)` 是否侦测到被注册为 `Iterable` 或者具有 `__iter__()` 方法的类，但它不能侦测到使用 `__getitem__()` 方法进行迭代的类。 确定一个对象是否为 iterable 的唯一可靠方式是调用 `iter(obj)`。

class collections.abc.Collection

  集合了 Sized 和 Iterable 类的抽象基类。

  在 3.6 版新加入.

class collections.abc.Iterator

  提供了 `__iter__()` 和 `__next__()` 方法的抽象基类。参见 iterator 的定义。

class collections.abc.Reversible

  用于同时提供了 `__reversed__()` 方法的可迭代类的 ABC

  在 3.6 版新加入.

class collections.abc.Generator

  用于实现了 PEP 342 中定义的协议的 generator 类的 ABC，它通过 `send()`, `throw()` 和 `close()` 方法对 迭代器 进行了扩展。

  在 3.5 版新加入.

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

  只读的与可变的 序列 的抽象基类。

  实现注意事项：某些混入方法，如 `__iter__()`, `__reversed__()` 和 `index()`，会重复调用下层的 `__getitem__()` 方法。 因此，如果 `__getitem__()` 被实现为常数级访问速度，则混入方法的性能将为线性级；但是，如果下层的方法是线性的（例如链表就是如此），则混入方法的性能将为平方级并可能需要被重写。

  在 3.5 版的變更: index() 方法支持 stop 和 start 参数。

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

  用于只读和可变 集合 的 ABC。

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

  只读的与可变的 映射 的抽象基类。

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

  映射及其键和值的 视图 的抽象基类。

class collections.abc.Awaitable

  针对 awaitable 对象的 ABC，它可被用于 `await` 表达式。 根据惯例所有实现都必须提供 `__await__()` 方法。

  协程 对象和 `Coroutine` ABC 的实例都是这个 ABC 的实例。

  備註

  在 CPython 中，基于生成器的协程 (使用 `@types.coroutine` 装饰的 生成器) 都是 可等待对象，即使它们没有 `__await__()` 方法。 对它们使用 `isinstance(gencoro, Awaitable)` 将返回 `False`。 请使用 `inspect.isawaitable()` 来检测它们。

  在 3.5 版新加入.

class collections.abc.Coroutine

  用于 coroutine 兼容类的 ABC。 实现了如下定义在 协程对象 里的方法: `send()`, `throw()` 和 `close()`。 根据惯例所有实现都还需要实现 `__await__()`。 所有的 `Coroutine` 实例同时也是 `Awaitable` 的实例。

  備註

  在 CPython 中，基于生成器的协程 (使用 `@types.coroutine` 装饰的 生成器) 都是 可等待对象，即使它们没有 `__await__()` 方法。 对它们使用 `isinstance(gencoro, Coroutine)` 将返回 `False`。 请使用 `inspect.isawaitable()` 来检测它们。

  在 3.5 版新加入.

class collections.abc.AsyncIterable

  针对提供了 `__aiter__` 方法的类的 ABC。 另请参阅 asynchronous iterable 的定义。

  在 3.5 版新加入.

class collections.abc.AsyncIterator

  提供了 `__aiter__` 和 `__anext__` 方法的抽象基类。参见 asynchronous iterator 的定义。

  在 3.5 版新加入.

class collections.abc.AsyncGenerator

  针对实现了在 PEP 525 和 PEP 492 中定义的协议的 asynchronous generator 类的 ABC。

  在 3.6 版新加入.

## 例子和配方

ABC 允许我们询问类或实例是否提供特定的功能，例如:

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

有些 ABC 还适用于作为混入类，这可以更容易地开发支持容器 API 的类。 例如，要写一个支持完整 `Set` API 的类，只需要提供三个下层抽象方法: `__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` 用作混入类时需注意：

1. 由于某些集合操作会创建新的集合，默认的混入方法需要一种根据 iterable 创建新实例的方式。 类构造器应当具有 `ClassName(iterable)` 形式的签名。 这样它将被重构为一个执行 `_from_iterable()` 的内部 `classmethod`，该方法会调用 `cls(iterable)` 来产生一个新的集合。 如果 `Set` 混入类在具有不同构造器签名的类中被使用，你将需要通过一个能根据可迭代对象参数构造新实例的类方法或常规方法来重写 `_from_iterable()`。

2. 要重写比较运算（应该是为了提高速度，因为其语义是固定的），请重新定义 `__le__()` 和 `__ge__()`，然后其他运算将自动跟进。

3. `Set` 混入类提供了一个 `_hash()` 方法为集合计算哈希值；但是，`__hash__()` 没有被定义因为并非所有集合都是 hashable 或不可变对象。 要使用混入类为集合添加可哈希性，请同时继承 `Set()` 和 `Hashable()`，然后定义 `__hash__ = Set._hash`。

也參考

- OrderedSet recipe 是基于 `MutableSet` 构建的一个示例。

- 關於 ABC 的更多資訊請見 `abc` module 和 PEP 3119。