Merge remote-tracking branch 'upstream/main' into gh-114258-contains

Author: corona10

Doc/c-api/exceptions.rst

@@ -363,8 +363,7 @@ Importing Modules
 
 .. c:function:: int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)
 
-   Similar to :c:func:`PyImport_ImportModuleAttr`, but names are UTF-8 encoded
-   strings instead of Python :class:`str` objects.
+   Sets the current lazy imports mode.
 
    This function always returns ``0``.
 

Doc/c-api/import.rst

@@ -72,23 +72,28 @@ Builtin Iterator Types
 These are built-in iteration types that are included in Python's C API, but
 provide no additional functions. They are here for completeness.
 
-
-.. list-table::
-   :widths: auto
-   :header-rows: 1
-
-   * * C type
-     * Python type
-   * * .. c:var:: PyTypeObject PyEnum_Type
-     * :py:class:`enumerate`
-   * * .. c:var:: PyTypeObject PyFilter_Type
-     * :py:class:`filter`
-   * * .. c:var:: PyTypeObject PyMap_Type
-     * :py:class:`map`
-   * * .. c:var:: PyTypeObject PyReversed_Type
-     * :py:class:`reversed`
-   * * .. c:var:: PyTypeObject PyZip_Type
-     * :py:class:`zip`
+.. stable-abi-note::
+
+   These pointers are part of the :ref:`Stable ABI <stable>`.
+
+.. omit-stable-abi-notes::
+
+   .. list-table::
+      :widths: auto
+      :header-rows: 1
+
+      * * C type
+        * Python type
+      * * .. c:var:: PyTypeObject PyEnum_Type
+        * :py:class:`enumerate`
+      * * .. c:var:: PyTypeObject PyFilter_Type
+        * :py:class:`filter`
+      * * .. c:var:: PyTypeObject PyMap_Type
+        * :py:class:`map`
+      * * .. c:var:: PyTypeObject PyReversed_Type
+        * :py:class:`reversed`
+      * * .. c:var:: PyTypeObject PyZip_Type
+        * :py:class:`zip`
 
 
 Other Iterator Objects

Doc/c-api/iterator.rst

@@ -214,6 +214,10 @@
     ('c:macro', 'LONG_MIN'),
     # Standard C variables
     ('c:data', 'errno'),
+    # Platform-specific socket constants documented collectively as SO_*.
+    ('py:const', 'socket.SO_EXCLUSIVEADDRUSE'),
+    ('py:const', 'socket.SO_REUSEADDR'),
+    ('py:const', 'socket.SO_REUSEPORT'),
     # Standard environment variables
     ('envvar', 'BROWSER'),
     ('envvar', 'COLUMNS'),

Doc/conf.py

@@ -1771,8 +1771,9 @@ Subcommands
 
    * help_ - help for sub-parser group in help output, by default ``None``
 
-   * metavar_ - string presenting available subcommands in help; by default it
-     is ``None`` and presents subcommands in form {cmd1, cmd2, ..}
+   * metavar_ - placeholder shown in usage and the subparsers' help entry
+     instead of ``{cmd1, cmd2, ...}``; by default ``None``.
+     Individual subcommand names are unchanged.
 
    Some example usage::
 

Doc/library/argparse.rst

@@ -244,6 +244,16 @@ Interpreter objects
    Generally, :class:`Interpreter` shouldn't be called directly.
    Instead, use :func:`create` or one of the other module functions.
 
+   :class:`!Interpreter` objects support the :term:`context manager`
+   protocol. Exiting the :keyword:`with` block calls :meth:`close`::
+
+      with interpreters.create() as interp:
+          interp.exec('print("hello")')
+
+   .. versionchanged:: next
+      Added support for using :class:`!Interpreter` objects in
+      a :term:`context manager`.
+
    .. attribute:: id
 
       (read-only)

Doc/library/concurrent.interpreters.rst

@@ -112,7 +112,7 @@ The module defines the following items:
    The *compresslevel* argument is an integer from ``0`` to ``9`` controlling
    the level of compression; ``1`` is fastest and produces the least
    compression, and ``9`` is slowest and produces the most compression. ``0``
-   is no compression. The default is ``9``.
+   is no compression. The default is ``6``.
 
    The optional *mtime* argument is the timestamp requested by gzip. The time
    is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. Set

Doc/library/gzip.rst

@@ -678,6 +678,11 @@ always available. Unless explicitly noted otherwise, all variables are read-only
         - :option:`-X context_aware_warnings <-X>` and
           :envvar:`PYTHON_CONTEXT_AWARE_WARNINGS`
 
+      * - .. attribute:: flags.lazy_imports
+        - :option:`-X lazy_imports <-X>` and :envvar:`PYTHON_LAZY_IMPORTS`
+          (``1`` for ``all``, ``-1`` otherwise; not changed by
+          :func:`set_lazy_imports`)
+
 
    .. versionchanged:: 3.2
       Added ``quiet`` attribute for the new :option:`-q` flag.
