[3.13] gh-101100: Fix some Sphinx reference warnings in whatsnew/2.6.rst (GH-139236) (#139569)

gh-101100: Fix some Sphinx reference warnings in ``whatsnew/2.6.rst`` (GH-139236)
(cherry picked from commit 04a2f80)

Co-authored-by: rowanbudge <[email protected]>
Co-authored-by: rowanvil <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

Author: 4 people

Doc/whatsnew/2.6.rst

@@ -56,7 +56,7 @@ Python 2.6 incorporates new features and syntax from 3.0 while
 remaining compatible with existing code by not removing older features
 or syntax.  When it's not possible to do that, Python 2.6 tries to do
 what it can, adding compatibility functions in a
-:mod:`future_builtins` module and a :option:`!-3` switch to warn about
+:mod:`!future_builtins` module and a :option:`!-3` switch to warn about
 usages that will become unsupported in 3.0.
 
 Some significant new packages have been added to the standard library,
@@ -109,7 +109,7 @@ are:
 Python 3.0 adds several new built-in functions and changes the
 semantics of some existing builtins.  Functions that are new in 3.0
 such as :func:`bin` have simply been added to Python 2.6, but existing
-builtins haven't been changed; instead, the :mod:`future_builtins`
+builtins haven't been changed; instead, the :mod:`!future_builtins`
 module has versions with the new 3.0 semantics.  Code written to be
 compatible with 3.0 can do ``from future_builtins import hex, map`` as
 necessary.
@@ -118,7 +118,7 @@ A new command-line switch, :option:`!-3`, enables warnings
 about features that will be removed in Python 3.0.  You can run code
 with this switch to see how much work will be necessary to port
 code to 3.0.  The value of this switch is available
-to Python code as the boolean variable :data:`sys.py3kwarning`,
+to Python code as the boolean variable :data:`!sys.py3kwarning`,
 and to C extension code as :c:data:`!Py_Py3kWarningFlag`.
 
 .. seealso::
@@ -307,9 +307,9 @@ The :mod:`threading` module's locks and condition variables  also support the
 The lock is acquired before the block is executed and always released once  the
 block is complete.
 
-The :func:`localcontext` function in the :mod:`decimal` module makes it easy
-to save and restore the current decimal context, which encapsulates the desired
-precision and rounding characteristics for computations::
+The :func:`~decimal.localcontext` function in the :mod:`decimal` module makes
+it easy to save and restore the current decimal context, which encapsulates
+the desired precision and rounding characteristics for computations::
 
    from decimal import Decimal, Context, localcontext
 
@@ -337,12 +337,12 @@ underlying implementation and should keep reading.
 A high-level explanation of the context management protocol is:
 
 * The expression is evaluated and should result in an object called a "context
-  manager".  The context manager must have :meth:`~object.__enter__` and :meth:`~object.__exit__`
-  methods.
+  manager".  The context manager must have :meth:`~object.__enter__` and
+  :meth:`~object.__exit__` methods.
 
-* The context manager's :meth:`~object.__enter__` method is called.  The value returned
-  is assigned to *VAR*.  If no ``as VAR`` clause is present, the value is simply
-  discarded.
+* The context manager's :meth:`~object.__enter__` method is called.  The value
+  returned is assigned to *VAR*.  If no ``as VAR`` clause is present, the
+  value is simply discarded.
 
 * The code in *BLOCK* is executed.
 
@@ -378,7 +378,7 @@ be to let the user write code like this::
 
 The transaction should be committed if the code in the block runs flawlessly or
 rolled back if there's an exception. Here's the basic interface for
-:class:`DatabaseConnection` that I'll assume::
+:class:`!DatabaseConnection` that I'll assume::
 
    class DatabaseConnection:
        # Database interface
@@ -431,14 +431,15 @@ The contextlib module
 The :mod:`contextlib` module provides some functions and a decorator that
 are useful when writing objects for use with the ':keyword:`with`' statement.
 
-The decorator is called :func:`contextmanager`, and lets you write a single
-generator function instead of defining a new class.  The generator should yield
-exactly one value.  The code up to the :keyword:`yield` will be executed as the
-:meth:`~object.__enter__` method, and the value yielded will be the method's return
-value that will get bound to the variable in the ':keyword:`with`' statement's
-:keyword:`!as` clause, if any.  The code after the :keyword:`!yield` will be
-executed in the :meth:`~object.__exit__` method.  Any exception raised in the block will
-be raised by the :keyword:`!yield` statement.
+The decorator is called :func:`~contextlib.contextmanager`, and lets you write
+a single generator function instead of defining a new class.  The generator
+should yield exactly one value.  The code up to the :keyword:`yield` will be
+executed as the :meth:`~object.__enter__` method, and the value yielded will
+be the method's return value that will get bound to the variable in the
+':keyword:`with`' statement's :keyword:`!as` clause, if any.  The code after
+the :keyword:`!yield` will be executed in the :meth:`~object.__exit__` method.
+Any exception raised in the block will be raised by the :keyword:`!yield`
+statement.
 
 Using this decorator, our database example from the previous section
 could be written as::
@@ -469,7 +470,7 @@ statement both starts a database transaction and acquires a thread lock::
    with nested (db_transaction(db), lock) as (cursor, locked):
        ...
 
-Finally, the :func:`closing` function returns its argument so that it can be
+Finally, the :func:`~contextlib.closing` function returns its argument so that it can be
 bound to a variable, and calls the argument's ``.close()`` method at the end
 of the block. ::
 
@@ -538,7 +539,7 @@ If you don't like the default directory, it can be overridden by an
 environment variable.  :envvar:`PYTHONUSERBASE` sets the root
 directory used for all Python versions supporting this feature.  On
 Windows, the directory for application-specific data can be changed by
-setting the :envvar:`APPDATA` environment variable.  You can also
+setting the :envvar:`!APPDATA` environment variable.  You can also
 modify the :file:`site.py` file for your Python installation.
 
 The feature can be disabled entirely by running Python with the
@@ -568,11 +569,12 @@ The :mod:`multiprocessing` module started out as an exact emulation of
 the :mod:`threading` module using processes instead of threads.  That
 goal was discarded along the path to Python 2.6, but the general
 approach of the module is still similar.  The fundamental class
-is the :class:`Process`, which is passed a callable object and
-a collection of arguments.  The :meth:`start` method
+is the :class:`~multiprocessing.Process`, which is passed a callable object and
+a collection of arguments.  The :meth:`~multiprocessing.Process.start` method
 sets the callable running in a subprocess, after which you can call
-the :meth:`is_alive` method to check whether the subprocess is still running
-and the :meth:`join` method to wait for the process to exit.
+the :meth:`~multiprocessing.Process.is_alive` method to check whether the
+subprocess is still running and the :meth:`~multiprocessing.Process.join`
+method to wait for the process to exit.
 
 Here's a simple example where the subprocess will calculate a
 factorial.  The function doing the calculation is written strangely so
@@ -619,13 +621,16 @@ the object to communicate.  (If the parent were to change the value of
 the global variable, the child's value would be unaffected, and vice
 versa.)
 
-Two other classes, :class:`Pool` and :class:`Manager`, provide
-higher-level interfaces.  :class:`Pool` will create a fixed number of
-worker processes, and requests can then be distributed to the workers
-by calling :meth:`apply` or :meth:`apply_async` to add a single request,
-and :meth:`map` or :meth:`map_async` to add a number of
-requests.  The following code uses a :class:`Pool` to spread requests
-across 5 worker processes and retrieve a list of results::
+Two other classes, :class:`~multiprocessing.pool.Pool` and
+:class:`~multiprocessing.Manager`, provide higher-level interfaces.
+:class:`~multiprocessing.pool.Pool` will create a fixed number of worker
+processes, and requests can then be distributed to the workers by calling
+:meth:`~multiprocessing.pool.Pool.apply` or
+:meth:`~multiprocessing.pool.Pool.apply_async` to add a single request, and
+:meth:`~multiprocessing.pool.Pool.map` or
+:meth:`~multiprocessing.pool.Pool.map_async` to add a number of
+requests.  The following code uses a :class:`~multiprocessing.pool.Pool` to
+spread requests across 5 worker processes and retrieve a list of results::
 
     from multiprocessing import Pool
 
@@ -646,15 +651,18 @@ This produces the following output::
     33452526613163807108170062053440751665152000000000
     ...
 
-The other high-level interface, the :class:`Manager` class, creates a
-separate server process that can hold master copies of Python data
+The other high-level interface, the :class:`~multiprocessing.Manager` class,
+creates a separate server process that can hold master copies of Python data
 structures.  Other processes can then access and modify these data
 structures using proxy objects.  The following example creates a
 shared dictionary by calling the :meth:`dict` method; the worker
 processes then insert values into the dictionary.  (Locking is not
 done for you automatically, which doesn't matter in this example.
-:class:`Manager`'s methods also include :meth:`Lock`, :meth:`RLock`,
-and :meth:`Semaphore` to create shared locks.)
+:class:`~multiprocessing.Manager`'s methods also include
+:meth:`~multiprocessing.managers.SyncManager.Lock`,
+:meth:`~multiprocessing.managers.SyncManager.RLock`,
+and :meth:`~multiprocessing.managers.SyncManager.Semaphore` to create
+shared locks.)
 
 ::
 
