[Python-checkins] bpo-30096: Use ABC in abc reference examples (#1220)

[Éric Araujo]

https://github.com/python/cpython/commit/122e88a8354e3f75aeaf6211232dac88ac296d54
commit: 122e88a8354e3f75aeaf6211232dac88ac296d54
branch: master
author: Eric Appelt <eric.appelt at gmail.com>
committer: Éric Araujo <merwok at 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):
               ...