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 :term:`hashable` or whether it is a :term:`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__(self): ... 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``, ``clear``, ``reverse``, ``extend``, 140 ``__delitem__``, ``pop``, ``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:class:`Buffer` [1]_ ``__buffer__`` 181============================== ====================== ======================= ==================================================== 182 183 184.. rubric:: Footnotes 185 186.. [1] These ABCs override :meth:`~abc.ABCMeta.__subclasshook__` to support 187 testing an interface by verifying the required methods are present 188 and have not been set to :const:`None`. This only works for simple 189 interfaces. More complex interfaces require registration or direct 190 subclassing. 191 192.. [2] Checking ``isinstance(obj, Iterable)`` detects classes that are 193 registered as :class:`Iterable` or that have an :meth:`~container.__iter__` 194 method, but it does not detect classes that iterate with the 195 :meth:`~object.__getitem__` method. The only reliable way to determine 196 whether an object is :term:`iterable` is to call ``iter(obj)``. 197 198 199Collections Abstract Base Classes -- Detailed Descriptions 200---------------------------------------------------------- 201 202 203.. class:: Container 204 205 ABC for classes that provide the :meth:`~object.__contains__` method. 206 207.. class:: Hashable 208 209 ABC for classes that provide the :meth:`~object.__hash__` method. 210 211.. class:: Sized 212 213 ABC for classes that provide the :meth:`~object.__len__` method. 214 215.. class:: Callable 216 217 ABC for classes that provide the :meth:`~object.__call__` method. 218 219 See :ref:`annotating-callables` for details on how to use 220 :class:`!Callable` in type annotations. 221 222.. class:: Iterable 223 224 ABC for classes that provide the :meth:`~container.__iter__` method. 225 226 Checking ``isinstance(obj, Iterable)`` detects classes that are registered 227 as :class:`Iterable` or that have an :meth:`~container.__iter__` method, 228 but it does 229 not detect classes that iterate with the :meth:`~object.__getitem__` method. 230 The only reliable way to determine whether an object is :term:`iterable` 231 is to call ``iter(obj)``. 232 233.. class:: Collection 234 235 ABC for sized iterable container classes. 236 237 .. versionadded:: 3.6 238 239.. class:: Iterator 240 241 ABC for classes that provide the :meth:`~iterator.__iter__` and 242 :meth:`~iterator.__next__` methods. See also the definition of 243 :term:`iterator`. 244 245.. class:: Reversible 246 247 ABC for iterable classes that also provide the :meth:`~object.__reversed__` 248 method. 249 250 .. versionadded:: 3.6 251 252.. class:: Generator 253 254 ABC for :term:`generator` classes that implement the protocol defined in 255 :pep:`342` that extends :term:`iterators <iterator>` with the 256 :meth:`~generator.send`, 257 :meth:`~generator.throw` and :meth:`~generator.close` methods. 258 259 See :ref:`annotating-generators-and-coroutines` 260 for details on using :class:`!Generator` in type annotations. 261 262 .. versionadded:: 3.5 263 264.. class:: Sequence 265 MutableSequence 266 ByteString 267 268 ABCs for read-only and mutable :term:`sequences <sequence>`. 269 270 Implementation note: Some of the mixin methods, such as 271 :meth:`~container.__iter__`, :meth:`~object.__reversed__` and :meth:`index`, make 272 repeated calls to the underlying :meth:`~object.__getitem__` method. 273 Consequently, if :meth:`~object.__getitem__` is implemented with constant 274 access speed, the mixin methods will have linear performance; 275 however, if the underlying method is linear (as it would be with a 276 linked list), the mixins will have quadratic performance and will 277 likely need to be overridden. 278 279 .. versionchanged:: 3.5 280 The index() method added support for *stop* and *start* 281 arguments. 282 283 .. deprecated-removed:: 3.12 3.14 284 The :class:`ByteString` ABC has been deprecated. 285 For use in typing, prefer a union, like ``bytes | bytearray``, or 286 :class:`collections.abc.Buffer`. 287 For use as an ABC, prefer :class:`Sequence` or :class:`collections.abc.Buffer`. 288 289.. class:: Set 290 MutableSet 291 292 ABCs for read-only and mutable :ref:`sets <types-set>`. 293 294.. class:: Mapping 295 MutableMapping 296 297 ABCs for read-only and mutable :term:`mappings <mapping>`. 298 299.. class:: MappingView 300 ItemsView 301 KeysView 302 ValuesView 303 304 ABCs for mapping, items, keys, and values :term:`views <dictionary view>`. 305 306.. class:: Awaitable 307 308 ABC for :term:`awaitable` objects, which can be used in :keyword:`await` 309 expressions. Custom implementations must provide the 310 :meth:`~object.__await__` method. 311 312 :term:`Coroutine <coroutine>` objects and instances of the 313 :class:`~collections.abc.Coroutine` ABC are all instances of this ABC. 314 315 .. note:: 316 In CPython, generator-based coroutines (:term:`generators <generator>` 317 decorated with :func:`@types.coroutine <types.coroutine>`) are 318 *awaitables*, even though they do not have an :meth:`~object.__await__` method. 319 Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``. 320 Use :func:`inspect.isawaitable` to detect them. 321 322 .. versionadded:: 3.5 323 324.. class:: Coroutine 325 326 ABC for :term:`coroutine` compatible classes. These implement the 327 following methods, defined in :ref:`coroutine-objects`: 328 :meth:`~coroutine.send`, :meth:`~coroutine.throw`, and 329 :meth:`~coroutine.close`. Custom implementations must also implement 330 :meth:`~object.__await__`. All :class:`Coroutine` instances are also 331 instances of :class:`Awaitable`. 332 333 .. note:: 334 In CPython, generator-based coroutines (:term:`generators <generator>` 335 decorated with :func:`@types.coroutine <types.coroutine>`) are 336 *awaitables*, even though they do not have an :meth:`~object.__await__` method. 337 Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``. 338 Use :func:`inspect.isawaitable` to detect them. 339 340 See :ref:`annotating-generators-and-coroutines` 341 for details on using :class:`!Coroutine` in type annotations. 342 The variance and order of type parameters correspond to those of 343 :class:`Generator`. 344 345 .. versionadded:: 3.5 346 347.. class:: AsyncIterable 348 349 ABC for classes that provide an ``__aiter__`` method. See also the 350 definition of :term:`asynchronous iterable`. 351 352 .. versionadded:: 3.5 353 354.. class:: AsyncIterator 355 356 ABC for classes that provide ``__aiter__`` and ``__anext__`` 357 methods. See also the definition of :term:`asynchronous iterator`. 358 359 .. versionadded:: 3.5 360 361.. class:: AsyncGenerator 362 363 ABC for :term:`asynchronous generator` classes that implement the protocol 364 defined in :pep:`525` and :pep:`492`. 365 366 See :ref:`annotating-generators-and-coroutines` 367 for details on using :class:`!AsyncGenerator` in type annotations. 368 369 .. versionadded:: 3.6 370 371.. class:: Buffer 372 373 ABC for classes that provide the :meth:`~object.__buffer__` method, 374 implementing the :ref:`buffer protocol <bufferobjects>`. See :pep:`688`. 375 376 .. versionadded:: 3.12 377 378Examples and Recipes 379-------------------- 380 381ABCs allow us to ask classes or instances if they provide 382particular functionality, for example:: 383 384 size = None 385 if isinstance(myvar, collections.abc.Sized): 386 size = len(myvar) 387 388Several of the ABCs are also useful as mixins that make it easier to develop 389classes supporting container APIs. For example, to write a class supporting 390the full :class:`Set` API, it is only necessary to supply the three underlying 391abstract methods: :meth:`~object.__contains__`, :meth:`~container.__iter__`, and 392:meth:`~object.__len__`. The ABC supplies the remaining methods such as 393:meth:`!__and__` and :meth:`~frozenset.isdisjoint`:: 394 395 class ListBasedSet(collections.abc.Set): 396 ''' Alternate set implementation favoring space over speed 397 and not requiring the set elements to be hashable. ''' 398 def __init__(self, iterable): 399 self.elements = lst = [] 400 for value in iterable: 401 if value not in lst: 402 lst.append(value) 403 404 def __iter__(self): 405 return iter(self.elements) 406 407 def __contains__(self, value): 408 return value in self.elements 409 410 def __len__(self): 411 return len(self.elements) 412 413 s1 = ListBasedSet('abcdef') 414 s2 = ListBasedSet('defghi') 415 overlap = s1 & s2 # The __and__() method is supported automatically 416 417Notes on using :class:`Set` and :class:`MutableSet` as a mixin: 418 419(1) 420 Since some set operations create new sets, the default mixin methods need 421 a way to create new instances from an :term:`iterable`. The class constructor is 422 assumed to have a signature in the form ``ClassName(iterable)``. 423 That assumption is factored-out to an internal :class:`classmethod` called 424 :meth:`!_from_iterable` which calls ``cls(iterable)`` to produce a new set. 425 If the :class:`Set` mixin is being used in a class with a different 426 constructor signature, you will need to override :meth:`!_from_iterable` 427 with a classmethod or regular method that can construct new instances from 428 an iterable argument. 429 430(2) 431 To override the comparisons (presumably for speed, as the 432 semantics are fixed), redefine :meth:`~object.__le__` and 433 :meth:`~object.__ge__`, 434 then the other operations will automatically follow suit. 435 436(3) 437 The :class:`Set` mixin provides a :meth:`!_hash` method to compute a hash value 438 for the set; however, :meth:`~object.__hash__` is not defined because not all sets 439 are :term:`hashable` or immutable. To add set hashability using mixins, 440 inherit from both :meth:`Set` and :meth:`Hashable`, then define 441 ``__hash__ = Set._hash``. 442 443.. seealso:: 444 445 * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an 446 example built on :class:`MutableSet`. 447 448 * For more about ABCs, see the :mod:`abc` module and :pep:`3119`. 449