@@ -714,6 +719,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    .. versionchanged:: 3.14
       Added the ``context_aware_warnings`` attribute.
 
+   .. versionchanged:: 3.15
+      Added the ``lazy_imports`` attribute.
+
 
 .. data:: float_info
 

Doc/library/sys.rst

@@ -506,7 +506,8 @@ The :mod:`!test.support` module defines the following functions:
 
 .. function:: with_pymalloc()
 
-   Return :const:`_testcapi.WITH_PYMALLOC`.
+   Return ``True`` if Python was built with :ref:`pymalloc <pymalloc>` enabled
+   and is not a :term:`free-threaded build`.
 
 
 .. function:: requires(resource, msg=None)
@@ -1088,7 +1089,7 @@ The :mod:`!test.support` module defines the following functions:
 
 .. function:: skip_if_broken_multiprocessing_synchronize()
 
-   Skip tests if the :mod:`multiprocessing.synchronize` module is missing, if
+   Skip tests if the :mod:`!multiprocessing.synchronize` module is missing, if
    there is no available semaphore implementation, or if creating a lock raises
    an :exc:`OSError`.
 
@@ -1260,7 +1261,7 @@ script execution tests.
    doesn't have an obvious home with Python's current home finding logic.
 
    Setting :envvar:`PYTHONHOME` is one way to get most of the testsuite to run
-   in that situation.  :envvar:`PYTHONPATH` or :envvar:`PYTHONUSERSITE` are
+   in that situation.  :envvar:`PYTHONPATH` or :envvar:`PYTHONNOUSERSITE` are
    other common environment variables that might impact whether or not the
    interpreter can start.
 
@@ -1708,8 +1709,8 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
 
    This function imports and returns a fresh copy of the named Python module
    by removing the named module from ``sys.modules`` before doing the import.
-   Note that unlike :func:`reload`, the original module is not affected by
-   this operation.
+   Note that unlike :func:`importlib.reload`, the original module is not
+   affected by this operation.
 
    *fresh* is an iterable of additional module names that are also removed
    from the ``sys.modules`` cache before doing the import.
@@ -1871,17 +1872,10 @@ The :mod:`!test.support.warnings_helper` module provides support for warnings te
 
    In this case all warnings are caught and no errors are raised.
 
-   On entry to the context manager, a :class:`WarningRecorder` instance is
-   returned. The underlying warnings list from
-   :func:`~warnings.catch_warnings` is available via the recorder object's
-   :attr:`warnings` attribute.  As a convenience, the attributes of the object
-   representing the most recent warning can also be accessed directly through
-   the recorder object (see example below).  If no warning has been raised,
-   then any of the attributes that would otherwise be expected on an object
-   representing a warning will return ``None``.
-
-   The recorder object also has a :meth:`reset` method, which clears the
-   warnings list.
+   On entry to the context manager, a :class:`WarningsRecorder` instance is
+   returned. The recorded warnings are available via its
+   :attr:`~WarningsRecorder.warnings` attribute, and its
+   :meth:`~WarningsRecorder.reset` method discards previously recorded warnings.
 
    The context manager is designed to be used like this::
 
@@ -1898,11 +1892,11 @@ The :mod:`!test.support.warnings_helper` module provides support for warnings te
 
       with check_warnings(quiet=True) as w:
           warnings.warn("foo")
-          assert str(w.args[0]) == "foo"
+          assert str(w.message) == "foo"
           warnings.warn("bar")
-          assert str(w.args[0]) == "bar"
-          assert str(w.warnings[0].args[0]) == "foo"
-          assert str(w.warnings[1].args[0]) == "bar"
+          assert str(w.message) == "bar"
+          assert str(w.warnings[0].message) == "foo"
+          assert str(w.warnings[1].message) == "bar"
           w.reset()
           assert len(w.warnings) == 0
 
@@ -1914,7 +1908,22 @@ The :mod:`!test.support.warnings_helper` module provides support for warnings te
       New optional arguments *filters* and *quiet*.
 
 
-.. class:: WarningsRecorder()
+.. class:: WarningsRecorder(warnings_list)
+
+   Class used to record warnings for unit tests. Wraps the warnings list
+   returned by :func:`warnings.catch_warnings` when recording is enabled.
+   :func:`check_warnings` returns an instance of this class.
+
+   As a convenience, the attributes of the object representing the most recent
+   warning can also be accessed directly through the recorder object.
+   If no warning has been raised since the recorder was created or last reset,
+   these attributes return ``None``.
+
+   .. attribute:: warnings
+
+      A list of warnings recorded since the recorder was created or last reset.
+
+   .. method:: reset()
 
-   Class used to record warnings for unit tests. See documentation of
-   :func:`check_warnings` above for more details.
+      Discard previously recorded warnings from the recorder's view.
+      The underlying warnings list is not modified.

Doc/library/test.rst

@@ -15,9 +15,8 @@ colorizers for on-screen displays.
 
 To simplify token stream handling, all :ref:`operator <operators>` and
 :ref:`delimiter <delimiters>` tokens and :data:`Ellipsis` are returned using
