python-clinic / Doc / library / abc.rst

Full commit

:mod:`abc` --- Abstract Base Classes

Source code: :source:`Lib/`

This module provides the infrastructure for defining :term:`abstract base classes <abstract base class>` (ABCs) in Python, as outlined in PEP 3119; see the PEP for why this was added to Python. (See also PEP 3141 and the :mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.)

The :mod:`collections` module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition the :mod:`` submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, is it hashable or a mapping.

This module provides the following classes:

Metaclass for defining Abstract Base Classes (ABCs).

Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete classes (even built-in classes) and unrelated ABCs as "virtual subclasses" -- these and their descendants will be considered subclasses of the registering ABC by the built-in :func:`issubclass` function, but the registering ABC won't show up in their MRO (Method Resolution Order) nor will method implementations defined by the registering ABC be callable (not even via :func:`super`). [1]

Classes created with a metaclass of :class:`ABCMeta` have the following method:

You can also override this method in an abstract base class:

For a demonstration of these concepts, look at this example ABC definition:

class Foo:
    def __getitem__(self, index):
    def __len__(self):
    def get_iterator(self):
        return iter(self)

class MyIterable(metaclass=ABCMeta):

    def __iter__(self):
        while False:
            yield None

    def get_iterator(self):
        return self.__iter__()

    def __subclasshook__(cls, C):
        if cls is MyIterable:
            if any("__iter__" in B.__dict__ for B in C.__mro__):
                return True
        return NotImplemented


The ABC MyIterable defines the standard iterable method, :meth:`__iter__`, as an abstract method. The implementation given here can still be called from subclasses. The :meth:`get_iterator` method is also part of the MyIterable abstract base class, but it does not have to be overridden in non-abstract derived classes.

The :meth:`__subclasshook__` class method defined here says that any class that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of one of its base classes, accessed via the :attr:`__mro__` list) is considered a MyIterable too.

Finally, the last line makes Foo a virtual subclass of MyIterable, even though it does not define an :meth:`__iter__` method (it uses the old-style iterable protocol, defined in terms of :meth:`__len__` and :meth:`__getitem__`). Note that this will not make get_iterator available as a method of Foo, so it is provided separately.

A helper class that has :class:`ABCMeta` as its metaclass. With this class, an abstract base class can be created by simply deriving from :class:`ABC`, avoiding sometimes confusing metaclass usage.

Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore inheriting from :class:`ABC` requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts.

The :mod:`abc` module also provides the following decorators:


[1]C++ programmers should note that Python's virtual base class concept is not the same as C++'s.