collections.abc – Абстрактные базовые классы для контейнеров¶collections.abc – Abstract Base Classes for Containers

Абстрактные базовые классы коллекций¶Collections Abstract Base Classes

Модуль collections предоставляет следующие абстрактные базовые классы:

Сноски

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

Эти ABC переопределяют object.__subclasshook__() для поддержки проверки интерфейса путём проверки, что требуемые методы присутствуют и не были установлены в None. Это работает только для простых интерфейсов. Более сложные интерфейсы требуют регистрации или прямого наследования.

2

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

Абстрактные базовые классы коллекций – Подробные описания¶Collections Abstract Base Classes – Detailed Descriptions

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 для ожидаемых объектов, которые могут использоваться в выражениях await. Пользовательские реализации должны предоставлять метод __await__() .

Объекты Coroutine и экземпляры ABC Coroutine являются экземплярами этого 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.

Примеры и рецепты¶Examples and Recipes

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

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

Некоторые из ABC также полезны в качестве примесей (mixins), упрощающих разработку классов, поддерживающих 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.