@@ -824,7 +832,7 @@ documentation for a :ref:`complete list <formatstrings>`; here's a sample:
       format, followed by a percent sign.
 ===== ========================================================================
 
-Classes and types can define a :meth:`__format__` method to control how they're
+Classes and types can define a :meth:`~object.__format__` method to control how they're
 formatted.  It receives a single argument, the format specifier::
 
    def __format__(self, format_spec):
@@ -834,7 +842,7 @@ formatted.  It receives a single argument, the format specifier::
            return str(self)
 
 There's also a :func:`format` builtin that will format a single
-value.  It calls the type's :meth:`__format__` method with the
+value.  It calls the type's :meth:`~object.__format__` method with the
 provided specifier::
 
     >>> format(75.6564, '.2f')
@@ -1029,56 +1037,58 @@ PEP 3116: New I/O Library
 
 Python's built-in file objects support a number of methods, but
 file-like objects don't necessarily support all of them.  Objects that
-imitate files usually support :meth:`read` and :meth:`write`, but they
-may not support :meth:`readline`, for example.  Python 3.0 introduces
-a layered I/O library in the :mod:`io` module that separates buffering
-and text-handling features from the fundamental read and write
-operations.
+imitate files usually support :meth:`!read` and
+:meth:`!write`, but they may not support :meth:`!readline`,
+for example.  Python 3.0 introduces a layered I/O library in the :mod:`io`
+module that separates buffering and text-handling features from the
+fundamental read and write operations.
 
 There are three levels of abstract base classes provided by
 the :mod:`io` module:
 
