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

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

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

Сноски

Абстрактные базовые классы коллекций – Подробные описания¶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__().

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

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().

См. Аннотирование генераторов и корутин для подробностей об использовании Generator в аннотациях типов.

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

class collections.abc.Sequence¶

class collections.abc.MutableSequence¶

class collections.abc.ByteString¶

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

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

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

Возвращает индекс первого вхождения value.

Возбуждает ValueError, если значение отсутствует.

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

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

Устарело с версии 3.12, будет удалено в версии 3.17: ABC ByteString устарел.

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

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

См. PEP 688 для получения дополнительных сведений.

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) являются ожидаемыми объектами, даже если они не имеют метода __await__(). Использование isinstance(gencoro, Awaitable) для них вернёт False. Для их обнаружения используется inspect.isawaitable().

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

class collections.abc.Coroutine¶

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

Примечание

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

См. Аннотирование генераторов и корутин для подробностей об использовании Coroutine в аннотациях типов. Вариантность и порядок параметров типа соответствуют таковым у Generator.

Добавлено в версии 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.

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

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

class collections.abc.Buffer¶

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

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

Примеры и рецепты¶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). Это предположение вынесено во внутренний classmethod, называемый _from_iterable(), который вызывает cls(iterable) для создания нового множества. Если миксин Set используется в классе с другой сигнатурой конструктора, потребуется переопределить _from_iterable() с помощью метода класса или обычного метода, который может создавать новые экземпляры из итерируемого аргумента.

2. Чтобы переопределить сравнения (предположительно для скорости, так как семантика фиксирована), переопределите __le__() и __ge__(); тогда остальные операции автоматически последуют их примеру.

3. Миксин Set предоставляет метод _hash() для вычисления хеш-значения множества; однако __hash__() не определён, поскольку не все множества являются хешируемыми или неизменяемыми. Чтобы добавить хешируемость множеству с помощью миксинов, наследуйтесь от обоих Set и Hashable, а затем определите __hash__ = Set._hash.