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 23 This module provides :term:`abstract base classes <abstract base class>` that 24 can be used to test whether a class provides a particular interface; for 25 example, whether it is hashable or whether it is a mapping. 26 27 28 .. _collections-abstract-base-classes: 29 30 Collections Abstract Base Classes 31 --------------------------------- 32 33 The collections module offers the following :term:`ABCs <abstract base class>`: 34 35 .. tabularcolumns:: |l|L|L|L| 36 37 ========================== ====================== ======================= ==================================================== 38 ABC 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:`Awaitable` ``__await__`` 92 :class:`Coroutine` :class:`Awaitable` ``send``, ``throw`` ``close`` 93 :class:`AsyncIterable` ``__aiter__`` 94 :class:`AsyncIterator` :class:`AsyncIterable` ``__anext__`` ``__aiter__`` 95 :class:`AsyncGenerator` :class:`AsyncIterator` ``asend``, ``athrow`` ``aclose``, ``__aiter__``, ``__anext__`` 96 ========================== ====================== ======================= ==================================================== 97 98 99 .. class:: Container 100 Hashable 101 Sized 102 Callable 103 104 ABCs for classes that provide respectively the methods :meth:`__contains__`, 105 :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`. 106 107 .. class:: Iterable 108 109 ABC for classes that provide the :meth:`__iter__` method. 110 See also the definition of :term:`iterable`. 111 112 .. class:: Collection 113 114 ABC for sized iterable container classes. 115 116 .. versionadded:: 3.6 117 118 .. class:: Iterator 119 120 ABC for classes that provide the :meth:`~iterator.__iter__` and 121 :meth:`~iterator.__next__` methods. See also the definition of 122 :term:`iterator`. 123 124 .. class:: Reversible 125 126 ABC for iterable classes that also provide the :meth:`__reversed__` 127 method. 128 129 .. versionadded:: 3.6 130 131 .. class:: Generator 132 133 ABC for generator classes that implement the protocol defined in 134 :pep:`342` that extends iterators with the :meth:`~generator.send`, 135 :meth:`~generator.throw` and :meth:`~generator.close` methods. 136 See also the definition of :term:`generator`. 137 138 .. versionadded:: 3.5 139 140 .. class:: Sequence 141 MutableSequence 142 ByteString 143 144 ABCs for read-only and mutable :term:`sequences <sequence>`. 145 146 Implementation note: Some of the mixin methods, such as 147 :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make 148 repeated calls to the underlying :meth:`__getitem__` method. 149 Consequently, if :meth:`__getitem__` is implemented with constant 150 access speed, the mixin methods will have linear performance; 151 however, if the underlying method is linear (as it would be with a 152 linked list), the mixins will have quadratic performance and will 153 likely need to be overridden. 154 155 .. versionchanged:: 3.5 156 The index() method added support for *stop* and *start* 157 arguments. 158 159 .. class:: Set 160 MutableSet 161 162 ABCs for read-only and mutable sets. 163 164 .. class:: Mapping 165 MutableMapping 166 167 ABCs for read-only and mutable :term:`mappings <mapping>`. 168 169 .. class:: MappingView 170 ItemsView 171 KeysView 172 ValuesView 173 174 ABCs for mapping, items, keys, and values :term:`views <dictionary view>`. 175 176 .. class:: Awaitable 177 178 ABC for :term:`awaitable` objects, which can be used in :keyword:`await` 179 expressions. Custom implementations must provide the :meth:`__await__` 180 method. 181 182 :term:`Coroutine` objects and instances of the 183 :class:`~collections.abc.Coroutine` ABC are all instances of this ABC. 184 185 .. note:: 186 In CPython, generator-based coroutines (generators decorated with 187 :func:`types.coroutine` or :func:`asyncio.coroutine`) are 188 *awaitables*, even though they do not have an :meth:`__await__` method. 189 Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``. 190 Use :func:`inspect.isawaitable` to detect them. 191 192 .. versionadded:: 3.5 193 194 .. class:: Coroutine 195 196 ABC for coroutine compatible classes. These implement the 197 following methods, defined in :ref:`coroutine-objects`: 198 :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and 199 :meth:`~coroutine.close`. Custom implementations must also implement 200 :meth:`__await__`. All :class:`Coroutine` instances are also instances of 201 :class:`Awaitable`. See also the definition of :term:`coroutine`. 202 203 .. note:: 204 In CPython, generator-based coroutines (generators decorated with 205 :func:`types.coroutine` or :func:`asyncio.coroutine`) are 206 *awaitables*, even though they do not have an :meth:`__await__` method. 207 Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. 208 Use :func:`inspect.isawaitable` to detect them. 209 210 .. versionadded:: 3.5 211 212 .. class:: AsyncIterable 213 214 ABC for classes that provide ``__aiter__`` method. See also the 215 definition of :term:`asynchronous iterable`. 216 217 .. versionadded:: 3.5 218 219 .. class:: AsyncIterator 220 221 ABC for classes that provide ``__aiter__`` and ``__anext__`` 222 methods. See also the definition of :term:`asynchronous iterator`. 223 224 .. versionadded:: 3.5 225 226 .. class:: AsyncGenerator 227 228 ABC for asynchronous generator classes that implement the protocol 229 defined in :pep:`525` and :pep:`492`. 230 231 .. versionadded:: 3.6 232 233 234 These ABCs allow us to ask classes or instances if they provide 235 particular functionality, for example:: 236 237 size = None 238 if isinstance(myvar, collections.abc.Sized): 239 size = len(myvar) 240 241 Several of the ABCs are also useful as mixins that make it easier to develop 242 classes supporting container APIs. For example, to write a class supporting 243 the full :class:`Set` API, it is only necessary to supply the three underlying 244 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. 245 The ABC supplies the remaining methods such as :meth:`__and__` and 246 :meth:`isdisjoint`:: 247 248 class ListBasedSet(collections.abc.Set): 249 ''' Alternate set implementation favoring space over speed 250 and not requiring the set elements to be hashable. ''' 251 def __init__(self, iterable): 252 self.elements = lst = [] 253 for value in iterable: 254 if value not in lst: 255 lst.append(value) 256 257 def __iter__(self): 258 return iter(self.elements) 259 260 def __contains__(self, value): 261 return value in self.elements 262 263 def __len__(self): 264 return len(self.elements) 265 266 s1 = ListBasedSet('abcdef') 267 s2 = ListBasedSet('defghi') 268 overlap = s1 & s2 # The __and__() method is supported automatically 269 270 Notes on using :class:`Set` and :class:`MutableSet` as a mixin: 271 272 (1) 273 Since some set operations create new sets, the default mixin methods need 274 a way to create new instances from an iterable. The class constructor is 275 assumed to have a signature in the form ``ClassName(iterable)``. 276 That assumption is factored-out to an internal classmethod called 277 :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set. 278 If the :class:`Set` mixin is being used in a class with a different 279 constructor signature, you will need to override :meth:`_from_iterable` 280 with a classmethod that can construct new instances from 281 an iterable argument. 282 283 (2) 284 To override the comparisons (presumably for speed, as the 285 semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`, 286 then the other operations will automatically follow suit. 287 288 (3) 289 The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value 290 for the set; however, :meth:`__hash__` is not defined because not all sets 291 are hashable or immutable. To add set hashability using mixins, 292 inherit from both :meth:`Set` and :meth:`Hashable`, then define 293 ``__hash__ = Set._hash``. 294 295 .. seealso:: 296 297 * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an 298 example built on :class:`MutableSet`. 299 300 * For more about ABCs, see the :mod:`abc` module and :pep:`3119`. 301