-* :class:`RawIOBase` defines raw I/O operations: :meth:`read`,
-  :meth:`readinto`,
-  :meth:`write`, :meth:`seek`, :meth:`tell`, :meth:`truncate`,
-  and :meth:`close`.
+* :class:`~io.RawIOBase` defines raw I/O operations: :meth:`~io.RawIOBase.read`,
+  :meth:`~io.RawIOBase.readinto`, :meth:`~io.RawIOBase.write`,
+  :meth:`~io.IOBase.seek`, :meth:`~io.IOBase.tell`, :meth:`~io.IOBase.truncate`,
+  and :meth:`~io.IOBase.close`.
   Most of the methods of this class will often map to a single system call.
-  There are also :meth:`readable`, :meth:`writable`, and :meth:`seekable`
-  methods for determining what operations a given object will allow.
+  There are also :meth:`~io.IOBase.readable`, :meth:`~io.IOBase.writable`,
+  and :meth:`~io.IOBase.seekable` methods for determining what operations a
+  given object will allow.
 
   Python 3.0 has concrete implementations of this class for files and
   sockets, but Python 2.6 hasn't restructured its file and socket objects
   in this way.
 
-* :class:`BufferedIOBase` is an abstract base class that
+* :class:`~io.BufferedIOBase` is an abstract base class that
   buffers data in memory to reduce the number of
   system calls used, making I/O processing more efficient.
