Merge remote-tracking branch 'cpython/main' into pythongh-98692

Doc/c-api/init_config.rst

@@ -1571,8 +1571,6 @@ Private provisional API:
 
 * :c:member:`PyConfig._init_main`: if set to ``0``,
   :c:func:`Py_InitializeFromConfig` stops at the "Core" initialization phase.
-* :c:member:`PyConfig._isolated_interpreter`: if non-zero,
-  disallow threads, subprocesses and fork.
 
 .. c:function:: PyStatus _Py_InitializeMain(void)
 

Doc/howto/clinic.rst

@@ -1,5 +1,7 @@
 .. highlight:: c
 
+.. _howto-clinic:
+
 **********************
 Argument Clinic How-To
 **********************

Doc/howto/isolating-extensions.rst

@@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters
 
    .. After adding to limited API:
 
-      If you use the `limited API <https://docs.python.org/3/c-api/stable.html>__,
+      If you use the :ref:`limited API <stable>,
       you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI
       compatibility with earlier versions.
 

Doc/howto/perf_profiling.rst

@@ -8,10 +8,11 @@ Python support for the Linux ``perf`` profiler
 
 :author: Pablo Galindo
 
-The Linux ``perf`` profiler is a very powerful tool that allows you to profile and
-obtain information about the performance of your application. ``perf`` also has
-a very vibrant ecosystem of tools that aid with the analysis of the data that it
-produces.
+`The Linux perf profiler <https://perf.wiki.kernel.org>`_
+is a very powerful tool that allows you to profile and obtain
+information about the performance of your application.
+``perf`` also has a very vibrant ecosystem of tools
+that aid with the analysis of the data that it produces.
 
 The main problem with using the ``perf`` profiler with Python applications is that
 ``perf`` only allows to get information about native symbols, this is, the names of
@@ -25,7 +26,7 @@ fly before the execution of every Python function and it will teach ``perf`` the
 relationship between this piece of code and the associated Python function using
 `perf map files`_.
 
-.. warning::
+.. note::
 
     Support for the ``perf`` profiler is only currently available for Linux on
     selected architectures. Check the output of the configure build step or
@@ -51,11 +52,11 @@ For example, consider the following script:
     if __name__ == "__main__":
         baz(1000000)
 
-We can run perf to sample CPU stack traces at 9999 Hertz:
+We can run ``perf`` to sample CPU stack traces at 9999 Hertz::
 
     $ perf record -F 9999 -g -o perf.data python my_script.py
 
-Then we can use perf report to analyze the data:
+Then we can use ``perf`` report to analyze the data:
 
 .. code-block:: shell-session
 
@@ -101,7 +102,7 @@ As you can see here, the Python functions are not shown in the output, only ``_P
 functions use the same C function to evaluate bytecode so we cannot know which Python function corresponds to which
 bytecode-evaluating function.
 
-Instead, if we run the same experiment with perf support activated we get:
+Instead, if we run the same experiment with ``perf`` support enabled we get:
 
 .. code-block:: shell-session
 
@@ -147,52 +148,58 @@ Instead, if we run the same experiment with perf support activated we get:
 
 
 
-Enabling perf profiling mode
-----------------------------
+How to enable ``perf`` profiling support
+----------------------------------------
 
-There are two main ways to activate the perf profiling mode. If you want it to be
-active since the start of the Python interpreter, you can use the ``-Xperf`` option:
+``perf`` profiling support can either be enabled from the start using
+the environment variable :envvar:`PYTHONPERFSUPPORT` or the
+:option:`-X perf <-X>` option,
+or dynamically using :func:`sys.activate_stack_trampoline` and
+:func:`sys.deactivate_stack_trampoline`.
 
-    $ python -Xperf my_script.py
+The :mod:`!sys` functions take precedence over the :option:`!-X` option,
+the :option:`!-X` option takes precedence over the environment variable.
 
-You can also set the :envvar:`PYTHONPERFSUPPORT` to a nonzero value to actiavate perf
-profiling mode globally.
+Example, using the environment variable::
 
-There is also support for dynamically activating and deactivating the perf
-profiling mode by using the APIs in the :mod:`sys` module:
+   $ PYTHONPERFSUPPORT=1
+   $ python script.py
+   $ perf report -g -i perf.data
 
-.. code-block:: python
-
-    import sys
-    sys.activate_stack_trampoline("perf")
+Example, using the :option:`!-X` option::
 
