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

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

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

Сноски

Классы абстрактного базиса коллекций – подробные описания

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__() реализован со скоростью доступа, постоянной во времени, то методы миксинов будут иметь линейную производительность; однако, если базовый метод имеет линейную производительность (как в случае с связанным списком), то миксины будут иметь квадратичную производительность и, вероятно, потребуют переопределения.

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

Устарело начиная с версии 3.12, будет удалено в версии 3.14: ABC ByteString устарел. Для использования в типизации предпочтительнее использовать объединение, например bytes | bytearray, или collections.abc.Buffer. Для использования в качестве ABC предпочтительнее Sequence или collections.abc.Buffer.

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

Объекты сопроцедуры и экземпляры 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) являются awaitable, даже если у них нет метода __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.

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

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):
    ''' 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.