-  It supports all of the methods of :class:`RawIOBase`,
-  and adds a :attr:`raw` attribute holding the underlying raw object.
+  It supports all of the methods of :class:`~io.RawIOBase`,
+  and adds a :attr:`~io.BufferedIOBase.raw` attribute holding the underlying
+  raw object.
 
   There are five concrete classes implementing this ABC.
-  :class:`BufferedWriter` and :class:`BufferedReader` are for objects
-  that support write-only or read-only usage that have a :meth:`seek`
-  method for random access.  :class:`BufferedRandom` objects support
+  :class:`~io.BufferedWriter` and :class:`~io.BufferedReader` are for objects
+  that support write-only or read-only usage that have a :meth:`~io.IOBase.seek`
+  method for random access.  :class:`~io.BufferedRandom` objects support
   read and write access upon the same underlying stream, and
-  :class:`BufferedRWPair` is for objects such as TTYs that have both
+  :class:`~io.BufferedRWPair` is for objects such as TTYs that have both
   read and write operations acting upon unconnected streams of data.
-  The :class:`BytesIO` class supports reading, writing, and seeking
+  The :class:`~io.BytesIO` class supports reading, writing, and seeking
   over an in-memory buffer.
 
   .. index::
      single: universal newlines; What's new
 
-* :class:`TextIOBase`: Provides functions for reading and writing
+* :class:`~io.TextIOBase`: Provides functions for reading and writing
   strings (remember, strings will be Unicode in Python 3.0),
-  and supporting :term:`universal newlines`.  :class:`TextIOBase` defines
+  and supporting :term:`universal newlines`.  :class:`~io.TextIOBase` defines
   the :meth:`readline` method and supports iteration upon
   objects.
 
-  There are two concrete implementations.  :class:`TextIOWrapper`
+  There are two concrete implementations.  :class:`~io.TextIOWrapper`
   wraps a buffered I/O object, supporting all of the methods for