-the generic :data:`~token.OP` token type.  The exact
-type can be determined by checking the ``exact_type`` property on the
-:term:`named tuple` returned from :func:`tokenize.tokenize`.
+the generic :data:`~token.OP` token type.
+The :attr:`TokenInfo.exact_type` property gives the exact token type.
 
 
 .. warning::
@@ -40,25 +39,10 @@ The primary entry point is a :term:`generator`:
    :meth:`io.IOBase.readline` method of file objects.  Each call to the
    function should return one line of input as bytes.
 
-   The generator produces 5-tuples with these members: the token type; the
-   token string; a 2-tuple ``(srow, scol)`` of ints specifying the row and
-   column where the token begins in the source; a 2-tuple ``(erow, ecol)`` of
-   ints specifying the row and column where the token ends in the source; and
-   the line on which the token was found. The line passed (the last tuple item)
-   is the *physical* line.  The 5 tuple is returned as a :term:`named tuple`
-   with the field names:
-   ``type string start end line``.
-
-   The returned :term:`named tuple` has an additional property named
-   ``exact_type`` that contains the exact operator type for
-   :data:`~token.OP` tokens.  For all other token types ``exact_type``
-   equals the named tuple ``type`` field.
+   The generator produces :class:`TokenInfo` objects.
 
    .. versionchanged:: 3.1
-      Added support for named tuples.
-
-   .. versionchanged:: 3.3
-      Added support for ``exact_type``.
+      Changed to yield :class:`TokenInfo` objects instead of plain tuples.
 
    :func:`.tokenize` determines the source encoding of the file by looking for a
    UTF-8 BOM or encoding cookie, according to :pep:`263`.
@@ -71,9 +55,78 @@ The primary entry point is a :term:`generator`:
    a single line of input. However, :func:`generate_tokens` expects *readline*
    to return a str object rather than bytes.
 
-   The result is an iterator yielding named tuples, exactly like
+   The result is an iterator yielding :class:`TokenInfo` objects, exactly like
    :func:`.tokenize`. It does not yield an :data:`~token.ENCODING` token.
 
+.. class:: TokenInfo(type, string, start, end, line)
+
+   A :term:`named tuple` describing a token. It has five fields and an
+   additional :attr:`exact_type` property.
+
+   .. versionadded:: 3.1
+
+   .. attribute:: type
+
+      An integer identifying the token type, as defined by the constants in
+      :mod:`token`, such as :data:`~token.NAME` and :data:`~token.STRING`.
+      Operators and delimiters have type :data:`~token.OP`; use
+      :attr:`exact_type` for their specific token type.
+
+   .. attribute:: string
+
+      The token text as a :class:`str`.
+      For :data:`~token.STRING` tokens, this includes the quotes, any prefix,
+      and escape sequences, without evaluating them.
+
+      For an :data:`~token.ENCODING` token, this is the encoding name.
+      Tokens inserted without corresponding source text can have an empty
+      string. In :data:`~token.FSTRING_MIDDLE` and
+      :data:`~token.TSTRING_MIDDLE` tokens, doubled braces are replaced by
+      single braces.
+
+   .. attribute:: start
+
+      A 2-tuple ``(srow, scol)`` of ints specifying the inclusive start
+      position of the token in the source. Rows are numbered from 1 and
+      columns from 0. Columns count Unicode code points; a tab counts as
+      one column, without expanding it to a tab stop.
+
+      For an :data:`~token.ENCODING` token, this is ``(0, 0)``.
+
+   .. attribute:: end
+
+      A 2-tuple ``(erow, ecol)`` of ints specifying the exclusive end
+      position of the token. Rows are numbered from 1 and columns from 0.
+      For a token spanning multiple lines, *erow* is the final row and
+      *ecol* is the column on that row.
+
+      For example, the name ``spam`` at the beginning of the first line
+      has :attr:`start` equal to ``(1, 0)`` and :attr:`end` equal to ``(1, 4)``.
+
+      For an :data:`~token.ENCODING` token, this is ``(0, 0)``.
+      A :data:`~token.NEWLINE` or :data:`~token.NL` token inserted at the end
+      of input without a final newline can have an end column one beyond
+      the source text.
+
+   .. attribute:: line
+
+      A :class:`str` containing the full source line on which
+      the token was found, including surrounding text and the line terminator
+      if present. For a token spanning multiple lines, this can contain
+      several source lines. It is empty for :data:`~token.ENCODING` and
+      :data:`~token.ENDMARKER` tokens.
+
+   .. attribute:: exact_type
+
+      An integer identifying the specific operator type for
+      :data:`~token.OP` tokens, as defined by the constants in :mod:`token`.
+      For all other token types, this equals :attr:`type`.
+      For example, a ``+`` token has :attr:`type` equal to :data:`~token.OP`
+      and :attr:`exact_type` equal to :data:`~token.PLUS`.
+
+      .. versionadded:: 3.3
+
+
 All constants from the :mod:`token` module are also exported from
 :mod:`!tokenize`.