From c0b4a6ac2469e3cf113499401a754508eefe2e4d Mon Sep 17 00:00:00 2001 From: Eric Appelt Date: Thu, 20 Apr 2017 16:20:21 -0500 Subject: [PATCH 1/3] bpo-30096: Use ABC in abc reference examples Update example code to use abc.ABC rather than abc.ABCMeta to define abstract base classes. Add examples using both methods in the documentation for abc.ABC. Reorder the documentation of the classes so that the examples make sense when the document is read from top to bottom. --- Doc/library/abc.rst | 55 ++++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 21 deletions(-) diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 966003bd45ada1..908896e3afda7f 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,9 +72,7 @@ This module provides the following classes: Register *subclass* as a "virtual subclass" of this ABC. For example:: - from abc import ABCMeta - - class MyABC(metaclass=ABCMeta): + class MyABC(ABC): pass MyABC.register(tuple) @@ -95,7 +119,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 +156,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 +181,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 +243,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 +264,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 +291,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 +301,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): ... From 1cb39eadc4829641ac1ea49b5c2dbd5196316d3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 30 Aug 2017 18:05:50 -0400 Subject: [PATCH 2/3] Restore import --- Doc/library/abc.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 908896e3afda7f..97bdd20784e47e 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -72,13 +72,15 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance: Register *subclass* as a "virtual subclass" of this ABC. For example:: - class MyABC(ABC): - pass + from abc import ABC + + 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. From ec9328fed42a114dc73b9cbbf705f055b34b084d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 30 Aug 2017 18:11:32 -0400 Subject: [PATCH 3/3] Thanks for the trailing whitespace github --- Doc/library/abc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 97bdd20784e47e..6001db32df49c3 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -73,7 +73,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance: example:: from abc import ABC - + class MyABC(ABC): pass