greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

gh-101100: Fix some Sphinx reference warnings in `whatsnew/2.6.rst` (#139236)

Browse Source 
Co-authored-by: rowanvil <rowan@anvil.works>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
rowanbudge
2025-10-04 16:59:39 +01:00
committed by GitHub
parent f191db2e0e
commit 04a2f80a60
1 changed files with 92 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
Doc/whatsnew/2.6.rst
View File

@@ -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.