# `collections.abc` — Abstract Base Classes for Containers ¶ Added 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. An `issubclass()` or `isinstance()` test for an interface works in one of three ways. 1. A newly written class can inherit directly from one of the abstract base classes. The class must supply the required abstract methods. The remaining mixin methods come from inheritance and can be overridden if desired. Other methods may be added as needed: Copy ``` class C(Sequence): # Direct inheritance def __init__(self): ... # Extra method not required by the ABC def __getitem__(self, index): ... # Required abstract method def __len__(self): ... # Required abstract method def count(self, value): ... # Optionally override a mixin method ``` Copy ``` >>> issubclass(C, Sequence) True >>> isinstance(C(), Sequence) True ``` 2. Existing classes and built-in classes can be registered as “virtual subclasses” of the ABCs. Those classes should define the full API including all of the abstract methods and all of the mixin methods. This lets users rely on `issubclass()` or `isinstance()` tests to determine whether the full interface is supported. The exception to this rule is for methods that are automatically inferred from the rest of the API: Copy ``` class D: # No inheritance def __init__(self): ... # Extra method not required by the ABC def __getitem__(self, index): ... # Abstract method def __len__(self): ... # Abstract method def count(self, value): ... # Mixin method def index(self, value): ... # Mixin method Sequence.register(D) # Register instead of inherit ``` Copy ``` >>> issubclass(D, Sequence) True >>> isinstance(D(), Sequence) True ``` In this example, class `D` does not need to define `__contains__`, `__iter__`, and `__reversed__` because the in-operator, the iteration logic, and the `reversed()` function automatically fall back to using `__getitem__` and `__len__`. 3. Some simple interfaces are directly recognizable by the presence of the required methods (unless those methods have been set to `None`): Copy ``` class E: def __iter__(self): ... def __next__(self): ... ``` Copy ``` >>> issubclass(E, Iterable) True >>> isinstance(E(), Iterable) True ``` Complex interfaces do not support this last technique because an interface is more than just the presence of method names. Interfaces specify semantics and relationships between methods that cannot be inferred solely from the presence of specific method names. For example, knowing that a class supplies `__getitem__`, `__len__`, and `__iter__` is insufficient for distinguishing a `Sequence` from a `Mapping`. Added in version 3.9: These abstract classes now support `[]`. See Generic Alias Type and **PEP 585**. ## Collections Abstract Base Classes ¶ The collections module offers the following ABCs: | ABC | Inherits from | Abstract Methods | Mixin Methods | | --- | --- | --- | --- | | `Container` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__contains__` | | | `Hashable` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__hash__` | | | `Iterable` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) [\[2\]](https://docs.python.org/3/library/collections.abc.html#id19) | | `__iter__` | | | `Iterator` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `Iterable` | `__next__` | `__iter__` | | `Reversible` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `Iterable` | `__reversed__` | | | `Generator` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `Iterator` | `send`, `throw` | `close`, `__iter__`, `__next__` | | `Sized` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__len__` | | | `Callable` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__call__` | | | `Collection` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `Sized`,<br>`Iterable`,<br>`Container` | `__contains__`,<br>`__iter__`,<br>`__len__` | | | `Sequence` | `Reversible`,<br>`Collection` | `__getitem__`,<br>`__len__` | `__contains__`, `__iter__`, `__reversed__`,<br>`index`, and `count` | | `MutableSequence` | `Sequence` | `__getitem__`,<br>`__setitem__`,<br>`__delitem__`,<br>`__len__`,<br>`insert` | Inherited `Sequence` methods and<br>`append`, `clear`, `reverse`, `extend`,<br>`pop`, `remove`, and `__iadd__` | | `ByteString` | `Sequence` | `__getitem__`,<br>`__len__` | Inherited `Sequence` methods | | `Set` | `Collection` | `__contains__`,<br>`__iter__`,<br>`__len__` | `__le__`, `__lt__`, `__eq__`, `__ne__`,<br>`__gt__`, `__ge__`, `__and__`, `__or__`,<br>`__sub__`, `__rsub__`, `__xor__`, `__rxor__`<br>and `isdisjoint` | | `MutableSet` | `Set` | `__contains__`,<br>`__iter__`,<br>`__len__`,<br>`add`,<br>`discard` | Inherited `Set` methods and<br>`clear`, `pop`, `remove`, `__ior__`,<br>`__iand__`, `__ixor__`, and `__isub__` | | `Mapping` | `Collection` | `__getitem__`,<br>`__iter__`,<br>`__len__` | `__contains__`, `keys`, `items`, `values`,<br>`get`, `__eq__`, and `__ne__` | | `MutableMapping` | `Mapping` | `__getitem__`,<br>`__setitem__`,<br>`__delitem__`,<br>`__iter__`,<br>`__len__` | Inherited `Mapping` methods and<br>`pop`, `popitem`, `clear`, `update`,<br>and `setdefault` | | `MappingView` | `Sized` | | `__init__`, `__len__` and `__repr__` | | `ItemsView` | `MappingView`,<br>`Set` | | `__contains__`,<br>`__iter__` | | `KeysView` | `MappingView`,<br>`Set` | | `__contains__`,<br>`__iter__` | | `ValuesView` | `MappingView`,<br>`Collection` | | `__contains__`, `__iter__` | | `Awaitable` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__await__` | | | `Coroutine` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `Awaitable` | `send`, `throw` | `close` | | `AsyncIterable` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__aiter__` | | | `AsyncIterator` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `AsyncIterable` | `__anext__` | `__aiter__` | | `AsyncGenerator` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | `AsyncIterator` | `asend`, `athrow` | `aclose`, `__aiter__`, `__anext__` | | `Buffer` [\[1\]](https://docs.python.org/3/library/collections.abc.html#id18) | | `__buffer__` | | Footnotes ## Collections Abstract Base Classes – Detailed Descriptions ¶ _class_ collections.abc.Container ¶ ABC for classes that provide the `__contains__()` method. _class_ collections.abc.Hashable ¶ ABC for classes that provide the `__hash__()` method. _class_ collections.abc.Sized ¶ ABC for classes that provide the `__len__()` method. _class_ collections.abc.Callable ¶ ABC for classes that provide the `__call__()` method. See Annotating callable objects for details on how to use `Callable` in type annotations. _class_ collections.abc.Iterable ¶ ABC for classes that provide the `__iter__()` method. Checking `isinstance(obj, Iterable)` detects classes that are registered as `Iterable` or that have an `__iter__()` method, but it does not detect classes that iterate with the `__getitem__()` method. The only reliable way to determine whether an object is iterable is to call `iter(obj)`.