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

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`, :class:`Iterable`, :class:`Container`	__contains__, __iter__, __len__
:class:`Sequence`	:class:`Reversible`, :class:`Collection`	__getitem__, __len__	__contains__, __iter__, __reversed__, index, and count
:class:`MutableSequence`	:class:`Sequence`	__getitem__, __setitem__, __delitem__, __len__, insert	Inherited :class:`Sequence` methods and append, reverse, extend, pop, remove, and __iadd__
:class:`ByteString`	:class:`Sequence`	__getitem__, __len__	Inherited :class:`Sequence` methods
:class:`Set`	:class:`Collection`	__contains__, __iter__, __len__	__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, and isdisjoint
:class:`MutableSet`	:class:`Set`	__contains__, __iter__, __len__, add, discard	Inherited :class:`Set` methods and clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__
:class:`Mapping`	:class:`Collection`	__getitem__, __iter__, __len__	__contains__, keys, items, values, get, __eq__, and __ne__
:class:`MutableMapping`	:class:`Mapping`	__getitem__, __setitem__, __delitem__, __iter__, __len__	Inherited :class:`Mapping` methods and pop, popitem, clear, update, and setdefault
:class:`MappingView`	:class:`Sized`		__len__
:class:`ItemsView`	:class:`MappingView`, :class:`Set`		__contains__, __iter__
:class:`KeysView`	:class:`MappingView`, :class:`Set`		__contains__, __iter__
:class:`ValuesView`	:class:`MappingView`, :class:`Collection`		__contains__, __iter__
: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__

ABCs for classes that provide respectively the methods :meth:`__contains__`, :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.

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

ABC for sized iterable container classes.

.. versionadded:: 3.6

ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods. See also the definition of :term:`iterator`.

ABC for iterable classes that also provide the :meth:`__reversed__` method.

.. versionadded:: 3.6

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

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.

ABCs for read-only and mutable sets.

ABCs for read-only and mutable :term:`mappings <mapping>`.

ABCs for mapping, items, keys, and values :term:`views <dictionary view>`.

ABC for :term:`awaitable` objects, which can be used in :keyword:`await` expressions. Custom implementations must provide the :meth:`__await__` method.

:term:`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

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

ABC for classes that provide __aiter__ method. See also the definition of :term:`asynchronous iterable`.

.. versionadded:: 3.5

ABC for classes that provide __aiter__ and __anext__ methods. See also the definition of :term:`asynchronous iterator`.

.. versionadded:: 3.5

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 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`.