
"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                                        |
+===========================+=======================+========================+======================================================+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "Iterator"                | "Iterable"            | "__next__"             | "__iter__"                                           |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "Sequence"                | "Sized", "Iterable",  | "__getitem__",         | "__contains__", "__iter__", "__reversed__", "index", |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "MutableSequence"         | "Sequence"            | "__getitem__",         | Inherited "Sequence" methods and "append",           |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "Set"                     | "Sized", "Iterable",  | "__contains__",        | "__le__", "__lt__", "__eq__", "__ne__", "__gt__",    |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "MutableSet"              | "Set"                 | "__contains__",        | Inherited "Set" methods and "clear", "pop",          |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "Mapping"                 | "Sized", "Iterable",  | "__getitem__",         | "__contains__", "keys", "items", "values", "get",    |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
| "MutableMapping"          | "Mapping"             | "__getitem__",         | Inherited "Mapping" methods and "pop", "popitem",    |
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+
+---------------------------+-----------------------+------------------------+------------------------------------------------------+

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