-    # Run some code with Perf profiling active
+   $ python -X perf script.py
+   $ perf report -g -i perf.data
 
-    sys.deactivate_stack_trampoline()
+Example, using the :mod:`sys` APIs in file :file:`example.py`:
 
-    # Perf profiling is not active anymore
+.. code-block:: python
 
-These APIs can be handy if you want to activate/deactivate profiling mode in
-response to a signal or other communication mechanism with your process.
+   import sys
 
+   sys.activate_stack_trampoline("perf")
+   do_profiled_stuff()
+   sys.deactivate_stack_trampoline()
 
+   non_profiled_stuff()
 
-Now we can analyze the data with ``perf report``:
+...then::
 
-    $ perf report -g -i perf.data
+   $ python ./example.py
+   $ perf report -g -i perf.data
 
 
 How to obtain the best results
--------------------------------
+------------------------------
 
 For the best results, Python should be compiled with
 ``CFLAGS="-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer"`` as this allows
 profilers to unwind using only the frame pointer and not on DWARF debug
-information. This is because as the code that is interposed to allow perf
+information. This is because as the code that is interposed to allow ``perf``
 support is dynamically generated it doesn't have any DWARF debugging information
 available.
 
-You can check if you system has been compiled with this flag by running:
+You can check if your system has been compiled with this flag by running::
 
     $ python -m sysconfig | grep 'no-omit-frame-pointer'
 

Doc/library/asyncio-stream.rst

@@ -183,7 +183,8 @@ StreamReader
 .. class:: StreamReader
 
    Represents a reader object that provides APIs to read data
-   from the IO stream.
+   from the IO stream. As an :term:`asynchronous iterable`, the
+   object supports the :keyword:`async for` statement.
 
    It is not recommended to instantiate *StreamReader* objects
    directly; use :func:`open_connection` and :func:`start_server`

Doc/library/configparser.rst

@@ -33,13 +33,17 @@ can be customized by end users easily.
 
 .. seealso::
 
+   Module :mod:`tomllib`
+      TOML is a well-specified format for application configuration files.
+      It is specifically designed to be an improved version of INI.
+
    Module :mod:`shlex`
-      Support for creating Unix shell-like mini-languages which can be used as
-      an alternate format for application configuration files.
+      Support for creating Unix shell-like mini-languages which can also
+      be used for application configuration files.
 
    Module :mod:`json`
-      The json module implements a subset of JavaScript syntax which can also
-      be used for this purpose.
+      The ``json`` module implements a subset of JavaScript syntax which is
+      sometimes used for configuration, but does not support comments.
 
 
 .. testsetup::

Doc/library/dataclasses.rst

@@ -191,7 +191,7 @@ Module contents
     .. versionchanged:: 3.11
        If a field name is already included in the ``__slots__``
        of a base class, it will not be included in the generated ``__slots__``
-       to prevent `overriding them <https://docs.python.org/3/reference/datamodel.html#notes-on-using-slots>`_.
+       to prevent :ref:`overriding them <datamodel-note-slots>`.
        Therefore, do not use ``__slots__`` to retrieve the field names of a
        dataclass. Use :func:`fields` instead.
        To be able to determine inherited slots,

Doc/library/dis.rst

@@ -38,7 +38,9 @@ interpreter.
       Some instructions are accompanied by one or more inline cache entries,
       which take the form of :opcode:`CACHE` instructions. These instructions
       are hidden by default, but can be shown by passing ``show_caches=True`` to
-      any :mod:`dis` utility.
+      any :mod:`dis` utility. Furthermore, the interpreter now adapts the
+      bytecode to specialize it for different runtime conditions. The
+      adaptive bytecode can be shown by passing ``adaptive=True``.
 
 
 Example: Given the function :func:`myfunc`::
@@ -70,8 +72,8 @@ The bytecode analysis API allows pieces of Python code to be wrapped in a
 :class:`Bytecode` object that provides easy access to details of the compiled
 code.
 
