[3.6] bpo-30096: Use ABC in abc reference examples (GH-1220) by miss-islington · Pull Request #3408 · python/cpython

Expand Up @@ -24,7 +24,33 @@ a class or instance provides a particular interface, for example, is it hashable or a mapping.

This module provides the following classes: This module provides the metaclass :class:`ABCMeta` for defining ABCs and a helper class :class:`ABC` to alternatively define ABCs through inheritance:
.. class:: ABC
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, for example::
from abc import ABC
class MyABC(ABC): pass
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. One may also define an abstract base class by passing the metaclass keyword and using :class:`ABCMeta` directly, for example::
from abc import ABCMeta
class MyABC(metaclass=ABCMeta): pass
.. versionadded:: 3.4

.. class:: ABCMeta
Expand All @@ -46,15 +72,15 @@ This module provides the following classes: Register *subclass* as a "virtual subclass" of this ABC. For example::
from abc import ABCMeta from abc import ABC
class MyABC(metaclass=ABCMeta): pass class MyABC(ABC): pass
MyABC.register(tuple) MyABC.register(tuple)
assert issubclass(tuple, MyABC) assert isinstance((), MyABC) assert issubclass(tuple, MyABC) assert isinstance((), MyABC)
.. versionchanged:: 3.3 Returns the registered subclass, to allow usage as a class decorator. Expand Down Expand Up @@ -95,7 +121,7 @@ This module provides the following classes: def get_iterator(self): return iter(self)
class MyIterable(metaclass=ABCMeta): class MyIterable(ABC):
@abstractmethod def __iter__(self): Expand Down Expand Up @@ -132,17 +158,6 @@ This module provides the following classes: available as a method of ``Foo``, so it is provided separately.

.. class:: ABC
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.
.. versionadded:: 3.4

The :mod:`abc` module also provides the following decorators: Expand All @@ -168,7 +183,7 @@ The :mod:`abc` module also provides the following decorators: descriptors, it should be applied as the innermost decorator, as shown in the following usage examples::
class C(metaclass=ABCMeta): class C(ABC): @abstractmethod def my_abstract_method(self, ...): ... Expand Down Expand Up @@ -230,7 +245,7 @@ The :mod:`abc` module also provides the following decorators: is now correctly identified as abstract when applied to an abstract method::
class C(metaclass=ABCMeta): class C(ABC): @classmethod @abstractmethod def my_abstract_classmethod(cls, ...): Expand All @@ -251,7 +266,7 @@ The :mod:`abc` module also provides the following decorators: is now correctly identified as abstract when applied to an abstract method::
class C(metaclass=ABCMeta): class C(ABC): @staticmethod @abstractmethod def my_abstract_staticmethod(...): Expand All @@ -278,7 +293,7 @@ The :mod:`abc` module also provides the following decorators: is now correctly identified as abstract when applied to an abstract method::
class C(metaclass=ABCMeta): class C(ABC): @property @abstractmethod def my_abstract_property(self): Expand All @@ -288,7 +303,7 @@ The :mod:`abc` module also provides the following decorators: read-write abstract property by appropriately marking one or more of the underlying methods as abstract::
class C(metaclass=ABCMeta): class C(ABC): @property def x(self): ... Expand Down