gh-101100: Fix Sphinx nitpicks in library/abc.rst (#112703)

This commit is contained in:
Alex Waygood 2023-12-04 12:42:24 +00:00 committed by GitHub
parent 6ca9d3e017
commit 9560e0d6d7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 22 deletions

View file

@ -21,7 +21,7 @@ The :mod:`collections` module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the ABCs; these can, of course, be further derived. In addition, the
:mod:`collections.abc` submodule has some ABCs that can be used to test whether :mod:`collections.abc` submodule has some ABCs that can be used to test whether
a class or instance provides a particular interface, for example, if it is a class or instance provides a particular interface, for example, if it is
:term:`hashable` or if it is a mapping. :term:`hashable` or if it is a :term:`mapping`.
This module provides the metaclass :class:`ABCMeta` for defining ABCs and This module provides the metaclass :class:`ABCMeta` for defining ABCs and
@ -30,7 +30,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
.. class:: ABC .. class:: ABC
A helper class that has :class:`ABCMeta` as its metaclass. With this class, 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` an abstract base class can be created by simply deriving from :class:`!ABC`
avoiding sometimes confusing metaclass usage, for example:: avoiding sometimes confusing metaclass usage, for example::
from abc import ABC from abc import ABC
@ -38,11 +38,11 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
class MyABC(ABC): class MyABC(ABC):
pass pass
Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore Note that the type of :class:`!ABC` is still :class:`ABCMeta`, therefore
inheriting from :class:`ABC` requires the usual precautions regarding inheriting from :class:`!ABC` requires the usual precautions regarding
metaclass usage, as multiple inheritance may lead to metaclass conflicts. metaclass usage, as multiple inheritance may lead to metaclass conflicts.
One may also define an abstract base class by passing the metaclass One may also define an abstract base class by passing the metaclass
keyword and using :class:`ABCMeta` directly, for example:: keyword and using :class:`!ABCMeta` directly, for example::
from abc import ABCMeta from abc import ABCMeta
@ -65,7 +65,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
implementations defined by the registering ABC be callable (not even via implementations defined by the registering ABC be callable (not even via
:func:`super`). [#]_ :func:`super`). [#]_
Classes created with a metaclass of :class:`ABCMeta` have the following method: Classes created with a metaclass of :class:`!ABCMeta` have the following method:
.. method:: register(subclass) .. method:: register(subclass)
@ -86,7 +86,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
Returns the registered subclass, to allow usage as a class decorator. Returns the registered subclass, to allow usage as a class decorator.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
To detect calls to :meth:`register`, you can use the To detect calls to :meth:`!register`, you can use the
:func:`get_cache_token` function. :func:`get_cache_token` function.
You can also override this method in an abstract base class: You can also override this method in an abstract base class:
@ -96,10 +96,10 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
(Must be defined as a class method.) (Must be defined as a class method.)
Check whether *subclass* is considered a subclass of this ABC. This means Check whether *subclass* is considered a subclass of this ABC. This means
that you can customize the behavior of ``issubclass`` further without the that you can customize the behavior of :func:`issubclass` further without the
need to call :meth:`register` on every class you want to consider a need to call :meth:`register` on every class you want to consider a
subclass of the ABC. (This class method is called from the subclass of the ABC. (This class method is called from the
:meth:`__subclasscheck__` method of the ABC.) :meth:`~class.__subclasscheck__` method of the ABC.)
This method should return ``True``, ``False`` or ``NotImplemented``. If This method should return ``True``, ``False`` or ``NotImplemented``. If
it returns ``True``, the *subclass* is considered a subclass of this ABC. it returns ``True``, the *subclass* is considered a subclass of this ABC.
@ -142,7 +142,7 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
The ABC ``MyIterable`` defines the standard iterable method, The ABC ``MyIterable`` defines the standard iterable method,
:meth:`~iterator.__iter__`, as an abstract method. The implementation given :meth:`~iterator.__iter__`, as an abstract method. The implementation given
here can still be called from subclasses. The :meth:`get_iterator` method 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 is also part of the ``MyIterable`` abstract base class, but it does not have
to be overridden in non-abstract derived classes. to be overridden in non-abstract derived classes.
@ -153,14 +153,14 @@ a helper class :class:`ABC` to alternatively define ABCs through inheritance:
Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``, Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
even though it does not define an :meth:`~iterator.__iter__` method (it uses even though it does not define an :meth:`~iterator.__iter__` method (it uses
the old-style iterable protocol, defined in terms of :meth:`__len__` and the old-style iterable protocol, defined in terms of :meth:`~object.__len__` and
:meth:`~object.__getitem__`). Note that this will not make ``get_iterator`` :meth:`~object.__getitem__`). Note that this will not make ``get_iterator``
available as a method of ``Foo``, so it is provided separately. available as a method of ``Foo``, so it is provided separately.
The :mod:`abc` module also provides the following decorator: The :mod:`!abc` module also provides the following decorator:
.. decorator:: abstractmethod .. decorator:: abstractmethod
@ -168,19 +168,19 @@ The :mod:`abc` module also provides the following decorator:
Using this decorator requires that the class's metaclass is :class:`ABCMeta` Using this decorator requires that the class's metaclass is :class:`ABCMeta`
or is derived from it. A class that has a metaclass derived from or is derived from it. A class that has a metaclass derived from
:class:`ABCMeta` cannot be instantiated unless all of its abstract methods :class:`!ABCMeta` cannot be instantiated unless all of its abstract methods
and properties are overridden. The abstract methods can be called using any and properties are overridden. The abstract methods can be called using any
of the normal 'super' call mechanisms. :func:`abstractmethod` may be used of the normal 'super' call mechanisms. :func:`!abstractmethod` may be used
to declare abstract methods for properties and descriptors. to declare abstract methods for properties and descriptors.
Dynamically adding abstract methods to a class, or attempting to modify the Dynamically adding abstract methods to a class, or attempting to modify the
abstraction status of a method or class once it is created, are only abstraction status of a method or class once it is created, are only
supported using the :func:`update_abstractmethods` function. The supported using the :func:`update_abstractmethods` function. The
:func:`abstractmethod` only affects subclasses derived using regular :func:`!abstractmethod` only affects subclasses derived using regular
inheritance; "virtual subclasses" registered with the ABC's :meth:`register` inheritance; "virtual subclasses" registered with the ABC's
method are not affected. :meth:`~ABCMeta.register` method are not affected.
When :func:`abstractmethod` is applied in combination with other method When :func:`!abstractmethod` is applied in combination with other method
descriptors, it should be applied as the innermost decorator, as shown in descriptors, it should be applied as the innermost decorator, as shown in
the following usage examples:: the following usage examples::
@ -216,7 +216,7 @@ The :mod:`abc` module also provides the following decorator:
In order to correctly interoperate with the abstract base class machinery, In order to correctly interoperate with the abstract base class machinery,
the descriptor must identify itself as abstract using the descriptor must identify itself as abstract using
:attr:`__isabstractmethod__`. In general, this attribute should be ``True`` :attr:`!__isabstractmethod__`. In general, this attribute should be ``True``
if any of the methods used to compose the descriptor are abstract. For if any of the methods used to compose the descriptor are abstract. For
example, Python's built-in :class:`property` does the equivalent of:: example, Python's built-in :class:`property` does the equivalent of::
@ -236,7 +236,7 @@ The :mod:`abc` module also provides the following decorator:
super-call in a framework that uses cooperative super-call in a framework that uses cooperative
multiple-inheritance. multiple-inheritance.
The :mod:`abc` module also supports the following legacy decorators: The :mod:`!abc` module also supports the following legacy decorators:
.. decorator:: abstractclassmethod .. decorator:: abstractclassmethod
@ -323,7 +323,7 @@ The :mod:`abc` module also supports the following legacy decorators:
... ...
The :mod:`abc` module also provides the following functions: The :mod:`!abc` module also provides the following functions:
.. function:: get_cache_token() .. function:: get_cache_token()

View file

@ -26,7 +26,6 @@ Doc/howto/enum.rst
Doc/howto/isolating-extensions.rst Doc/howto/isolating-extensions.rst
Doc/howto/logging.rst Doc/howto/logging.rst
Doc/howto/urllib2.rst Doc/howto/urllib2.rst
Doc/library/abc.rst
Doc/library/ast.rst Doc/library/ast.rst
Doc/library/asyncio-extending.rst Doc/library/asyncio-extending.rst
Doc/library/asyncio-policy.rst Doc/library/asyncio-policy.rst