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

3.3 新版功能: 该模块曾是 collections 模块的组成部分。

源代码: Lib/_collections_abc.py


该模块定义了一些 抽象基类,它们可用于判断一个具体类是否具有某一特定的接口;例如,这个类是否可哈希,或其是否为映射类。

容器抽象基类

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

ABC

继承自

抽象方法

Mixin 方法

Container

__contains__

Hashable

__hash__

Iterable

__iter__

Iterator

Iterable

__next__

__iter__

Reversible

Iterable

__reversed__

Generator

Iterator

send, throw

close, __iter__, __next__

Sized

__len__

Callable

__call__

Collection

Sized, Iterable, Container

__contains__, __iter__, __len__

Sequence

Reversible, Collection

__getitem__, __len__

__contains__, __iter__, __reversed__, index, and count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

继承自 Sequence 的方法,以及 append, 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__, and 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__, and __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

__await__

Coroutine

Awaitable

send, throw

close

AsyncIterable

__aiter__

AsyncIterator

AsyncIterable

__anext__

__aiter__

AsyncGenerator

AsyncIterator

asend, athrow

aclose, __aiter__, __anext__

class collections.abc.Container
class collections.abc.Hashable
class collections.abc.Sized
class collections.abc.Callable

分别提供了 __contains__(), __hash__(), __len__()__call__() 方法的抽象基类。

class collections.abc.Iterable

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

使用 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__() 方法的抽象基类。

3.6 新版功能.

class collections.abc.Generator

生成器类,实现了 PEP 342 中定义的协议,继承并扩展了迭代器,提供了 send(), throw()close() 方法。参见 generator 的定义。

3.5 新版功能.

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

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

实现笔记:一些混入(Maxin)方法比如 __iter__(), __reversed__()index() 会重复调用底层的 __getitem__() 方法。因此,如果实现的 __getitem__() 是常数级访问速度,那么相应的混入方法会有一个线性的表现;然而,如果底层方法是线性实现(例如链表),那么混入方法将会是平方级的表现,这也许就需要被重构了。

在 3.5 版更改: index() 方法支持 stopstart 参数。

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

只读且可变的集合的抽象基类。

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

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

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

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

class collections.abc.Awaitable

为可等待对象 awaitable 提供的类,可以被用于 await 表达式中。习惯上必须实现 __await__() 方法。

协程对象 CoroutineCoroutine 抽象基类的实例都是这个抽象基类的实例。

注解

在 CPython 里,基于生成器的协程(使用 types.coroutine()asyncio.coroutine() 包装的生成器)都是 可等待对象,即使他们不含有 __await__() 方法。使用 isinstance(gencoro, Awaitable) 来检测他们会返回 False。要使用 inspect.isawaitable() 来检测他们。

3.5 新版功能.

class collections.abc.Coroutine

ABC for coroutine compatible classes. These implement the following methods, defined in 协程对象: send(), throw(), and close(). Custom implementations must also implement __await__(). All Coroutine instances are also instances of Awaitable. See also the definition of coroutine.

注解

In CPython, generator-based coroutines (generators decorated with types.coroutine() or asyncio.coroutine()) are awaitables, even though they do not have an __await__() method. Using isinstance(gencoro, Coroutine) for them will return False. Use inspect.isawaitable() to detect them.

3.5 新版功能.

class collections.abc.AsyncIterable

ABC for classes that provide __aiter__ method. See also the definition of asynchronous iterable.

3.5 新版功能.

class collections.abc.AsyncIterator

ABC for classes that provide __aiter__ and __anext__ methods. See also the definition of 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 新版功能.

These ABCs allow us to ask classes or instances if they provide particular functionality, for example:

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

Notes on using Set and MutableSet as a mixin:

  1. 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 internal classmethod called _from_iterable() which calls cls(iterable) to produce a new set. If the Set mixin is being used in a class with a different constructor signature, you will need to override _from_iterable() with a classmethod that can construct new instances from an iterable argument.

  2. To override the comparisons (presumably for speed, as the semantics are fixed), redefine __le__() and __ge__(), then the other operations will automatically follow suit.

  3. 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 both Set() and Hashable(), then define __hash__ = Set._hash.

参见