collections.abc — Абстрактные базовые классы для контейнеров

Добавлено в версии 3.3: Ранее этот модуль был частью модуля collections.

Исходный код: Lib/_collections_abc.py


Модуль предоставляет абстрактные базовые классы, которые можно использовать для проверки того, предоставляет ли класс определенный интерфейс; например, является ли он хешируемым или отображением.

Коллекции абстрактных базовых классов

Модуль collections предлагает следующие ABC:

ABC Наследуется от Абстрактные методы Методы миксин
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, 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

ABC для классов, предоставляющие __contains__() метод.

class collections.abc.Hashable

ABC для классов, предоставляющие __hash__() метод.

class collections.abc.Sized

ABC для классов, предоставляющие __len__() метод.

class collections.abc.Callable

ABC для классов, предоставляющие __call__() метод.

class collections.abc.Iterable

ABC для классов, предоставляющие __iter__() метод.

Проверка isinstance(obj, Iterable) обнаруживает классы, зарегистрированные как Iterable или имеющие метод __iter__(), но не обнаруживает классы, которые повторяются с методом __getitem__(). Единственный надежный способ определить, является ли объект итерируемым — вызвать iter(obj).

class collections.abc.Collection

ABC для размерных итераторов классов.

Добавлено в версии 3.6.

class collections.abc.Iterator

ABC для классов, предоставляющие методы __iter__() и __next__(). См. также определение итератора.

class collections.abc.Reversible

ABC для итерируемых классов, которые также предоставляют __reversed__() метод.

Добавлено в версии 3.6.

class collections.abc.Generator

ABC для классов генераторов, реализующих протокол, определенный в PEP 342, который расширяет итераторы с помощью методов send(), throw() и close(). См. также определение генератора.

Добавлено в версии 3.5.

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

ABC для только для чтения и изменяемых последовательностей.

Примечание по реализации: некоторые из методов миксин, такие как __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

ABC для только для чтения и изменяемых отображений.

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

ABC для отображения, элементов, ключей и значений представлений.

class collections.abc.Awaitable

ABC для awaitable объектов, которые можно использовать в await выражениях. Пользовательские реализации должны предоставлять __await__() метод.

Объекты корутины и все экземпляры Coroutine ABC являющиеся экземплярами данного ABC.

Примечание

В CPython корутины (сопрограммы) на основе генераторов (генераторы, декорированные types.coroutine() или asyncio.coroutine()) являются ожидаемыми, даже если у них нет метода __await__(). Использование isinstance(gencoro, Awaitable) для них вернёт False. Используйте inspect.isawaitable() для их обнаружения.

Добавлено в версии 3.5.

class collections.abc.Coroutine

ABC для классов, совместимых с корутинами. Они реализуют следующие методы, определенные в Объекты корутины: send(), throw() и close(). Пользовательские реализации также должны реализовывать __await__(). Все экземпляры Coroutine также являются экземплярами Awaitable. См. также определение корутины.

Примечание

В CPython корутины на основе генераторов (генераторы, декорированные types.coroutine() или asyncio.coroutine()) являются ожидаемыми, даже если у них нет метода __await__(). Использование isinstance(gencoro, Coroutine) для них вернёт False. Используйте inspect.isawaitable() для их обнаружения.

Добавлено в версии 3.5.

class collections.abc.AsyncIterable

ABC для классов, предоставляющих __aiter__ метод. См. также определение асинхронный итерируемый.

Добавлено в версии 3.5.

class collections.abc.AsyncIterator

ABC для классов, предоставляющих __aiter__ и __anext__ методы. См. также определение асинхронный итератор.

Добавлено в версии 3.5.

class collections.abc.AsyncGenerator

ABC для классов асинхронных генераторов, реализующих протокол, определенный в PEP 525 и PEP 492.

Добавлено в версии 3.6.

Данные ABC позволяют нам, например, спрашивать у классов или экземпляров, предоставляют ли они определенные функции:

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

Некоторые из ABC также полезны в качестве миксинов, которые упрощают разработку классов, поддерживающих API-интерфейсы контейнеров. Например, чтобы написать класс, поддерживающий полный API Set, необходимо предоставить только три базовых абстрактных метода: __contains__(), __iter__() и __len__(). ABC предоставляет остальные методы, такие как __and__() и isdisjoint():

class ListBasedSet(collections.abc.Set):
    ''' Альтернативная реализация множества, предпочитающая пространство над скоростью
       и не требует, чтобы заданные элементы были хэшируемыми. '''
    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            # Метод __and__() поддерживатся автоматически

Примечания по использованию Set и MutableSet как миксин:

  1. Поскольку некоторые операции над множествами создают новые множества, методы миксин по умолчанию нуждаются в способе создания новых экземпляров из итерируемого объекта. Предполагается, что у конструктора класса есть сигнатура в форме ClassName(iterable). Это предположение переносится во внутреннему методу класса _from_iterable(), который вызывает cls(iterable) для создания нового множества. Если миксин Set используется в классе с другой сигнатурой конструктора, вам нужно переопределить _from_iterable() с помощью метода класса, который может создавать новые экземпляры из итерируемого аргумента.
  2. Чтобы переопределить сравнения (предположительно для скорости, поскольку семантика фиксирована), переопределите __le__() и __ge__(), тогда другие операции будут автоматически следовать этому примеру.
  3. Миксин Set предоставляет метод _hash() для вычисления хэш- значения для множества; однако __hash__() не определён, потому что не все множества являются хешируемыми или неизменяемыми. Чтобы добавить хэшируемость множества с помощью миксинов, наследуйте его от Set() и Hashable(), затем определите __hash__ = Set._hash.

См.также