Merge branch 'main' into gh-11599-docs

Author: corona10

Doc/glossary.rst

@@ -800,6 +800,10 @@ Glossary
       thread removes *key* from *mapping* after the test, but before the lookup.
       This issue can be solved with locks or by using the EAFP approach.
 
+   lexical analyzer
+
+      Formal name for the *tokenizer*; see :term:`token`.
+
    list
       A built-in Python :term:`sequence`.  Despite its name it is more akin
       to an array in other languages than to a linked list since access to
@@ -1291,6 +1295,17 @@ Glossary
       See also :term:`binary file` for a file object able to read and write
       :term:`bytes-like objects <bytes-like object>`.
 
+   token
+
+      A small unit of source code, generated by the
+      :ref:`lexical analyzer <lexical>` (also called the *tokenizer*).
+      Names, numbers, strings, operators,
+      newlines and similar are represented by tokens.
+
+      The :mod:`tokenize` module exposes Python's lexical analyzer.
+      The :mod:`token` module contains information on the various types
+      of tokens.
+
    triple-quoted string
       A string which is bound by three instances of either a quotation mark
       (") or an apostrophe (').  While they don't provide any functionality

Doc/library/bdb.rst

@@ -118,7 +118,7 @@ The :mod:`bdb` module also defines two classes:
 
       Count of the number of times a :class:`Breakpoint` has been hit.
 
-.. class:: Bdb(skip=None)
+.. class:: Bdb(skip=None, backend='settrace')
 
    The :class:`Bdb` class acts as a generic Python debugger base class.
 
@@ -132,9 +132,22 @@ The :mod:`bdb` module also defines two classes:
    frame is considered to originate in a certain module is determined
    by the ``__name__`` in the frame globals.
 
+   The *backend* argument specifies the backend to use for :class:`Bdb`. It
+   can be either ``'settrace'`` or ``'monitoring'``. ``'settrace'`` uses
+   :func:`sys.settrace` which has the best backward compatibility. The
+   ``'monitoring'`` backend uses the new :mod:`sys.monitoring` that was
+   introduced in Python 3.12, which can be much more efficient because it
+   can disable unused events. We are trying to keep the exact interfaces
+   for both backends, but there are some differences. The debugger developers
+   are encouraged to use the ``'monitoring'`` backend to achieve better
+   performance.
+
    .. versionchanged:: 3.1
       Added the *skip* parameter.
 
+   .. versionchanged:: 3.14
+      Added the *backend* parameter.
+
    The following methods of :class:`Bdb` normally don't need to be overridden.
 
    .. method:: canonic(filename)
@@ -146,6 +159,20 @@ The :mod:`bdb` module also defines two classes:
       <os.path.abspath>`. A *filename* with angle brackets, such as ``"<stdin>"``
       generated in interactive mode, is returned unchanged.
 
+   .. method:: start_trace(self)
+
+      Start tracing. For ``'settrace'`` backend, this method is equivalent to
+      ``sys.settrace(self.trace_dispatch)``
+
+      .. versionadded:: 3.14
+
+   .. method:: stop_trace(self)
+
+      Stop tracing. For ``'settrace'`` backend, this method is equivalent to
+      ``sys.settrace(None)``
+
+      .. versionadded:: 3.14
+
    .. method:: reset()
 
       Set the :attr:`!botframe`, :attr:`!stopframe`, :attr:`!returnframe` and
@@ -364,6 +391,28 @@ The :mod:`bdb` module also defines two classes:
       Return all breakpoints that are set.
 
 
+   Derived classes and clients can call the following methods to disable and
+   restart events to achieve better performance. These methods only work
+   when using the ``'monitoring'`` backend.
+
+   .. method:: disable_current_event()
+
+      Disable the current event until the next time :func:`restart_events` is
+      called. This is helpful when the debugger is not interested in the current
+      line.
+
+      .. versionadded:: 3.14
+
+   .. method:: restart_events()
+
+      Restart all the disabled events. This function is automatically called in
+      ``dispatch_*`` methods after ``user_*`` methods are called. If the
+      ``dispatch_*`` methods are not overridden, the disabled events will be
+      restarted after each user interaction.
+
+      .. versionadded:: 3.14
+
+
    Derived classes and clients can call the following methods to get a data
    structure representing a stack trace.
 

Doc/library/cmdline.rst

@@ -12,7 +12,7 @@ The following modules have a command-line interface.
 * :ref:`compileall <compileall-cli>`
 * :mod:`cProfile`: see :ref:`profile <profile-cli>`
 * :ref:`dis <dis-cli>`
-* :mod:`doctest`
+* :ref:`doctest <doctest-cli>`
 * :mod:`!encodings.rot_13`
 * :mod:`ensurepip`
 * :mod:`filecmp`

Doc/library/dis.rst

@@ -535,7 +535,7 @@ details of bytecode instructions as :class:`Instruction` instances:
       :class:`dis.Positions` object holding the
       start and end locations that are covered by this instruction.
 
-   .. data::cache_info
+   .. data:: cache_info
 
       Information about the cache entries of this instruction, as
       triplets of the form ``(name, size, data)``, where the ``name``

Doc/library/doctest.rst

@@ -177,15 +177,8 @@ prohibit it by passing ``verbose=False``.  In either of those cases,
 ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
 has no effect).
 
-There is also a command line shortcut for running :func:`testmod`.  You can
-instruct the Python interpreter to run the doctest module directly from the
-standard library and pass the module name(s) on the command line::
-
-   python -m doctest -v example.py
-
-This will import :file:`example.py` as a standalone module and run
-:func:`testmod` on it.  Note that this may not work correctly if the file is
-part of a package and imports other submodules from that package.
+There is also a command line shortcut for running :func:`testmod`, see section
+:ref:`doctest-cli`.
 
 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
 
@@ -248,16 +241,53 @@ Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
 ``-v`` command-line switch or with the optional keyword argument
 *verbose*.
 
-There is also a command line shortcut for running :func:`testfile`.  You can
-instruct the Python interpreter to run the doctest module directly from the
-standard library and pass the file name(s) on the command line::
+There is also a command line shortcut for running :func:`testfile`, see section
+:ref:`doctest-cli`.
 
-   python -m doctest -v example.txt
+For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
 
-Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
-it must be run with :func:`testfile`, not :func:`testmod`.
 
-For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
+.. _doctest-cli:
+
+Command-line Usage
+------------------
+
+The :mod:`doctest` module can be invoked as a script from the command line:
+
+.. code-block:: bash
+
+   python -m doctest [-v] [-o OPTION] [-f] file [file ...]
+
+.. program:: doctest
+
+.. option:: -v, --verbose
+
+   Detailed report of all examples tried is printed to standard output,
+   along with assorted summaries at the end::
+
+      python -m doctest -v example.py
+
+   This will import :file:`example.py` as a standalone module and run
+   :func:`testmod` on it. Note that this may not work correctly if the
+   file is part of a package and imports other submodules from that package.
+
+   If the file name does not end with :file:`.py`, :mod:`!doctest` infers
+   that it must be run with :func:`testfile` instead::
+
+      python -m doctest -v example.txt
+
+.. option:: -o, --option <option>
+
+   Option flags control various aspects of doctest's behavior, see section
+   :ref:`doctest-options`.
+
+   .. versionadded:: 3.4
+
+.. option:: -f, --fail-fast
+
+   This is shorthand for ``-o FAIL_FAST``.
+
+   .. versionadded:: 3.4
 
 
 .. _doctest-how-it-works:
@@ -540,9 +570,6 @@ Symbolic names for the flags are supplied as module constants, which can be
 The names can also be used in :ref:`doctest directives <doctest-directives>`,
 and may be passed to the doctest command line interface via the ``-o`` option.
 
-.. versionadded:: 3.4
-   The ``-o`` command line option.
-
 The first group of options define test semantics, controlling aspects of how
 doctest decides whether actual output matches an example's expected output:
 
@@ -682,11 +709,6 @@ The second group of options controls how test failures are reported:
    1.  This flag may be useful during debugging, since examples after the first
    failure won't even produce debugging output.
 
-   The doctest command line accepts the option ``-f`` as a shorthand for ``-o
-   FAIL_FAST``.
-
-   .. versionadded:: 3.4
-
 
 .. data:: REPORTING_FLAGS
 

Doc/library/http.server.rst

@@ -418,49 +418,6 @@ the current directory::
 such as using different index file names by overriding the class attribute
 :attr:`index_pages`.
 
-.. _http-server-cli:
-
-:mod:`http.server` can also be invoked directly using the :option:`-m`
-switch of the interpreter.  Similar to
-the previous example, this serves files relative to the current directory::
-
-        python -m http.server
-
-The server listens to port 8000 by default. The default can be overridden
-by passing the desired port number as an argument::
-
-        python -m http.server 9000
-
-By default, the server binds itself to all interfaces.  The option ``-b/--bind``
-specifies a specific address to which it should bind. Both IPv4 and IPv6
-addresses are supported. For example, the following command causes the server
-to bind to localhost only::
-
-        python -m http.server --bind 127.0.0.1
-
-.. versionchanged:: 3.4
-   Added the ``--bind`` option.
-
-.. versionchanged:: 3.8
-   Support IPv6 in the ``--bind`` option.
-
-By default, the server uses the current directory. The option ``-d/--directory``
-specifies a directory to which it should serve the files. For example,
-the following command uses a specific directory::
-
-        python -m http.server --directory /tmp/
-
-.. versionchanged:: 3.7
-   Added the ``--directory`` option.
-
-By default, the server is conformant to HTTP/1.0. The option ``-p/--protocol``
-specifies the HTTP version to which the server is conformant. For example, the
-following command runs an HTTP/1.1 conformant server::
-
-        python -m http.server --protocol HTTP/1.1
-
-.. versionchanged:: 3.11
-   Added the ``--protocol`` option.
 
 .. class:: CGIHTTPRequestHandler(request, client_address, server)
 
@@ -510,25 +467,85 @@ following command runs an HTTP/1.1 conformant server::
       Retaining it could lead to further :ref:`security considerations
       <http.server-security>`.
 
-:class:`CGIHTTPRequestHandler` can be enabled in the command line by passing
-the ``--cgi`` option::
 
-        python -m http.server --cgi
+.. _http-server-cli:
+
+Command-line interface
+----------------------
+
+:mod:`http.server` can also be invoked directly using the :option:`-m`
+switch of the interpreter.  The following example illustrates how to serve
+files relative to the current directory::
+
+   python -m http.server [OPTIONS] [port]
+
+The following options are accepted:
+
+.. program:: http.server
 
-.. deprecated-removed:: 3.13 3.15
+.. option:: port
 
-   :mod:`http.server` command line ``--cgi`` support is being removed
-   because :class:`CGIHTTPRequestHandler` is being removed.
+   The server listens to port 8000 by default. The default can be overridden
+   by passing the desired port number as an argument::
+
+      python -m http.server 9000
+
+.. option:: -b, --bind <address>
+
+   Specifies a specific address to which it should bind. Both IPv4 and IPv6
+   addresses are supported. By default, the server binds itself to all
+   interfaces. For example, the following command causes the server to bind
+   to localhost only::
+
+      python -m http.server --bind 127.0.0.1
+
+   .. versionadded:: 3.4
+
+   .. versionchanged:: 3.8
+      Support IPv6 in the ``--bind`` option.
+
+.. option:: -d, --directory <dir>
+
+   Specifies a directory to which it should serve the files. By default,
+   the server uses the current directory. For example, the following command
+   uses a specific directory::
+
+      python -m http.server --directory /tmp/
+
+   .. versionadded:: 3.7
+
+.. option:: -p, --protocol <version>
+
+   Specifies the HTTP version to which the server is conformant. By default,
+   the server is conformant to HTTP/1.0. For example, the following command
+   runs an HTTP/1.1 conformant server::
+
+      python -m http.server --protocol HTTP/1.1
+
+   .. versionadded:: 3.11
+
+.. option:: --cgi
+
+   :class:`CGIHTTPRequestHandler` can be enabled in the command line by passing
+   the ``--cgi`` option::
+
+      python -m http.server --cgi
+
+   .. deprecated-removed:: 3.13 3.15
+
+      :mod:`http.server` command line ``--cgi`` support is being removed
+      because :class:`CGIHTTPRequestHandler` is being removed.
 
 .. warning::
 
-   :class:`CGIHTTPRequestHandler` and the ``--cgi`` command line option
+   :class:`CGIHTTPRequestHandler` and the ``--cgi`` command-line option
    are not intended for use by untrusted clients and may be vulnerable
    to exploitation. Always use within a secure environment.
 
+
 .. _http.server-security:
 
-Security Considerations
+Security considerations
 -----------------------
 
 .. index:: pair: http.server; security

Doc/library/math.rst

@@ -350,8 +350,8 @@ Floating point manipulation functions
 
    *abs_tol* is the absolute tolerance; it defaults to ``0.0`` and it must be
    nonnegative.  When comparing ``x`` to ``0.0``, ``isclose(x, 0)`` is computed
-   as ``abs(x) <= rel_tol  * abs(x)``, which is ``False`` for any ``x`` and
-   rel_tol less than ``1.0``.  So add an appropriate positive abs_tol argument
+   as ``abs(x) <= rel_tol  * abs(x)``, which is ``False`` for any nonzero ``x`` and
+   *rel_tol* less than ``1.0``.  So add an appropriate positive *abs_tol* argument
    to the call.
 
    The IEEE 754 special values of ``NaN``, ``inf``, and ``-inf`` will be