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.abc 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 27An :func:`issubclass` or :func:`isinstance` test for an interface works in one 28of three ways. 29 301) A newly written class can inherit directly from one of the 31abstract base classes. The class must supply the required abstract 32methods. The remaining mixin methods come from inheritance and can be 33overridden if desired. Other methods may be added as needed: 34 35.. testcode:: 36 37 class C(Sequence): # Direct inheritance 38 def __init__(self): ... # Extra method not required by the ABC 39 def __getitem__(self, index): ... # Required abstract method 40 def __len__(self): ... # Required abstract method 41 def count(self, value): ... # Optionally override a mixin method 42 43.. doctest:: 44 45 >>> issubclass(C, Sequence) 46 True 47 >>> isinstance(C(), Sequence) 48 True 49 502) Existing classes and built-in classes can be registered as "virtual 51subclasses" of the ABCs. Those classes should define the full API 52including all of the abstract methods and all of the mixin methods. 53This lets users rely on :func:`issubclass` or :func:`isinstance` tests 54to determine whether the full interface is supported. The exception to 55this rule is for methods that are automatically inferred from the rest 56of the API: 57 58.. testcode:: 59 60 class D: # No inheritance 61 def __init__(self): ... # Extra method not required by the ABC 62 def __getitem__(self, index): ... # Abstract method 63 def __len__(self): ... # Abstract method 64 def count(self, value): ... # Mixin method 65 def index(self, value): ... # Mixin method 66 67 Sequence.register(D) # Register instead of inherit 68 69.. doctest:: 70 71 >>> issubclass(D, Sequence) 72 True 73 >>> isinstance(D(), Sequence) 74 True 75 76In this example, class :class:`D` does not need to define 77``__contains__``, ``__iter__``, and ``__reversed__`` because the 78:ref:`in-operator <comparisons>`, the :term:`iteration <iterable>` 79logic, and the :func:`reversed` function automatically fall back to 80using ``__getitem__`` and ``__len__``. 81 823) Some simple interfaces are directly recognizable by the presence of 83the required methods (unless those methods have been set to 84:const:`None`): 85 86.. testcode:: 87 88 class E: 89 def __iter__(self): ... 90 def __next__(next): ... 91 92.. doctest:: 93 94 >>> issubclass(E, Iterable) 95 True 96 >>> isinstance(E(), Iterable) 97 True 98 99Complex interfaces do not support this last technique because an 100interface is more than just the presence of method names. Interfaces 101specify semantics and relationships between methods that cannot be 102inferred solely from the presence of specific method names. For 103example, knowing that a class supplies ``__getitem__``, ``__len__``, and 104``__iter__`` is insufficient for distinguishing a :class:`Sequence` from 105a :class:`Mapping`. 106 107.. versionadded:: 3.9 108 These abstract classes now support ``[]``. See :ref:`types-genericalias` 109 and :pep:`585`. 110 111.. _collections-abstract-base-classes: 112 113Collections Abstract Base Classes 114--------------------------------- 115 116The collections module offers the following :term:`ABCs <abstract base class>`: 117 118.. tabularcolumns:: |l|L|L|L| 119 120============================== ====================== ======================= ==================================================== 121ABC Inherits from Abstract Methods Mixin Methods 122============================== ====================== ======================= ==================================================== 123:class:`Container` [1]_ ``__contains__`` 124:class:`Hashable` [1]_ ``__hash__`` 125:class:`Iterable` [1]_ [2]_ ``__iter__`` 126:class:`Iterator` [1]_ :class:`Iterable` ``__next__`` ``__iter__`` 127:class:`Reversible` [1]_ :class:`Iterable` ``__reversed__`` 128:class:`Generator` [1]_ :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__`` 129:class:`Sized` [1]_ ``__len__`` 130:class:`Callable` [1]_ ``__call__`` 131:class:`Collection` [1]_ :class:`Sized`, ``__contains__``, 132 :class:`Iterable`, ``__iter__``, 133 :class:`Container` ``__len__`` 134 135:class:`Sequence` :class:`Reversible`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``, 136 :class:`Collection` ``__len__`` ``index``, and ``count`` 137 138:class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and 139 ``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``, 140 ``__delitem__``, ``remove``, and ``__iadd__`` 141 ``__len__``, 142 ``insert`` 143 144:class:`ByteString` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods 145 ``__len__`` 146 147:class:`Set` :class:`Collection` ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, 148 ``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``, 149 ``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint`` 150 151:class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and 152 ``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``, 153 ``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__`` 154 ``add``, 155 ``discard`` 156 157:class:`Mapping` :class:`Collection` ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``, 158 ``__iter__``, ``get``, ``__eq__``, and ``__ne__`` 159 ``__len__`` 160 161:class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and 162 ``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``, 163 ``__delitem__``, and ``setdefault`` 164 ``__iter__``, 165 ``__len__`` 166 167 168:class:`MappingView` :class:`Sized` ``__len__`` 169:class:`ItemsView` :class:`MappingView`, ``__contains__``, 170 :class:`Set` ``__iter__`` 171:class:`KeysView` :class:`MappingView`, ``__contains__``, 172 :class:`Set` ``__iter__`` 173:class:`ValuesView` :class:`MappingView`, ``__contains__``, ``__iter__`` 174 :class:`Collection` 175:class:`Awaitable` [1]_ ``__await__`` 176:class:`Coroutine` [1]_ :class:`Awaitable` ``send``, ``throw`` ``close`` 177:class:`AsyncIterable` [1]_ ``__aiter__`` 178:class:`AsyncIterator` [1]_ :class:`AsyncIterable` ``__anext__`` ``__aiter__`` 179:class:`AsyncGenerator` [1]_ :class:`AsyncIterator` ``asend``, ``athrow`` ``aclose``, ``__aiter__``, ``__anext__`` 180============================== ====================== ======================= ==================================================== 181 182 183.. rubric:: Footnotes 184 185.. [1] These ABCs override :meth:`object.__subclasshook__` to support 186 testing an interface by verifying the required methods are present 187 and have not been set to :const:`None`. This only works for simple 188 interfaces. More complex interfaces require registration or direct 189 subclassing. 190 191.. [2] Checking ``isinstance(obj, Iterable)`` detects classes that are 192 registered as :class:`Iterable` or that have an :meth:`__iter__` 193 method, but it does not detect classes that iterate with the 194 :meth:`__getitem__` method. The only reliable way to determine 195 whether an object is :term:`iterable` is to call ``iter(obj)``. 196 197 198Collections Abstract Base Classes -- Detailed Descriptions 199---------------------------------------------------------- 200 201 202.. class:: Container 203 204 ABC for classes that provide the :meth:`__contains__` method. 205 206.. class:: Hashable 207 208 ABC for classes that provide the :meth:`__hash__` method. 209 210.. class:: Sized 211 212 ABC for classes that provide the :meth:`__len__` method. 213 214.. class:: Callable 215 216 ABC for classes that provide the :meth:`__call__` method. 217 218.. class:: Iterable 219 220 ABC for classes that provide the :meth:`__iter__` method. 221 222 Checking ``isinstance(obj, Iterable)`` detects classes that are registered 223 as :class:`Iterable` or that have an :meth:`__iter__` method, but it does 224 not detect classes that iterate with the :meth:`__getitem__` method. 225 The only reliable way to determine whether an object is :term:`iterable` 226 is to call ``iter(obj)``. 227 228.. class:: Collection 229 230 ABC for sized iterable container classes. 231 232 .. versionadded:: 3.6 233 234.. class:: Iterator 235 236 ABC for classes that provide the :meth:`~iterator.__iter__` and 237 :meth:`~iterator.__next__` methods. See also the definition of 238 :term:`iterator`. 239 240.. class:: Reversible 241 242 ABC for iterable classes that also provide the :meth:`__reversed__` 243 method. 244 245 .. versionadded:: 3.6 246 247.. class:: Generator 248 249 ABC for generator classes that implement the protocol defined in 250 :pep:`342` that extends iterators with the :meth:`~generator.send`, 251 :meth:`~generator.throw` and :meth:`~generator.close` methods. 252 See also the definition of :term:`generator`. 253 254 .. versionadded:: 3.5 255 256.. class:: Sequence 257 MutableSequence 258 ByteString 259 260 ABCs for read-only and mutable :term:`sequences <sequence>`. 261 262 Implementation note: Some of the mixin methods, such as 263 :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make 264 repeated calls to the underlying :meth:`__getitem__` method. 265 Consequently, if :meth:`__getitem__` is implemented with constant 266 access speed, the mixin methods will have linear performance; 267 however, if the underlying method is linear (as it would be with a 268 linked list), the mixins will have quadratic performance and will 269 likely need to be overridden. 270 271 .. versionchanged:: 3.5 272 The index() method added support for *stop* and *start* 273 arguments. 274 275.. class:: Set 276 MutableSet 277 278 ABCs for read-only and mutable sets. 279 280.. class:: Mapping 281 MutableMapping 282 283 ABCs for read-only and mutable :term:`mappings <mapping>`. 284 285.. class:: MappingView 286 ItemsView 287 KeysView 288 ValuesView 289 290 ABCs for mapping, items, keys, and values :term:`views <dictionary view>`. 291 292.. class:: Awaitable 293 294 ABC for :term:`awaitable` objects, which can be used in :keyword:`await` 295 expressions. Custom implementations must provide the :meth:`__await__` 296 method. 297 298 :term:`Coroutine <coroutine>` objects and instances of the 299 :class:`~collections.abc.Coroutine` ABC are all instances of this ABC. 300 301 .. note:: 302 In CPython, generator-based coroutines (generators decorated with 303 :func:`types.coroutine` or :func:`asyncio.coroutine`) are 304 *awaitables*, even though they do not have an :meth:`__await__` method. 305 Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``. 306 Use :func:`inspect.isawaitable` to detect them. 307 308 .. versionadded:: 3.5 309 310.. class:: Coroutine 311 312 ABC for coroutine compatible classes. These implement the 313 following methods, defined in :ref:`coroutine-objects`: 314 :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and 315 :meth:`~coroutine.close`. Custom implementations must also implement 316 :meth:`__await__`. All :class:`Coroutine` instances are also instances of 317 :class:`Awaitable`. See also the definition of :term:`coroutine`. 318 319 .. note:: 320 In CPython, generator-based coroutines (generators decorated with 321 :func:`types.coroutine` or :func:`asyncio.coroutine`) are 322 *awaitables*, even though they do not have an :meth:`__await__` method. 323 Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. 324 Use :func:`inspect.isawaitable` to detect them. 325 326 .. versionadded:: 3.5 327 328.. class:: AsyncIterable 329 330 ABC for classes that provide ``__aiter__`` method. See also the 331 definition of :term:`asynchronous iterable`. 332 333 .. versionadded:: 3.5 334 335.. class:: AsyncIterator 336 337 ABC for classes that provide ``__aiter__`` and ``__anext__`` 338 methods. See also the definition of :term:`asynchronous iterator`. 339 340 .. versionadded:: 3.5 341 342.. class:: AsyncGenerator 343 344 ABC for asynchronous generator classes that implement the protocol 345 defined in :pep:`525` and :pep:`492`. 346 347 .. versionadded:: 3.6 348 349Examples and Recipes 350-------------------- 351 352ABCs allow us to ask classes or instances if they provide 353particular functionality, for example:: 354 355 size = None 356 if isinstance(myvar, collections.abc.Sized): 357 size = len(myvar) 358 359Several of the ABCs are also useful as mixins that make it easier to develop 360classes supporting container APIs. For example, to write a class supporting 361the full :class:`Set` API, it is only necessary to supply the three underlying 362abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. 363The ABC supplies the remaining methods such as :meth:`__and__` and 364:meth:`isdisjoint`:: 365 366 class ListBasedSet(collections.abc.Set): 367 ''' Alternate set implementation favoring space over speed 368 and not requiring the set elements to be hashable. ''' 369 def __init__(self, iterable): 370 self.elements = lst = [] 371 for value in iterable: 372 if value not in lst: 373 lst.append(value) 374 375 def __iter__(self): 376 return iter(self.elements) 377 378 def __contains__(self, value): 379 return value in self.elements 380 381 def __len__(self): 382 return len(self.elements) 383 384 s1 = ListBasedSet('abcdef') 385 s2 = ListBasedSet('defghi') 386 overlap = s1 & s2 # The __and__() method is supported automatically 387 388Notes on using :class:`Set` and :class:`MutableSet` as a mixin: 389 390(1) 391 Since some set operations create new sets, the default mixin methods need 392 a way to create new instances from an iterable. The class constructor is 393 assumed to have a signature in the form ``ClassName(iterable)``. 394 That assumption is factored-out to an internal classmethod called 395 :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set. 396 If the :class:`Set` mixin is being used in a class with a different 397 constructor signature, you will need to override :meth:`_from_iterable` 398 with a classmethod or regular method that can construct new instances from 399 an iterable argument. 400 401(2) 402 To override the comparisons (presumably for speed, as the 403 semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`, 404 then the other operations will automatically follow suit. 405 406(3) 407 The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value 408 for the set; however, :meth:`__hash__` is not defined because not all sets 409 are hashable or immutable. To add set hashability using mixins, 410 inherit from both :meth:`Set` and :meth:`Hashable`, then define 411 ``__hash__ = Set._hash``. 412 413.. seealso:: 414 415 * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an 416 example built on :class:`MutableSet`. 417 418 * For more about ABCs, see the :mod:`abc` module and :pep:`3119`. 419