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

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

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

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

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

class collections.abc.Container

class collections.abc.Hashable

class collections.abc.Sized

class collections.abc.Callable

ABCs for classes that provide respectively the methods __contains__(), __hash__(), __len__(), and __call__().

class collections.abc.Iterable

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

class collections.abc.Iterator

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

class collections.abc.Generator

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

Новое в версии 3.5.

class collections.abc.Sequence

class collections.abc.MutableSequence

class collections.abc.ByteString

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

Примечание для реализации: Некоторые из методов-миксинов, такие как __iter__(), __reversed__() и index(), вызывают метод __getitem__() многократно. Следовательно, если метод __getitem__() имеет постоянную скорость доступа, методы-миксины будут иметь линейную производительность; однако, если базовый метод имеет линейную производительность (как в случае со списком ссылок), миксины будут иметь квадратичную производительность и, вероятно, потребуют переопределения.

Изменено в версии 3.5: Метод index() получил поддержку аргументов stop и start.

class collections.abc.Set

class collections.abc.MutableSet

ABCs для неизменяемых и изменяемых множеств.

class collections.abc.Mapping

class collections.abc.MutableMapping

ABCs для неизменяемых и изменяемых отображений.

class collections.abc.MappingView

class collections.abc.ItemsView

class collections.abc.KeysView

class collections.abc.ValuesView

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

class collections.abc.Awaitable

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

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

Примечание

В CPython, генераторы-корутины (генераторы, декорированные types.coroutine() или asyncio.coroutine()) являются awaitable, даже если у них нет метода __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()) являются awaitable, даже если у них нет метода __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.

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