1:mod:`collections.abc` --- Abstract Base Classes for Containers
2===============================================================
3
4.. module:: collections.abc
5   :synopsis: Abstract base classes for containers
6
7.. moduleauthor:: Raymond Hettinger <python at rcn.com>
8.. sectionauthor:: Raymond Hettinger <python at rcn.com>
9
10.. versionadded:: 3.3
11   Formerly, this module was part of the :mod:`collections` module.
12
13**Source code:** :source:`Lib/_collections_abc.py`
14
15.. testsetup:: *
16
17   from collections import *
18   import itertools
19   __name__ = '<doctest>'
20
21--------------
22
23This module provides :term:`abstract base classes <abstract base class>` that
24can be used to test whether a class provides a particular interface; for
25example, whether it is hashable or whether it is a mapping.
26
27
28.. _collections-abstract-base-classes:
29
30Collections Abstract Base Classes
31---------------------------------
32
33The collections module offers the following :term:`ABCs <abstract base class>`:
34
35.. tabularcolumns:: |l|L|L|L|
36
37========================== ====================== ======================= ====================================================
38ABC                        Inherits from          Abstract Methods        Mixin Methods
39========================== ====================== ======================= ====================================================
40:class:`Container`                                ``__contains__``
41:class:`Hashable`                                 ``__hash__``
42:class:`Iterable`                                 ``__iter__``
43:class:`Iterator`          :class:`Iterable`      ``__next__``            ``__iter__``
44:class:`Reversible`        :class:`Iterable`      ``__reversed__``
45:class:`Generator`         :class:`Iterator`      ``send``, ``throw``     ``close``, ``__iter__``, ``__next__``
46:class:`Sized`                                    ``__len__``
47:class:`Callable`                                 ``__call__``
48:class:`Collection`        :class:`Sized`,        ``__contains__``,
49                           :class:`Iterable`,     ``__iter__``,
50                           :class:`Container`     ``__len__``
51
52:class:`Sequence`          :class:`Reversible`,   ``__getitem__``,        ``__contains__``, ``__iter__``, ``__reversed__``,
53                           :class:`Collection`    ``__len__``             ``index``, and ``count``
54
55:class:`MutableSequence`   :class:`Sequence`      ``__getitem__``,        Inherited :class:`Sequence` methods and
56                                                  ``__setitem__``,        ``append``, ``reverse``, ``extend``, ``pop``,
57                                                  ``__delitem__``,        ``remove``, and ``__iadd__``
58                                                  ``__len__``,
59                                                  ``insert``
60
61:class:`ByteString`        :class:`Sequence`      ``__getitem__``,        Inherited :class:`Sequence` methods
62                                                  ``__len__``
63
64:class:`Set`               :class:`Collection`    ``__contains__``,       ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
65                                                  ``__iter__``,           ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
66                                                  ``__len__``             ``__sub__``, ``__xor__``, and ``isdisjoint``
67
68:class:`MutableSet`        :class:`Set`           ``__contains__``,       Inherited :class:`Set` methods and
69                                                  ``__iter__``,           ``clear``, ``pop``, ``remove``, ``__ior__``,
70                                                  ``__len__``,            ``__iand__``, ``__ixor__``, and ``__isub__``
71                                                  ``add``,
72                                                  ``discard``
73
74:class:`Mapping`           :class:`Collection`    ``__getitem__``,        ``__contains__``, ``keys``, ``items``, ``values``,
75                                                  ``__iter__``,           ``get``, ``__eq__``, and ``__ne__``
76                                                  ``__len__``
77
78:class:`MutableMapping`    :class:`Mapping`       ``__getitem__``,        Inherited :class:`Mapping` methods and
79                                                  ``__setitem__``,        ``pop``, ``popitem``, ``clear``, ``update``,
80                                                  ``__delitem__``,        and ``setdefault``
81                                                  ``__iter__``,
82                                                  ``__len__``
83
84
85:class:`MappingView`       :class:`Sized`                                 ``__len__``
86:class:`ItemsView`         :class:`MappingView`,                          ``__contains__``,
87                           :class:`Set`                                   ``__iter__``
88:class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
89                           :class:`Set`                                   ``__iter__``
90:class:`ValuesView`        :class:`MappingView`,                          ``__contains__``, ``__iter__``
91                           :class:`Collection`
92:class:`Awaitable`                                ``__await__``
93:class:`Coroutine`         :class:`Awaitable`     ``send``, ``throw``     ``close``
94:class:`AsyncIterable`                            ``__aiter__``
95:class:`AsyncIterator`     :class:`AsyncIterable` ``__anext__``           ``__aiter__``
96:class:`AsyncGenerator`    :class:`AsyncIterator` ``asend``, ``athrow``   ``aclose``, ``__aiter__``, ``__anext__``
97========================== ====================== ======================= ====================================================
98
99
100.. class:: Container
101           Hashable
102           Sized
103           Callable
104
105   ABCs for classes that provide respectively the methods :meth:`__contains__`,
106   :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
107
108.. class:: Iterable
109
110   ABC for classes that provide the :meth:`__iter__` method.
111
112   Checking ``isinstance(obj, Iterable)`` detects classes that are registered
113   as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
114   not detect classes that iterate with the :meth:`__getitem__` method.
115   The only reliable way to determine whether an object is :term:`iterable`
116   is to call ``iter(obj)``.
117
118.. class:: Collection
119
120   ABC for sized iterable container classes.
121
122   .. versionadded:: 3.6
123
124.. class:: Iterator
125
126   ABC for classes that provide the :meth:`~iterator.__iter__` and
127   :meth:`~iterator.__next__` methods.  See also the definition of
128   :term:`iterator`.
129
130.. class:: Reversible
131
132   ABC for iterable classes that also provide the :meth:`__reversed__`
133   method.
134
135   .. versionadded:: 3.6
136
137.. class:: Generator
138
139   ABC for generator classes that implement the protocol defined in
140   :pep:`342` that extends iterators with the :meth:`~generator.send`,
141   :meth:`~generator.throw` and :meth:`~generator.close` methods.
142   See also the definition of :term:`generator`.
143
144   .. versionadded:: 3.5
145
146.. class:: Sequence
147           MutableSequence
148           ByteString
149
150   ABCs for read-only and mutable :term:`sequences <sequence>`.
151
152   Implementation note: Some of the mixin methods, such as
153   :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make
154   repeated calls to the underlying :meth:`__getitem__` method.
155   Consequently, if :meth:`__getitem__` is implemented with constant
156   access speed, the mixin methods will have linear performance;
157   however, if the underlying method is linear (as it would be with a
158   linked list), the mixins will have quadratic performance and will
159   likely need to be overridden.
160
161   .. versionchanged:: 3.5
162      The index() method added support for *stop* and *start*
163      arguments.
164
165.. class:: Set
166           MutableSet
167
168   ABCs for read-only and mutable sets.
169
170.. class:: Mapping
171           MutableMapping
172
173   ABCs for read-only and mutable :term:`mappings <mapping>`.
174
175.. class:: MappingView
176           ItemsView
177           KeysView
178           ValuesView
179
180   ABCs for mapping, items, keys, and values :term:`views <dictionary view>`.
181
182.. class:: Awaitable
183
184   ABC for :term:`awaitable` objects, which can be used in :keyword:`await`
185   expressions.  Custom implementations must provide the :meth:`__await__`
186   method.
187
188   :term:`Coroutine` objects and instances of the
189   :class:`~collections.abc.Coroutine` ABC are all instances of this ABC.
190
191   .. note::
192      In CPython, generator-based coroutines (generators decorated with
193      :func:`types.coroutine` or :func:`asyncio.coroutine`) are
194      *awaitables*, even though they do not have an :meth:`__await__` method.
195      Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
196      Use :func:`inspect.isawaitable` to detect them.
197
198   .. versionadded:: 3.5
199
200.. class:: Coroutine
201
202   ABC for coroutine compatible classes.  These implement the
203   following methods, defined in :ref:`coroutine-objects`:
204   :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and
205   :meth:`~coroutine.close`.  Custom implementations must also implement
206   :meth:`__await__`.  All :class:`Coroutine` instances are also instances of
207   :class:`Awaitable`.  See also the definition of :term:`coroutine`.
208
209   .. note::
210      In CPython, generator-based coroutines (generators decorated with
211      :func:`types.coroutine` or :func:`asyncio.coroutine`) are
212      *awaitables*, even though they do not have an :meth:`__await__` method.
213      Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
214      Use :func:`inspect.isawaitable` to detect them.
215
216   .. versionadded:: 3.5
217
218.. class:: AsyncIterable
219
220   ABC for classes that provide ``__aiter__`` method.  See also the
221   definition of :term:`asynchronous iterable`.
222
223   .. versionadded:: 3.5
224
225.. class:: AsyncIterator
226
227   ABC for classes that provide ``__aiter__`` and ``__anext__``
228   methods.  See also the definition of :term:`asynchronous iterator`.
229
230   .. versionadded:: 3.5
231
232.. class:: AsyncGenerator
233
234   ABC for asynchronous generator classes that implement the protocol
235   defined in :pep:`525` and :pep:`492`.
236
237   .. versionadded:: 3.6
238
239
240These ABCs allow us to ask classes or instances if they provide
241particular functionality, for example::
242
243    size = None
244    if isinstance(myvar, collections.abc.Sized):
245        size = len(myvar)
246
247Several of the ABCs are also useful as mixins that make it easier to develop
248classes supporting container APIs.  For example, to write a class supporting
249the full :class:`Set` API, it is only necessary to supply the three underlying
250abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
251The ABC supplies the remaining methods such as :meth:`__and__` and
252:meth:`isdisjoint`::
253
254    class ListBasedSet(collections.abc.Set):
255        ''' Alternate set implementation favoring space over speed
256            and not requiring the set elements to be hashable. '''
257        def __init__(self, iterable):
258            self.elements = lst = []
259            for value in iterable:
260                if value not in lst:
261                    lst.append(value)
262
263        def __iter__(self):
264            return iter(self.elements)
265
266        def __contains__(self, value):
267            return value in self.elements
268
269        def __len__(self):
270            return len(self.elements)
271
272    s1 = ListBasedSet('abcdef')
273    s2 = ListBasedSet('defghi')
274    overlap = s1 & s2            # The __and__() method is supported automatically
275
276Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
277
278(1)
279   Since some set operations create new sets, the default mixin methods need
280   a way to create new instances from an iterable. The class constructor is
281   assumed to have a signature in the form ``ClassName(iterable)``.
282   That assumption is factored-out to an internal classmethod called
283   :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
284   If the :class:`Set` mixin is being used in a class with a different
285   constructor signature, you will need to override :meth:`_from_iterable`
286   with a classmethod that can construct new instances from
287   an iterable argument.
288
289(2)
290   To override the comparisons (presumably for speed, as the
291   semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`,
292   then the other operations will automatically follow suit.
293
294(3)
295   The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
296   for the set; however, :meth:`__hash__` is not defined because not all sets
297   are hashable or immutable.  To add set hashability using mixins,
298   inherit from both :meth:`Set` and :meth:`Hashable`, then define
299   ``__hash__ = Set._hash``.
300
301.. seealso::
302
303   * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an
304     example built on :class:`MutableSet`.
305
306   * For more about ABCs, see the :mod:`abc` module and :pep:`3119`.
307