-  text I/O and adding a :attr:`buffer` attribute for access
-  to the underlying object.  :class:`StringIO` simply buffers
+  text I/O and adding a :attr:`~io.TextIOBase.buffer` attribute for access
+  to the underlying object.  :class:`~io.StringIO` simply buffers
   everything in memory without ever writing anything to disk.
 
   (In Python 2.6, :class:`io.StringIO` is implemented in
@@ -1162,7 +1172,7 @@ Some object-oriented languages such as Java support interfaces,
 declaring that a class has a given set of methods or supports a given
 access protocol.  Abstract Base Classes (or ABCs) are an equivalent
 feature for Python. The ABC support consists of an :mod:`abc` module
-containing a metaclass called :class:`ABCMeta`, special handling of
+containing a metaclass called :class:`~abc.ABCMeta`, special handling of
 this metaclass by the :func:`isinstance` and :func:`issubclass`
 builtins, and a collection of basic ABCs that the Python developers
 think will be widely useful.  Future versions of Python will probably
@@ -1172,17 +1182,17 @@ Let's say you have a particular class and wish to know whether it supports
 dictionary-style access.  The phrase "dictionary-style" is vague, however.
 It probably means that accessing items with ``obj[1]`` works.
 Does it imply that setting items with ``obj[2] = value`` works?
-Or that the object will have :meth:`keys`, :meth:`values`, and :meth:`items`
-methods?  What about the iterative variants  such as :meth:`iterkeys`?  :meth:`copy`
-and :meth:`update`?  Iterating over the object with :func:`iter`?
+Or that the object will have :meth:`!keys`, :meth:`!values`, and :meth:`!items`
+methods?  What about the iterative variants  such as :meth:`!iterkeys`?
+:meth:`!copy`and :meth:`!update`?  Iterating over the object with :func:`!iter`?
 
 The Python 2.6 :mod:`collections` module includes a number of
 different ABCs that represent these distinctions.  :class:`Iterable`
-indicates that a class defines :meth:`__iter__`, and
-:class:`Container` means the class defines a :meth:`__contains__`
+indicates that a class defines :meth:`~object.__iter__`, and
+:class:`Container` means the class defines a :meth:`~object.__contains__`
 method and therefore supports ``x in y`` expressions.  The basic
 dictionary interface of getting items, setting items, and
-:meth:`keys`, :meth:`values`, and :meth:`items`, is defined by the
+:meth:`!keys`, :meth:`!values`, and :meth:`!items`, is defined by the
 :class:`MutableMapping` ABC.
 
 You can derive your own classes from a particular ABC
@@ -1196,7 +1206,7 @@ to indicate they support that ABC's interface::
 
 Alternatively, you could write the class without deriving from
 the desired ABC and instead register the class by
-calling the ABC's :meth:`register` method::
+calling the ABC's :meth:`~abc.ABCMeta.register` method::
 
     import collections
 
@@ -1206,10 +1216,10 @@ calling the ABC's :meth:`register` method::
     collections.MutableMapping.register(Storage)
 
 For classes that you write, deriving from the ABC is probably clearer.
-The :meth:`register`  method is useful when you've written a new
+The :meth:`~abc.ABCMeta.register`  method is useful when you've written a new
 ABC that can describe an existing type or class, or if you want
 to declare that some third-party class implements an ABC.
-For example, if you defined a :class:`PrintableType` ABC,
+For example, if you defined a :class:`!PrintableType` ABC,
 it's legal to do::
 
   # Register Python's types
@@ -1256,16 +1266,16 @@ metaclass in a class definition::
             ...
 
 
-In the :class:`Drawable` ABC above, the :meth:`draw_doubled` method
+In the :class:`!Drawable` ABC above, the :meth:`!draw_doubled` method
 renders the object at twice its size and can be implemented in terms
-of other methods described in :class:`Drawable`.  Classes implementing
+of other methods described in :class:`!Drawable`.  Classes implementing
 this ABC therefore don't need to provide their own implementation
-of :meth:`draw_doubled`, though they can do so.  An implementation
-of :meth:`draw` is necessary, though; the ABC can't provide
+of :meth:`!draw_doubled`, though they can do so.  An implementation
+of :meth:`!draw` is necessary, though; the ABC can't provide
 a useful generic implementation.
 
-You can apply the ``@abstractmethod`` decorator to methods such as
-:meth:`draw` that must be implemented; Python will then raise an
+You can apply the :deco:`~abc.abstractmethod` decorator to methods such as
+:meth:`!draw` that must be implemented; Python will then raise an
 exception for classes that don't define the method.
 Note that the exception is only raised when you actually
 try to create an instance of a subclass lacking the method::
@@ -1289,7 +1299,7 @@ Abstract data attributes can be declared using the
     def readonly(self):
        return self._x
 
-Subclasses must then define a :meth:`readonly` property.
+Subclasses must then define a ``readonly`` property.
 
 .. seealso::
 
@@ -2739,13 +2749,13 @@ numbers.
 
 .. ======================================================================
 
-The :mod:`future_builtins` module
+The :mod:`!future_builtins` module
 --------------------------------------
 
 Python 3.0 makes many changes to the repertoire of built-in
 functions, and most of the changes can't be introduced in the Python
 2.x series because they would break compatibility.
-The :mod:`future_builtins` module provides versions
+The :mod:`!future_builtins` module provides versions
 of these built-in functions that can be imported when writing
 3.0-compatible code.