mirror of https://github.com/python/cpython
gh-101100: Fix Sphinx warnings in `whatsnew/2.1.rst` (#112357)
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
This commit is contained in:
parent
de0b4f95cb
commit
8e8ab75d97
|
@ -78,7 +78,6 @@ Doc/reference/compound_stmts.rst
|
|||
Doc/reference/datamodel.rst
|
||||
Doc/tutorial/datastructures.rst
|
||||
Doc/using/windows.rst
|
||||
Doc/whatsnew/2.1.rst
|
||||
Doc/whatsnew/2.4.rst
|
||||
Doc/whatsnew/2.5.rst
|
||||
Doc/whatsnew/2.6.rst
|
||||
|
|
|
@ -48,7 +48,7 @@ nested recursive function definition doesn't work::
|
|||
return g(value-1) + 1
|
||||
...
|
||||
|
||||
The function :func:`g` will always raise a :exc:`NameError` exception, because
|
||||
The function :func:`!g` will always raise a :exc:`NameError` exception, because
|
||||
the binding of the name ``g`` isn't in either its local namespace or in the
|
||||
module-level namespace. This isn't much of a problem in practice (how often do
|
||||
you recursively define interior functions like this?), but this also made using
|
||||
|
@ -104,7 +104,7 @@ To make the preceding explanation a bit clearer, here's an example::
|
|||
|
||||
Line 4 containing the ``exec`` statement is a syntax error, since
|
||||
``exec`` would define a new local variable named ``x`` whose value should
|
||||
be accessed by :func:`g`.
|
||||
be accessed by :func:`!g`.
|
||||
|
||||
This shouldn't be much of a limitation, since ``exec`` is rarely used in
|
||||
most Python code (and when it is used, it's often a sign of a poor design
|
||||
|
@ -161,7 +161,7 @@ PEP 207: Rich Comparisons
|
|||
|
||||
In earlier versions, Python's support for implementing comparisons on user-defined
|
||||
classes and extension types was quite simple. Classes could implement a
|
||||
:meth:`__cmp__` method that was given two instances of a class, and could only
|
||||
:meth:`!__cmp__` method that was given two instances of a class, and could only
|
||||
return 0 if they were equal or +1 or -1 if they weren't; the method couldn't
|
||||
raise an exception or return anything other than a Boolean value. Users of
|
||||
Numeric Python often found this model too weak and restrictive, because in the
|
||||
|
@ -175,21 +175,21 @@ In Python 2.1, rich comparisons were added in order to support this need.
|
|||
Python classes can now individually overload each of the ``<``, ``<=``, ``>``,
|
||||
``>=``, ``==``, and ``!=`` operations. The new magic method names are:
|
||||
|
||||
+-----------+----------------+
|
||||
| Operation | Method name |
|
||||
+===========+================+
|
||||
| ``<`` | :meth:`__lt__` |
|
||||
+-----------+----------------+
|
||||
| ``<=`` | :meth:`__le__` |
|
||||
+-----------+----------------+
|
||||
| ``>`` | :meth:`__gt__` |
|
||||
+-----------+----------------+
|
||||
| ``>=`` | :meth:`__ge__` |
|
||||
+-----------+----------------+
|
||||
| ``==`` | :meth:`__eq__` |
|
||||
+-----------+----------------+
|
||||
| ``!=`` | :meth:`__ne__` |
|
||||
+-----------+----------------+
|
||||
+-----------+------------------------+
|
||||
| Operation | Method name |
|
||||
+===========+========================+
|
||||
| ``<`` | :meth:`~object.__lt__` |
|
||||
+-----------+------------------------+
|
||||
| ``<=`` | :meth:`~object.__le__` |
|
||||
+-----------+------------------------+
|
||||
| ``>`` | :meth:`~object.__gt__` |
|
||||
+-----------+------------------------+
|
||||
| ``>=`` | :meth:`~object.__ge__` |
|
||||
+-----------+------------------------+
|
||||
| ``==`` | :meth:`~object.__eq__` |
|
||||
+-----------+------------------------+
|
||||
| ``!=`` | :meth:`~object.__ne__` |
|
||||
+-----------+------------------------+
|
||||
|
||||
(The magic methods are named after the corresponding Fortran operators ``.LT.``.
|
||||
``.LE.``, &c. Numeric programmers are almost certainly quite familiar with
|
||||
|
@ -208,7 +208,7 @@ The built-in ``cmp(A,B)`` function can use the rich comparison machinery,
|
|||
and now accepts an optional argument specifying which comparison operation to
|
||||
use; this is given as one of the strings ``"<"``, ``"<="``, ``">"``, ``">="``,
|
||||
``"=="``, or ``"!="``. If called without the optional third argument,
|
||||
:func:`cmp` will only return -1, 0, or +1 as in previous versions of Python;
|
||||
:func:`!cmp` will only return -1, 0, or +1 as in previous versions of Python;
|
||||
otherwise it will call the appropriate method and can return any Python object.
|
||||
|
||||
There are also corresponding changes of interest to C programmers; there's a new
|
||||
|
@ -245,7 +245,7 @@ out warnings that you don't want to be displayed. Third-party modules can also
|
|||
use this framework to deprecate old features that they no longer wish to
|
||||
support.
|
||||
|
||||
For example, in Python 2.1 the :mod:`regex` module is deprecated, so importing
|
||||
For example, in Python 2.1 the :mod:`!regex` module is deprecated, so importing
|
||||
it causes a warning to be printed::
|
||||
|
||||
>>> import regex
|
||||
|
@ -262,7 +262,7 @@ can be used to specify a particular warning category.
|
|||
|
||||
Filters can be added to disable certain warnings; a regular expression pattern
|
||||
can be applied to the message or to the module name in order to suppress a
|
||||
warning. For example, you may have a program that uses the :mod:`regex` module
|
||||
warning. For example, you may have a program that uses the :mod:`!regex` module
|
||||
and not want to spare the time to convert it to use the :mod:`re` module right
|
||||
now. The warning can be suppressed by calling ::
|
||||
|
||||
|
@ -274,7 +274,7 @@ now. The warning can be suppressed by calling ::
|
|||
|
||||
This adds a filter that will apply only to warnings of the class
|
||||
:class:`DeprecationWarning` triggered in the :mod:`__main__` module, and applies
|
||||
a regular expression to only match the message about the :mod:`regex` module
|
||||
a regular expression to only match the message about the :mod:`!regex` module
|
||||
being deprecated, and will cause such warnings to be ignored. Warnings can also
|
||||
be printed only once, printed every time the offending code is executed, or
|
||||
turned into exceptions that will cause the program to stop (unless the
|
||||
|
@ -368,7 +368,7 @@ dictionary::
|
|||
This version works for simple things such as integers, but it has a side effect;
|
||||
the ``_cache`` dictionary holds a reference to the return values, so they'll
|
||||
never be deallocated until the Python process exits and cleans up. This isn't
|
||||
very noticeable for integers, but if :func:`f` returns an object, or a data
|
||||
very noticeable for integers, but if :func:`!f` returns an object, or a data
|
||||
structure that takes up a lot of memory, this can be a problem.
|
||||
|
||||
Weak references provide a way to implement a cache that won't keep objects alive
|
||||
|
@ -379,7 +379,7 @@ created by calling ``wr = weakref.ref(obj)``. The object being referred to is
|
|||
returned by calling the weak reference as if it were a function: ``wr()``. It
|
||||
will return the referenced object, or ``None`` if the object no longer exists.
|
||||
|
||||
This makes it possible to write a :func:`memoize` function whose cache doesn't
|
||||
This makes it possible to write a :func:`!memoize` function whose cache doesn't
|
||||
keep objects alive, by storing weak references in the cache. ::
|
||||
|
||||
_cache = {}
|
||||
|
@ -402,7 +402,7 @@ weak references --- an object referenced only by proxy objects is deallocated --
|
|||
but instead of requiring an explicit call to retrieve the object, the proxy
|
||||
transparently forwards all operations to the object as long as the object still
|
||||
exists. If the object is deallocated, attempting to use a proxy will cause a
|
||||
:exc:`weakref.ReferenceError` exception to be raised. ::
|
||||
:exc:`!weakref.ReferenceError` exception to be raised. ::
|
||||
|
||||
proxy = weakref.proxy(obj)
|
||||
proxy.attr # Equivalent to obj.attr
|
||||
|
@ -446,7 +446,7 @@ The dictionary containing attributes can be accessed as the function's
|
|||
:attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in
|
||||
functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though
|
||||
the new value is restricted to a regular Python dictionary; you *can't* be
|
||||
tricky and set it to a :class:`UserDict` instance, or any other random object
|
||||
tricky and set it to a :class:`!UserDict` instance, or any other random object
|
||||
that behaves like a mapping.
|
||||
|
||||
|
||||
|
@ -584,11 +584,11 @@ available from the Distutils SIG at https://www.python.org/community/sigs/curren
|
|||
New and Improved Modules
|
||||
========================
|
||||
|
||||
* Ka-Ping Yee contributed two new modules: :mod:`inspect.py`, a module for
|
||||
getting information about live Python code, and :mod:`pydoc.py`, a module for
|
||||
* Ka-Ping Yee contributed two new modules: :mod:`!inspect.py`, a module for
|
||||
getting information about live Python code, and :mod:`!pydoc.py`, a module for
|
||||
interactively converting docstrings to HTML or text. As a bonus,
|
||||
:file:`Tools/scripts/pydoc`, which is now automatically installed, uses
|
||||
:mod:`pydoc.py` to display documentation given a Python module, package, or
|
||||
:mod:`!pydoc.py` to display documentation given a Python module, package, or
|
||||
class name. For example, ``pydoc xml.dom`` displays the following::
|
||||
|
||||
Python Library Documentation: package xml.dom in xml
|
||||
|
@ -617,7 +617,7 @@ New and Improved Modules
|
|||
Kent Beck's Smalltalk testing framework. See https://pyunit.sourceforge.net/ for
|
||||
more information about PyUnit.
|
||||
|
||||
* The :mod:`difflib` module contains a class, :class:`SequenceMatcher`, which
|
||||
* The :mod:`difflib` module contains a class, :class:`~difflib.SequenceMatcher`, which
|
||||
compares two sequences and computes the changes required to transform one
|
||||
sequence into the other. For example, this module can be used to write a tool
|
||||
similar to the Unix :program:`diff` program, and in fact the sample program
|
||||
|
@ -633,7 +633,7 @@ New and Improved Modules
|
|||
2.1 includes an updated version of the :mod:`xml` package. Some of the
|
||||
noteworthy changes include support for Expat 1.2 and later versions, the ability
|
||||
for Expat parsers to handle files in any encoding supported by Python, and
|
||||
various bugfixes for SAX, DOM, and the :mod:`minidom` module.
|
||||
various bugfixes for SAX, DOM, and the :mod:`!minidom` module.
|
||||
|
||||
* Ping also contributed another hook for handling uncaught exceptions.
|
||||
:func:`sys.excepthook` can be set to a callable object. When an exception isn't
|
||||
|
@ -643,8 +643,8 @@ New and Improved Modules
|
|||
printing an extended traceback that not only lists the stack frames, but also
|
||||
lists the function arguments and the local variables for each frame.
|
||||
|
||||
* Various functions in the :mod:`time` module, such as :func:`asctime` and
|
||||
:func:`localtime`, require a floating point argument containing the time in
|
||||
* Various functions in the :mod:`time` module, such as :func:`~time.asctime` and
|
||||
:func:`~time.localtime`, require a floating point argument containing the time in
|
||||
seconds since the epoch. The most common use of these functions is to work with
|
||||
the current time, so the floating point argument has been made optional; when a
|
||||
value isn't provided, the current time will be used. For example, log file
|
||||
|
@ -724,10 +724,10 @@ of the more notable changes are:
|
|||
a discussion in comp.lang.python.
|
||||
|
||||
A new module and method for file objects was also added, contributed by Jeff
|
||||
Epler. The new method, :meth:`xreadlines`, is similar to the existing
|
||||
:func:`xrange` built-in. :func:`xreadlines` returns an opaque sequence object
|
||||
Epler. The new method, :meth:`!xreadlines`, is similar to the existing
|
||||
:func:`!xrange` built-in. :func:`!xreadlines` returns an opaque sequence object
|
||||
that only supports being iterated over, reading a line on every iteration but
|
||||
not reading the entire file into memory as the existing :meth:`readlines` method
|
||||
not reading the entire file into memory as the existing :meth:`!readlines` method
|
||||
does. You'd use it like this::
|
||||
|
||||
for line in sys.stdin.xreadlines():
|
||||
|
@ -737,7 +737,7 @@ of the more notable changes are:
|
|||
For a fuller discussion of the line I/O changes, see the python-dev summary for
|
||||
January 1--15, 2001 at https://mail.python.org/pipermail/python-dev/2001-January/.
|
||||
|
||||
* A new method, :meth:`popitem`, was added to dictionaries to enable
|
||||
* A new method, :meth:`~dict.popitem`, was added to dictionaries to enable
|
||||
destructively iterating through the contents of a dictionary; this can be faster
|
||||
for large dictionaries because there's no need to construct a list containing
|
||||
all the keys or values. ``D.popitem()`` removes a random ``(key, value)`` pair
|
||||
|
|
Loading…
Reference in New Issue