https://github.com/python/cpython/commit/122e88a8354e3f75aeaf6211232dac88ac2... commit: 122e88a8354e3f75aeaf6211232dac88ac296d54 branch: master author: Eric Appelt <eric.appelt@gmail.com> committer: Éric Araujo <merwok@users.noreply.github.com> date: 2017-08-30T18:47:52-04:00 summary: bpo-30096: Use ABC in abc reference examples (#1220) Use base class rather than metaclass in examples. files: M Doc/library/abc.rst diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 966003bd45a..6001db32df4 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -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 @@ -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. @@ -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): @@ -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: @@ -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, ...): ... @@ -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, ...): @@ -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(...): @@ -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): @@ -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): ...