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

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

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

class collections.abc.Iterable

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

class collections.abc.Iterator

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

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

   ABCs for read-only and mutable *sequences*.

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

   ABCs for read-only and mutable sets.

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

   ABCs for read-only and mutable *mappings*.

class collections.abc.MappingView
class collections.abc.ItemsView
class collections.abc.KeysView
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.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 "Set" API, it is 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.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 "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 "__ge__()", 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 hashability 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**.
