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

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

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

Примечания

Абстрактные базовые классы коллекций — подробные описания

class collections.abc.Container

Абстрактный базовый класс для классов, предоставляющих метод __contains__().

class collections.abc.Hashable

Абстрактный базовый класс для классов, предоставляющих метод __hash__().

class collections.abc.Sized

Абстрактный базовый класс для классов, предоставляющих метод __len__().

class collections.abc.Callable

Абстрактный базовый класс для классов, предоставляющих метод __call__().

Подробную информацию об использовании Callable в аннотациях типов см. в разделе Аннотирование вызываемых объектов.

class collections.abc.Iterable

Абстрактный базовый класс для классов, предоставляющих метод __iter__().

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

class collections.abc.Collection

Абстрактный базовый класс для контейнерных классов, которые можно перебирать и размер которых можно определить.

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

class collections.abc.Iterator

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

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

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

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

index(value, start=0, stop=None)

Возвращает первый индекс значения value.

Вызывает исключение ValueError, если значение отсутствует.

Поддержка аргументов start и stop необязательна, но рекомендуется.

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

Устарело начиная с версии 3.12; будет удалено в версии 3.17: Абстрактный базовый класс ByteString объявлен устаревшим.

Используйте isinstance(obj, collections.abc.Buffer), чтобы во время выполнения проверить, реализует ли obj протокол буфера. В аннотациях типов используйте либо Buffer, либо объединение, явно перечисляющее типы, поддерживаемые вашим кодом (например, bytes | bytearray | memoryview).

Изначально ByteString задумывался как абстрактный класс, который служил бы супертипом для bytes и bytearray. Однако у этого абстрактного базового класса никогда не было методов, поэтому знание о том, что объект является экземпляром ByteString, на самом деле ничего полезного об объекте не сообщало. Другие распространённые типы буферов, такие как memoryview, также никогда не считались подтипами ByteString (ни во время выполнения, ни статическими анализаторами типов).

Подробнее см. в PEP 688.

class collections.abc.Set

class collections.abc.MutableSet

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

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

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

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

Примечание

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

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

class collections.abc.Coroutine

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

Примечание

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

Подробную информацию об использовании Coroutine в аннотациях типов см. в разделе Аннотирование генераторов и сопрограмм. Ковариантность и порядок параметров типов соответствуют параметрам Generator.

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

class collections.abc.AsyncIterable

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

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

class collections.abc.AsyncIterator

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

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

class collections.abc.AsyncGenerator

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

Подробную информацию об использовании AsyncGenerator в аннотациях типов см. в разделе Аннотирование генераторов и сопрограмм.

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

class collections.abc.Buffer

Абстрактный базовый класс для классов, предоставляющих метод __buffer__() и реализующих протокол буфера. См. PEP 688.

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

Примеры и рецепты

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

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

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