collections.abc
— Абстрактные базовые классы для контейнеров¶
Added in version 3.3: Раньше этот модуль был частью модуля collections
.
Источник: Lib/_collections_abc.py
Этот модуль предоставляет abstract base classes, который можно использовать для проверки того, предоставляет ли класс определенный интерфейс; например, является ли он hashable или mapping.
Тест issubclass()
или isinstance()
для интерфейса работает одним из трех способов.
1) A newly written class can inherit directly from one of the abstract base classes. The class must supply the required abstract methods. The remaining mixin methods come from inheritance and can be overridden if desired. Other methods may be added as needed:
class C(Sequence): # Direct inheritance
def __init__(self): ... # Extra method not required by the ABC
def __getitem__(self, index): ... # Required abstract method
def __len__(self): ... # Required abstract method
def count(self, value): ... # Optionally override a mixin method
>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True
2) Existing classes and built-in classes can be registered as «virtual
subclasses» of the ABCs. Those classes should define the full API
including all of the abstract methods and all of the mixin methods.
This lets users rely on issubclass()
or isinstance()
tests
to determine whether the full interface is supported. The exception to
this rule is for methods that are automatically inferred from the rest
of the API:
class D: # No inheritance
def __init__(self): ... # Extra method not required by the ABC
def __getitem__(self, index): ... # Abstract method
def __len__(self): ... # Abstract method
def count(self, value): ... # Mixin method
def index(self, value): ... # Mixin method
Sequence.register(D) # Register instead of inherit
>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True
В этом примере классу D
не нужно определять __contains__
, __iter__
и __reversed__
, потому что логика in-operator, iteration и функция reversed()
автоматически возвращаются к использованию __getitem__
и __len__
.
3) Some simple interfaces are directly recognizable by the presence of
the required methods (unless those methods have been set to
None
):
class E:
def __iter__(self): ...
def __next__(self): ...
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
Сложные интерфейсы не поддерживают эту последнюю технику, потому что интерфейс - это нечто большее, чем просто наличие имен методов. Интерфейсы определяют семантику и отношения между методами, которые нельзя вывести только из наличия конкретных имен методов. Например, знание того, что класс предоставляет __getitem__
, __len__
и __iter__
, недостаточно для того, чтобы отличить Sequence
от Mapping
.
Added in version 3.9: Эти абстрактные классы теперь поддерживают []
. См. Общий тип псевдонима и PEP 585.
Коллекции Абстрактные базовые классы¶
Модуль коллекций предлагает следующие ABCs:
ABC |
Наследует от |
Абстрактные методы |
Методы миксинов |
---|---|---|---|
|
|||
|
|||
|
|||
|
|
||
|
|||
|
|
||
|
|||
|
|||
|
|||
|
|
||
|
Наследуются методы |
||
|
|
||
|
Наследуются методы |
||
|
|
||
|
Наследуются методы |
||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|
||
|
|||
|
|
||
|
|
||
|
Сноски
Абстрактные базовые классы коллекций - подробные описания¶
- class collections.abc.Container¶
ABC для классов, предоставляющих метод
__contains__()
.
- class collections.abc.Hashable¶
ABC для классов, предоставляющих метод
__hash__()
.
- class collections.abc.Callable¶
ABC для классов, предоставляющих метод
__call__()
.
- class collections.abc.Iterable¶
ABC для классов, предоставляющих метод
__iter__()
.Проверка
isinstance(obj, Iterable)
обнаруживает классы, зарегистрированные какIterable
или имеющие метод__iter__()
, но не обнаруживает классы, которые выполняют итерацию с помощью метода__getitem__()
. Единственный надежный способ определить, является ли объект iterable, - вызватьiter(obj)
.
- class collections.abc.Collection¶
ABC для классов контейнеров с итерируемыми размерами.
Added in version 3.6.
- class collections.abc.Iterator¶
ABC для классов, предоставляющих методы
__iter__()
и__next__()
. См. также определение iterator.
- class collections.abc.Reversible¶
ABC для классов iterable, которые также предоставляют метод
__reversed__()
.Added in version 3.6.
- class collections.abc.Generator¶
ABC для классов generator, реализующих протокол, определенный в PEP 342, который расширяет iterators с помощью методов
send()
,throw()
иclose()
.Added in version 3.5.
- class collections.abc.Sequence¶
- class collections.abc.MutableSequence¶
ABC для доступных только для чтения и изменяемых sequences.
Примечание по реализации: Некоторые из методов миксинов, такие как
__iter__()
,__reversed__()
иindex()
, выполняют повторные обращения к базовому методу__getitem__()
. Следовательно, если__getitem__()
реализован с постоянной скоростью доступа, методы миксинов будут иметь линейную производительность; однако если базовый метод линейный (как в случае со связным списком), миксины будут иметь квадратичную производительность и, скорее всего, потребуют переопределения.Изменено в версии 3.5: В метод index() добавлена поддержка аргументов stop и start.
- class collections.abc.Set¶
- class collections.abc.MutableSet¶
ABC для доступных только для чтения и изменяемых sets.
- class collections.abc.Mapping¶
- class collections.abc.MutableMapping¶
ABC для доступных только для чтения и изменяемых mappings.
- class collections.abc.MappingView¶
- class collections.abc.ItemsView¶
- class collections.abc.KeysView¶
- class collections.abc.ValuesView¶
Азбука отображения, элементов, ключей и значений views.
- class collections.abc.Awaitable¶
ABC для объектов awaitable, которые могут быть использованы в выражениях
await
. Пользовательские реализации должны предоставлять метод__await__()
.Объекты Coroutine и экземпляры
Coroutine
ABC - это все экземпляры этого ABC.Примечание
В CPython корутины на основе генератора (generators, украшенные
@types.coroutine
) являются дожидающимися, даже если у них нет метода__await__()
. Использованиеisinstance(gencoro, Awaitable)
для них вернетFalse
. Для их обнаружения используйтеinspect.isawaitable()
.Added in version 3.5.
- class collections.abc.Coroutine¶
ABC для классов, совместимых с coroutine. Они реализуют следующие методы, определенные в Объекты корутины:
send()
,throw()
иclose()
. Пользовательские реализации должны также реализовывать__await__()
. Все экземплярыCoroutine
также являются экземплярамиAwaitable
.Примечание
В CPython корутины на основе генератора (generators, украшенные
@types.coroutine
) являются дожидающимися, даже если у них нет метода__await__()
. Использованиеisinstance(gencoro, Coroutine)
для них вернетFalse
. Для их обнаружения используйтеinspect.isawaitable()
.Added in version 3.5.
- class collections.abc.AsyncIterable¶
ABC для классов, предоставляющих метод
__aiter__
. См. также определение asynchronous iterable.Added in version 3.5.
- class collections.abc.AsyncIterator¶
ABC для классов, предоставляющих методы
__aiter__
и__anext__
. См. также определение asynchronous iterator.Added in version 3.5.
- class collections.abc.AsyncGenerator¶
ABC для классов asynchronous generator, реализующих протокол, определенный в PEP 525 и PEP 492.
Added in version 3.6.
- class collections.abc.Buffer¶
ABC для классов, которые предоставляют метод
__buffer__()
, реализуя buffer protocol. См. PEP 688.Added in version 3.12.
Примеры и рецепты¶
ABC позволяют нам спрашивать классы или экземпляры, предоставляют ли они определенную функциональность, например:
size = None
if isinstance(myvar, collections.abc.Sized):
size = len(myvar)
Некоторые из ABC также полезны в качестве миксинов, которые облегчают разработку классов, поддерживающих контейнерные API. Например, чтобы написать класс, поддерживающий полный Set
API, необходимо предоставить только три базовых абстрактных метода: __contains__()
, __iter__()
и __len__()
. Остальные методы, такие как __and__()
и isdisjoint()
, предоставляет ABC:
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
в качестве миксина:
Поскольку некоторые операции с множествами создают новые множества, методам миксина по умолчанию необходим способ создания новых экземпляров из iterable. Предполагается, что конструктор класса имеет сигнатуру в виде
ClassName(iterable)
. Это предположение раскладывается на внутреннийclassmethod
, называемый_from_iterable()
, который вызываетcls(iterable)
для создания нового набора. Если миксинSet
используется в классе с другой сигнатурой конструктора, вам нужно переопределить_from_iterable()
с помощью метода класса или обычного метода, который может создавать новые экземпляры из аргумента iterable.Чтобы отменить сравнения (предположительно для скорости, поскольку семантика фиксирована), переопределите
__le__()
и__ge__()
, тогда остальные операции автоматически последуют за ними.Миксин
Set
предоставляет метод_hash()
для вычисления хэш-значения для набора; однако__hash__()
не определен, поскольку не все наборы являются hashable или неизменяемыми. Чтобы добавить хэшируемость множества с помощью миксинов, наследуйте отSet()
иHashable()
, а затем определите__hash__ = Set._hash
.
См.также
OrderedSet recipe для примера, построенного на
MutableSet
.