
``collections.abc`` --- Abstract Base Classes for Containers
************************************************************

New in version 3.3: Formerly, this module was part of the
``collections`` module.

**Source code:** Lib/collections/abc.py

======================================================================

This module provides *abstract base classes* 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 *ABCs*:

+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ABC                       | Inherits from         | Abstract Methods       | Mixin Methods                                        |
+===========================+=======================+========================+======================================================+
| ``Container``             |                       | ``__contains__``       |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Hashable``              |                       | ``__hash__``           |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Iterable``              |                       | ``__iter__``           |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Iterator``              | ``Iterable``          | ``__next__``           | ``__iter__``                                         |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Sized``                 |                       | ``__len__``            |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Callable``              |                       | ``__call__``           |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Sequence``              | ``Sized``,            | ``__getitem__``        | ``__contains__``, ``__iter__``, ``__reversed__``,    |
|                           | ``Iterable``,         |                        | ``index``, and ``count``                             |
|                           | ``Container``         |                        |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``MutableSequence``       | ``Sequence``          | ``__setitem__``,       | Inherited ``Sequence`` methods and ``append``,       |
|                           |                       | ``__delitem__``,       | ``reverse``, ``extend``, ``pop``, ``remove``,        |
|                           |                       | ``insert``             | ``clear``, and ``__iadd__``                          |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Set``                   | ``Sized``,            |                        | ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,      |
|                           | ``Iterable``,         |                        | ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,     |
|                           | ``Container``         |                        | ``__sub__``, ``__xor__``, and ``isdisjoint``         |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``MutableSet``            | ``Set``               | ``add``, ``discard``   | Inherited ``Set`` methods and ``clear``, ``pop``,    |
|                           |                       |                        | ``remove``, ``__ior__``, ``__iand__``, ``__ixor__``, |
|                           |                       |                        | and ``__isub__``                                     |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``Mapping``               | ``Sized``,            | ``__getitem__``        | ``__contains__``, ``keys``, ``items``, ``values``,   |
|                           | ``Iterable``,         |                        | ``get``, ``__eq__``, and ``__ne__``                  |
|                           | ``Container``         |                        |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``MutableMapping``        | ``Mapping``           | ``__setitem__``,       | Inherited ``Mapping`` methods and ``pop``,           |
|                           |                       | ``__delitem__``        | ``popitem``, ``clear``, ``update``, and              |
|                           |                       |                        | ``setdefault``                                       |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``MappingView``           | ``Sized``             |                        | ``__len__``                                          |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``ItemsView``             | ``MappingView``,      |                        | ``__contains__``, ``__iter__``                       |
|                           | ``Set``               |                        |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``KeysView``              | ``MappingView``,      |                        | ``__contains__``, ``__iter__``                       |
|                           | ``Set``               |                        |                                                      |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| ``ValuesView``            | ``MappingView``       |                        | ``__contains__``, ``__iter__``                       |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+

class class collections.abc.Container
class class collections.abc.Hashable
class class collections.abc.Sized
class class collections.abc.Callable

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

class class collections.abc.Iterable

   ABC for classes that provide the ``__iter__()`` method. See also
   the definition of *iterable*.

class class collections.abc.Iterator

   ABC for classes that provide the ``__iter__()`` and ``next()``
   methods. See also the definition of *iterator*.

class class collections.abc.Sequence
class class collections.abc.MutableSequence

   ABCs for read-only and mutable *sequences*.

class class collections.abc.Set
class class collections.abc.MutableSet

   ABCs for read-only and mutable sets.

class class collections.abc.Mapping
class class collections.abc.MutableMapping

   ABCs for read-only and mutable *mappings*.

class class collections.abc.MappingView
class class collections.abc.ItemsView
class class collections.abc.KeysView
class class collections.abc.ValuesView

   ABCs for mapping, items, keys, and values *views*.

These ABCs allow us to ask classes or instances if they provide
particular functionality, for example:

   size = None
   if isinstance(myvar, collections.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 ``Set`` API, it only necessary to supply the
three underlying abstract methods: ``__contains__()``, ``__iter__()``,
and ``__len__()``. The ABC supplies the remaining methods such as
``__and__()`` and ``isdisjoint()``

   class ListBasedSet(collections.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 ``Set`` and ``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 ``_from_iterable()`` which calls
   ``cls(iterable)`` to produce a new set. If the ``Set`` mixin is
   being used in a class with a different constructor signature, you
   will need to override ``_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 ``__le__()`` and then the other operations
   will automatically follow suit.

3. The ``Set`` mixin provides a ``_hash()`` method to compute a hash
   value for the set; however, ``__hash__()`` is not defined because
   not all sets are hashable or immutable.  To add set hashabilty
   using mixins, inherit from both ``Set()`` and ``Hashable()``, then
   define ``__hash__ = Set._hash``.

See also:

   * OrderedSet recipe for an example built on ``MutableSet``.

   * For more about ABCs, see the ``abc`` module and **PEP 3119**.
