D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
local
/
src
/
Python-3.9.9
/
Doc
/
library
/
Filename :
collections.abc.rst
back
Copy
:mod:`collections.abc` --- Abstract Base Classes for Containers =============================================================== .. module:: collections.abc :synopsis: Abstract base classes for containers .. moduleauthor:: Raymond Hettinger <python at rcn.com> .. sectionauthor:: Raymond Hettinger <python at rcn.com> .. versionadded:: 3.3 Formerly, this module was part of the :mod:`collections` module. **Source code:** :source:`Lib/_collections_abc.py` .. testsetup:: * from collections import * import itertools __name__ = '<doctest>' -------------- This module provides :term:`abstract base classes <abstract base class>` that can be used to test whether a class provides a particular interface; for example, whether it is hashable or whether it is a mapping. .. versionadded:: 3.9 These abstract classes now support ``[]``. See :ref:`types-genericalias` and :pep:`585`. .. _collections-abstract-base-classes: Collections Abstract Base Classes --------------------------------- The collections module offers the following :term:`ABCs <abstract base class>`: .. tabularcolumns:: |l|L|L|L| ========================== ====================== ======================= ==================================================== ABC Inherits from Abstract Methods Mixin Methods ========================== ====================== ======================= ==================================================== :class:`Container` ``__contains__`` :class:`Hashable` ``__hash__`` :class:`Iterable` ``__iter__`` :class:`Iterator` :class:`Iterable` ``__next__`` ``__iter__`` :class:`Reversible` :class:`Iterable` ``__reversed__`` :class:`Generator` :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__`` :class:`Sized` ``__len__`` :class:`Callable` ``__call__`` :class:`Collection` :class:`Sized`, ``__contains__``, :class:`Iterable`, ``__iter__``, :class:`Container` ``__len__`` :class:`Sequence` :class:`Reversible`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``, :class:`Collection` ``__len__`` ``index``, and ``count`` :class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and ``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``, ``__delitem__``, ``remove``, and ``__iadd__`` ``__len__``, ``insert`` :class:`ByteString` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods ``__len__`` :class:`Set` :class:`Collection` ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, ``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``, ``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint`` :class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and ``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``, ``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__`` ``add``, ``discard`` :class:`Mapping` :class:`Collection` ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``, ``__iter__``, ``get``, ``__eq__``, and ``__ne__`` ``__len__`` :class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and ``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``, ``__delitem__``, and ``setdefault`` ``__iter__``, ``__len__`` :class:`MappingView` :class:`Sized` ``__len__`` :class:`ItemsView` :class:`MappingView`, ``__contains__``, :class:`Set` ``__iter__`` :class:`KeysView` :class:`MappingView`, ``__contains__``, :class:`Set` ``__iter__`` :class:`ValuesView` :class:`MappingView`, ``__contains__``, ``__iter__`` :class:`Collection` :class:`Awaitable` ``__await__`` :class:`Coroutine` :class:`Awaitable` ``send``, ``throw`` ``close`` :class:`AsyncIterable` ``__aiter__`` :class:`AsyncIterator` :class:`AsyncIterable` ``__anext__`` ``__aiter__`` :class:`AsyncGenerator` :class:`AsyncIterator` ``asend``, ``athrow`` ``aclose``, ``__aiter__``, ``__anext__`` ========================== ====================== ======================= ==================================================== .. class:: Container ABC for classes that provide the :meth:`__contains__` method. .. class:: Hashable ABC for classes that provide the :meth:`__hash__` method. .. class:: Sized ABC for classes that provide the :meth:`__len__` method. .. class:: Callable ABC for classes that provide the :meth:`__call__` method. .. class:: Iterable ABC for classes that provide the :meth:`__iter__` method. Checking ``isinstance(obj, Iterable)`` detects classes that are registered as :class:`Iterable` or that have an :meth:`__iter__` method, but it does not detect classes that iterate with the :meth:`__getitem__` method. The only reliable way to determine whether an object is :term:`iterable` is to call ``iter(obj)``. .. class:: Collection ABC for sized iterable container classes. .. versionadded:: 3.6 .. class:: Iterator ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods. See also the definition of :term:`iterator`. .. class:: Reversible ABC for iterable classes that also provide the :meth:`__reversed__` method. .. versionadded:: 3.6 .. class:: Generator ABC for generator classes that implement the protocol defined in :pep:`342` that extends iterators with the :meth:`~generator.send`, :meth:`~generator.throw` and :meth:`~generator.close` methods. See also the definition of :term:`generator`. .. versionadded:: 3.5 .. class:: Sequence MutableSequence ByteString ABCs for read-only and mutable :term:`sequences <sequence>`. Implementation note: Some of the mixin methods, such as :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make repeated calls to the underlying :meth:`__getitem__` method. Consequently, if :meth:`__getitem__` is implemented with constant access speed, the mixin methods will have linear performance; however, if the underlying method is linear (as it would be with a linked list), the mixins will have quadratic performance and will likely need to be overridden. .. versionchanged:: 3.5 The index() method added support for *stop* and *start* arguments. .. class:: Set MutableSet ABCs for read-only and mutable sets. .. class:: Mapping MutableMapping ABCs for read-only and mutable :term:`mappings <mapping>`. .. class:: MappingView ItemsView KeysView ValuesView ABCs for mapping, items, keys, and values :term:`views <dictionary view>`. .. class:: Awaitable ABC for :term:`awaitable` objects, which can be used in :keyword:`await` expressions. Custom implementations must provide the :meth:`__await__` method. :term:`Coroutine <coroutine>` objects and instances of the :class:`~collections.abc.Coroutine` ABC are all instances of this ABC. .. note:: In CPython, generator-based coroutines (generators decorated with :func:`types.coroutine` or :func:`asyncio.coroutine`) are *awaitables*, even though they do not have an :meth:`__await__` method. Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``. Use :func:`inspect.isawaitable` to detect them. .. versionadded:: 3.5 .. class:: Coroutine ABC for coroutine compatible classes. These implement the following methods, defined in :ref:`coroutine-objects`: :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and :meth:`~coroutine.close`. Custom implementations must also implement :meth:`__await__`. All :class:`Coroutine` instances are also instances of :class:`Awaitable`. See also the definition of :term:`coroutine`. .. note:: In CPython, generator-based coroutines (generators decorated with :func:`types.coroutine` or :func:`asyncio.coroutine`) are *awaitables*, even though they do not have an :meth:`__await__` method. Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. Use :func:`inspect.isawaitable` to detect them. .. versionadded:: 3.5 .. class:: AsyncIterable ABC for classes that provide ``__aiter__`` method. See also the definition of :term:`asynchronous iterable`. .. versionadded:: 3.5 .. class:: AsyncIterator ABC for classes that provide ``__aiter__`` and ``__anext__`` methods. See also the definition of :term:`asynchronous iterator`. .. versionadded:: 3.5 .. class:: AsyncGenerator ABC for asynchronous generator classes that implement the protocol defined in :pep:`525` and :pep:`492`. .. versionadded:: 3.6 These ABCs allow us to ask classes or instances if they provide particular functionality, for example:: size = None if isinstance(myvar, collections.abc.Sized): size = len(myvar) Several of the ABCs are also useful as mixins that make it easier to develop classes supporting container APIs. For example, to write a class supporting the full :class:`Set` API, it is only necessary to supply the three underlying abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. The ABC supplies the remaining methods such as :meth:`__and__` and :meth:`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 Notes on using :class:`Set` and :class:`MutableSet` as a mixin: (1) Since some set operations create new sets, the default mixin methods need a way to create new instances from an iterable. The class constructor is assumed to have a signature in the form ``ClassName(iterable)``. That assumption is factored-out to an internal classmethod called :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set. If the :class:`Set` mixin is being used in a class with a different constructor signature, you will need to override :meth:`_from_iterable` with a classmethod or regular method that can construct new instances from an iterable argument. (2) To override the comparisons (presumably for speed, as the semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`, then the other operations will automatically follow suit. (3) The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value for the set; however, :meth:`__hash__` is not defined because not all sets are hashable or immutable. To add set hashability using mixins, inherit from both :meth:`Set` and :meth:`Hashable`, then define ``__hash__ = Set._hash``. .. seealso:: * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an example built on :class:`MutableSet`. * For more about ABCs, see the :mod:`abc` module and :pep:`3119`.