[3.12] gh-101100: Fix various Sphinx warnings for dunder references in the `library...

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Doc/conf.py b/Doc/conf.py
index bd098df3acc8203370ef4018267c668b0f7e061c..50207468f63c9440ca8a8ba82fe25875338664e0 100644 (file)
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -242,6 +242,7 @@ nitpick_ignore += [
     # Attributes/methods/etc. that definitely should be documented better,
     # but are deferred for now:
     ('py:attr', '__annotations__'),
+    ('py:meth', '__missing__'),
     ('py:attr', '__wrapped__'),
     ('py:meth', 'index'),  # list.index, tuple.index, etc.
 ]

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 649f1a3a5fc6d6d64172995f63afb48073e7eacd..47077d5b558046c1e163b479933a9f740b2bcc4a 100644 (file)
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -1976,7 +1976,8 @@ Examples of working with a :class:`.time` object::
    American EST and EDT.
 
    Special requirement for pickling:  A :class:`tzinfo` subclass must have an
-   :meth:`__init__` method that can be called with no arguments, otherwise it can be
+   :meth:`~object.__init__` method that can be called with no arguments,
+   otherwise it can be
    pickled but possibly not unpickled again. This is a technical requirement that
    may be relaxed in the future.
 

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index cb72be500c5435866a912964d29c23e3b4f1f3bb..d7c4a10d4983a3f25382a6fd37e70a6130bdbdf6 100644 (file)
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -1005,9 +1005,9 @@ their subgroups based on the types of the contained exceptions.
          True
 
 
-   Note that :exc:`BaseExceptionGroup` defines :meth:`__new__`, so
+   Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so
    subclasses that need a different constructor signature need to
-   override that rather than :meth:`__init__`. For example, the following
+   override that rather than :meth:`~object.__init__`. For example, the following
    defines an exception group subclass which accepts an exit_code and
    and constructs the group's message from it. ::
 

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 6cbdc39b3c024d706181c12f0017f65d759d2b39..9173db07fd00718456b4447bc943157e68a7e93b 100644 (file)
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -1408,7 +1408,8 @@ The :mod:`test.support.os_helper` module provides support for os tests.
 
 .. class:: FakePath(path)
 
-   Simple :term:`path-like object`.  It implements the :meth:`__fspath__`
+   Simple :term:`path-like object`.  It implements the
+   :meth:`~os.PathLike.__fspath__`
    method which just returns the *path* argument.  If *path* is an exception,
    it will be raised in :meth:`!__fspath__`.
 

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 175ab0fb237dac14211b8b85fa90950eadc09b74..27adfd9ae01095ae8ec2a29c124bd93eaeba603e 100644 (file)
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -820,8 +820,9 @@ apply to method calls on the mock object.
 
 .. class:: PropertyMock(*args, **kwargs)
 
-   A mock intended to be used as a property, or other descriptor, on a class.
-   :class:`PropertyMock` provides :meth:`__get__` and :meth:`__set__` methods
+   A mock intended to be used as a :class:`property`, or other
+   :term:`descriptor`, on a class. :class:`PropertyMock` provides
+   :meth:`~object.__get__` and :meth:`~object.__set__` methods
    so you can specify a return value when it is fetched.
 
    Fetching a :class:`PropertyMock` instance from an object calls the mock, with
@@ -1658,8 +1659,9 @@ Keywords can be used in the :func:`patch.dict` call to set values in the diction
 :func:`patch.dict` can be used with dictionary like objects that aren't actually
 dictionaries. At the very minimum they must support item getting, setting,
 deleting and either iteration or membership test. This corresponds to the
-magic methods :meth:`~object.__getitem__`, :meth:`__setitem__`, :meth:`__delitem__` and either
-:meth:`__iter__` or :meth:`__contains__`.
+magic methods :meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
+:meth:`~object.__delitem__` and either :meth:`~container.__iter__` or
+:meth:`~object.__contains__`.
 
     >>> class Container:
     ...     def __init__(self):
@@ -2122,7 +2124,7 @@ For example:
    >>> object() in mock
    False
 
-The two equality methods, :meth:`__eq__` and :meth:`__ne__`, are special.
+The two equality methods, :meth:`!__eq__` and :meth:`!__ne__`, are special.
 They do the default equality comparison on identity, using the
 :attr:`~Mock.side_effect` attribute, unless you change their return value to
 return something else::
@@ -2472,8 +2474,8 @@ mock_open
       *read_data* is now reset on each call to the *mock*.
 
    .. versionchanged:: 3.8
-      Added :meth:`__iter__` to implementation so that iteration (such as in for
-      loops) correctly consumes *read_data*.
+      Added :meth:`~container.__iter__` to implementation so that iteration
+      (such as in for loops) correctly consumes *read_data*.
 
 Using :func:`open` as a context manager is a great way to ensure your file handles
 are closed properly and is becoming common::
@@ -2655,7 +2657,7 @@ able to use autospec. On the other hand it is much better to design your
 objects so that introspection is safe [#]_.
 
 A more serious problem is that it is common for instance attributes to be
-created in the :meth:`__init__` method and not to exist on the class at all.
+created in the :meth:`~object.__init__` method and not to exist on the class at all.
 *autospec* can't know about any dynamically created attributes and restricts
 the api to visible attributes. ::
 
@@ -2696,8 +2698,9 @@ this particular scenario:
     AttributeError: Mock object has no attribute 'a'
 
 Probably the best way of solving the problem is to add class attributes as
-default values for instance members initialised in :meth:`__init__`. Note that if
-you are only setting default attributes in :meth:`__init__` then providing them via
+default values for instance members initialised in :meth:`~object.__init__`.
+Note that if
+you are only setting default attributes in :meth:`!__init__` then providing them via
 class attributes (shared between instances of course) is faster too. e.g.
 
 .. code-block:: python

diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 975381808c5ac723be69ab611c1e90167d1ce7f7..2c84bad2b437c77be9e48534a25bbd9583995272 100644 (file)
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -1725,7 +1725,7 @@ Grouping tests
    .. method:: __iter__()
 
       Tests grouped by a :class:`TestSuite` are always accessed by iteration.
-      Subclasses can lazily provide tests by overriding :meth:`__iter__`. Note
+      Subclasses can lazily provide tests by overriding :meth:`!__iter__`. Note
       that this method may be called several times on a single suite (for
       example when counting tests or comparing for equality) so the tests
       returned by repeated iterations before :meth:`TestSuite.run` must be the
@@ -1736,7 +1736,7 @@ Grouping tests
 
       .. versionchanged:: 3.2
          In earlier versions the :class:`TestSuite` accessed tests directly rather
-         than through iteration, so overriding :meth:`__iter__` wasn't sufficient
+         than through iteration, so overriding :meth:`!__iter__` wasn't sufficient
          for providing tests.
 
       .. versionchanged:: 3.4

diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst
index be9e56b04c1fbf1c81445495b55c6564a62959ee..c2b0ba7046967edce2f6bb8f0c5f76a5dae8f859 100644 (file)
--- a/Doc/library/wsgiref.rst
+++ b/Doc/library/wsgiref.rst
@@ -201,8 +201,9 @@ manipulation of WSGI response headers using a mapping-like interface.
    an empty list.
 
    :class:`Headers` objects support typical mapping operations including
-   :meth:`~object.__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`,
-   :meth:`__delitem__` and :meth:`__contains__`.  For each of
+   :meth:`~object.__getitem__`, :meth:`~dict.get`, :meth:`~object.__setitem__`,
+   :meth:`~dict.setdefault`,
+   :meth:`~object.__delitem__` and :meth:`~object.__contains__`.  For each of
    these methods, the key is the header name (treated case-insensitively), and the
    value is the first value associated with that header name.  Setting a header
    deletes any existing values for that header, then adds a new value at the end of
@@ -520,8 +521,10 @@ input, output, and error streams.
    want to subclass this instead of :class:`BaseCGIHandler`.
 
    This class is a subclass of :class:`BaseHandler`.  It overrides the
-   :meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`,
-   :meth:`_write`, and :meth:`_flush` methods to support explicitly setting the
+   :meth:`!__init__`, :meth:`~BaseHandler.get_stdin`,
+   :meth:`~BaseHandler.get_stderr`, :meth:`~BaseHandler.add_cgi_vars`,
+   :meth:`~BaseHandler._write`, and :meth:`~BaseHandler._flush` methods to
+   support explicitly setting the
    environment and streams via the constructor.  The supplied environment and
    streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and
    :attr:`environ` attributes.

diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst
index 146c4fd768233bb089b18780d8515434ccfb322f..f7f23007fb0522b53d5a0ff3998f407975aa7096 100644 (file)
--- a/Doc/library/xmlrpc.client.rst
+++ b/Doc/library/xmlrpc.client.rst
@@ -269,8 +269,9 @@ DateTime Objects
       Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream
       object.
 
-   It also supports certain of Python's built-in operators through rich comparison
-   and :meth:`__repr__` methods.
+   It also supports certain of Python's built-in operators through
+   :meth:`rich comparison <object.__lt__>` and :meth:`~object.__repr__`
+   methods.
 
 A working example follows. The server code::
 
@@ -334,8 +335,8 @@ Binary Objects
       which was the de facto standard base64 specification when the
       XML-RPC spec was written.
 
-   It also supports certain of Python's built-in operators through :meth:`__eq__`
-   and :meth:`__ne__` methods.
+   It also supports certain of Python's built-in operators through
+   :meth:`~object.__eq__` and :meth:`~object.__ne__` methods.
 
 Example usage of the binary objects.  We're going to transfer an image over
 XMLRPC::