-.. class:: Bytecode(x, *, first_line=None, current_offset=None, show_caches=False)
-
+.. class:: Bytecode(x, *, first_line=None, current_offset=None,\
+                    show_caches=False, adaptive=False)
 
    Analyse the bytecode corresponding to a function, generator, asynchronous
    generator, coroutine, method, string of source code, or a code object (as
@@ -90,6 +92,12 @@ code.
    disassembled code. Setting this means :meth:`.dis` will display a "current
    instruction" marker against the specified opcode.
 
+   If *show_caches* is ``True``, :meth:`.dis` will display inline cache
+   entries used by the interpreter to specialize the bytecode.
+
+   If *adaptive* is ``True``, :meth:`.dis` will display specialized bytecode
+   that may be different from the original bytecode.
+
    .. classmethod:: from_traceback(tb, *, show_caches=False)
 
       Construct a :class:`Bytecode` instance from the given traceback, setting
@@ -117,7 +125,7 @@ code.
       This can now handle coroutine and asynchronous generator objects.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 Example:
 
@@ -172,7 +180,7 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
 
-.. function:: dis(x=None, *, file=None, depth=None, show_caches=False)
+.. function:: dis(x=None, *, file=None, depth=None, show_caches=False, adaptive=False)
 
    Disassemble the *x* object.  *x* can denote either a module, a class, a
    method, a function, a generator, an asynchronous generator, a coroutine,
@@ -193,6 +201,12 @@ operation is being performed, so the intermediate analysis object isn't useful:
    The maximal depth of recursion is limited by *depth* unless it is ``None``.
    ``depth=0`` means no recursion.
 
+   If *show_caches* is ``True``, this function will display inline cache
+   entries used by the interpreter to specialize the bytecode.
+
+   If *adaptive* is ``True``, this function will display specialized bytecode
+   that may be different from the original bytecode.
+
    .. versionchanged:: 3.4
       Added *file* parameter.
 
@@ -203,10 +217,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
       This can now handle coroutine and asynchronous generator objects.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
-.. function:: distb(tb=None, *, file=None, show_caches=False)
+.. function:: distb(tb=None, *, file=None, show_caches=False, adaptive=False)
 
    Disassemble the top-of-stack function of a traceback, using the last
    traceback if none was passed.  The instruction causing the exception is
@@ -219,11 +233,11 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
-.. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False)
-              disco(code, lasti=-1, *, file=None, show_caches=False)
+.. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
+              disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False)
 
    Disassemble a code object, indicating the last instruction if *lasti* was
    provided.  The output is divided in the following columns:
@@ -246,10 +260,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
-.. function:: get_instructions(x, *, first_line=None, show_caches=False)
+.. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)
 
    Return an iterator over the instructions in the supplied function, method,
    source code string or code object.
@@ -262,10 +276,12 @@ operation is being performed, so the intermediate analysis object isn't useful:
    source line information (if any) is taken directly from the disassembled code
    object.
 
+   The *show_caches* and *adaptive* parameters work as they do in :func:`dis`.
+
    .. versionadded:: 3.4
 
    .. versionchanged:: 3.11
-      Added the ``show_caches`` parameter.
+      Added the *show_caches* and *adaptive* parameters.
 
 
 .. function:: findlinestarts(code)
@@ -397,6 +413,15 @@ The Python compiler currently generates the following bytecode instructions.
    Removes the top-of-stack (TOS) item.
 
 
+.. opcode:: END_FOR
+
+   Removes the top two values from the stack.
+   Equivalent to POP_TOP; POP_TOP.
+   Used to clean up at the end of loops, hence the name.
+
+   .. versionadded:: 3.12
+
+
 .. opcode:: COPY (i)
 
    Push the *i*-th item to the top of the stack. The item is not removed from its
@@ -1072,9 +1097,11 @@ iterations of the loop.
 
    TOS is an :term:`iterator`.  Call its :meth:`~iterator.__next__` method.  If
    this yields a new value, push it on the stack (leaving the iterator below
-   it).  If the iterator indicates it is exhausted, TOS is popped, and the byte
+   it).  If the iterator indicates it is exhausted then the byte
    code counter is incremented by *delta*.
 
+   .. versionchanged:: 3.12
+      Up until 3.11 the iterator was popped when it was exhausted.
 
 .. opcode:: LOAD_GLOBAL (namei)
 

Doc/library/importlib.metadata.rst

@@ -360,7 +360,7 @@ Because `Distribution Package <https://packaging.python.org/en/latest/glossary/#
 is not available through :data:`sys.path` searches, or
 package loaders directly,
 the metadata for a distribution is found through import
-system `finders`_.  To find a distribution package's metadata,
+system :ref:`finders <finders-and-loaders>`.  To find a distribution package's metadata,
 ``importlib.metadata`` queries the list of :term:`meta path finders <meta path finder>` on
 :data:`sys.meta_path`.
 
@@ -396,4 +396,3 @@ a custom finder, return instances of this derived ``Distribution`` in the
 
 .. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
 .. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api
-.. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders