Merge branch 'main' into pep-828/implementation

Author: ZeroIntensity

.gitignore

@@ -143,6 +143,7 @@ Tools/unicode/data/
 /config.status.lineno
 /.ccache
 /cross-build*/
+/dist/
 /jit_stencils*.h
 /jit_unwind_info*.h
 .jit-stamp

Doc/c-api/frame.rst

@@ -269,29 +269,8 @@ Unless using :pep:`523`, you will not need this.
       * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR
         - The frame corresponds to a method on a class instance.
 
-   However, Python's C API lacks a function to read the executable kind from
-   a frame. Instead, use this recipe:
-
-   .. code-block:: c
-
-      int
-      get_executable_kind(PyFrameObject *frame)
-      {
-         _PyInterpreterFrame *f = frame->f_frame;
-         PyObject *exec = PyStackRef_AsPyObjectBorrow(f->f_executable);
-
-         if (PyCode_Check(exec)) {
-            return PyUnstable_EXECUTABLE_KIND_PY_FUNCTION;
-         }
-         if (PyMethod_Check(exec)) {
-            return PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION;
-         }
-         if (Py_IS_TYPE(exec, &PyMethodDescr_Type)) {
-            return PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR;
-         }
-
-         return PyUnstable_EXECUTABLE_KIND_SKIP;
-      }
+   Note that reading the executable kind from a frame is currently only
+   possible with undocumented internal APIs.
 
    .. versionadded:: 3.13
 

Doc/library/argparse.rst

@@ -1679,6 +1679,12 @@ The Namespace object
    Simple class used by default by :meth:`~ArgumentParser.parse_args` to create
    an object holding attributes and return it.
 
+   :class:`!Namespace` objects support :func:`copy.replace`,
+   which returns a copy of the object with the specified attributes replaced.
+
+   .. versionchanged:: next
+      Added support for :func:`copy.replace`.
+
    This class is deliberately simple, just an :class:`object` subclass with a
    readable string representation. If you prefer to have dict-like view of the
    attributes, you can use the standard Python idiom, :func:`vars`::

Doc/library/ast.rst

@@ -806,7 +806,8 @@ Comprehensions
    List and set comprehensions, generator expressions, and dictionary
    comprehensions. ``elt`` (or ``key`` and ``value``) is a single node
    representing the part that will be evaluated for each item.
-
+   For dictionary comprehensions using unpacking, for example
+   ``{**item for item in items}``, ``value`` is ``None``,
    ``generators`` is a list of :class:`comprehension` nodes.
 
    .. doctest::

Doc/library/asyncio-stream.rst

@@ -389,6 +389,16 @@ StreamWriter
       be resumed.  When there is nothing to wait for, the :meth:`drain`
       returns immediately.
 
+      .. note::
+
+         When the write buffer is below the high watermark,
+         :meth:`drain` returns immediately without yielding to
+         the event loop.  As a result, code which repeatedly calls
+         ``write()`` followed by ``await drain()`` may prevent other
+         tasks from running.  To prevent blocking behavior, yield
+         to the event loop explicitly with ``await asyncio.sleep(0)``
+         (see :func:`asyncio.sleep`).
+
    .. method:: start_tls(sslcontext, *, server_hostname=None, \
                          ssl_handshake_timeout=None, ssl_shutdown_timeout=None)
       :async:

Doc/library/asyncio-task.rst

@@ -288,6 +288,17 @@ Creating tasks
               # completion:
               task.add_done_callback(background_tasks.discard)
 
+      Note that this approach never awaits the tasks, so if a task
+      fails, its exception is never retrieved and asyncio logs a
+      "Task exception was never retrieved" message when the task is
+      garbage collected.  To avoid this, use :class:`asyncio.TaskGroup`
+      which keeps a strong reference to each task, awaits them and
+      propagates their exceptions::
+
+          async with asyncio.TaskGroup() as tg:
+              for i in range(10):
+                  tg.create_task(some_coro(param=i))
+
    .. versionadded:: 3.7
 
    .. versionchanged:: 3.8

Doc/library/dis.rst

@@ -1899,25 +1899,29 @@ iterations of the loop.
 
    The operand determines which intrinsic function is called:
 
-   +----------------------------------------+-----------------------------------+
-   | Operand                                | Description                       |
-   +========================================+===================================+
-   | ``INTRINSIC_2_INVALID``                | Not valid                         |
-   +----------------------------------------+-----------------------------------+
-   | ``INTRINSIC_PREP_RERAISE_STAR``        | Calculates the                    |
-   |                                        | :exc:`ExceptionGroup` to raise    |
-   |                                        | from a ``try-except*``.           |
-   +----------------------------------------+-----------------------------------+
-   | ``INTRINSIC_TYPEVAR_WITH_BOUND``       | Creates a :class:`typing.TypeVar` |
-   |                                        | with a bound.                     |
-   +----------------------------------------+-----------------------------------+
-   | ``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS`` | Creates a                         |
-   |                                        | :class:`typing.TypeVar` with      |
-   |                                        | constraints.                      |
-   +----------------------------------------+-----------------------------------+
-   | ``INTRINSIC_SET_FUNCTION_TYPE_PARAMS`` | Sets the ``__type_params__``      |
-   |                                        | attribute of a function.          |
-   +----------------------------------------+-----------------------------------+
+   +------------------------------------------+-----------------------------------+
+   | Operand                                  | Description                       |
+   +==========================================+===================================+
+   | ``INTRINSIC_2_INVALID``                  | Not valid                         |
+   +------------------------------------------+-----------------------------------+
+   | ``INTRINSIC_PREP_RERAISE_STAR``          | Calculates the                    |
+   |                                          | :exc:`ExceptionGroup` to raise    |
+   |                                          | from a ``try-except*``.           |
+   +------------------------------------------+-----------------------------------+
+   | ``INTRINSIC_TYPEVAR_WITH_BOUND``         | Creates a :class:`typing.TypeVar` |
+   |                                          | with a bound.                     |
+   +------------------------------------------+-----------------------------------+
+   | ``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS``   | Creates a                         |
+   |                                          | :class:`typing.TypeVar` with      |
+   |                                          | constraints.                      |
+   +------------------------------------------+-----------------------------------+
+   | ``INTRINSIC_SET_FUNCTION_TYPE_PARAMS``   | Sets the ``__type_params__``      |
+   |                                          | attribute of a function.          |
+   +------------------------------------------+-----------------------------------+
+   | ``INTRINSIC_ADD_CONDITIONAL_ANNOTATION`` | Adds an annotation index to the   |
+   |                                          | ``__conditional_annotations__``   |
+   |                                          | set.                              |
+   +------------------------------------------+-----------------------------------+
 
    .. versionadded:: 3.12
 

Doc/library/os.rst

@@ -1448,7 +1448,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
    respectively.
 
-   .. availability:: Unix, not WASI, not macOS, not iOS.
+   .. availability:: Unix, macOS >= 27.0, not WASI, not iOS.
 
    .. versionadded:: 3.3
 

Doc/library/stdtypes.rst

@@ -4871,7 +4871,7 @@ copying.
       .. versionadded:: 3.2
 
    .. method:: cast(format, /)
-               cast(format, shape, /)
+               cast(format, shape, /, *, order='C')
 
       Cast a memoryview to a new format or shape. *shape* defaults to
       ``[byte_length//new_itemsize]``, which means that the result view
@@ -4880,6 +4880,12 @@ copying.
       1D -> C-:term:`contiguous`, C-contiguous -> 1D, and
       F-contiguous -> 1D.
 
+      With a multidimensional *shape*, *order* selects the memory layout of
+      the result: ``'C'`` for C-contiguous (row-major, the default) or ``'F'``
+      for Fortran-contiguous (column-major).  The buffer is still not copied,
+      so ``order='F'`` gives a zero-copy view over a buffer holding
+      column-major data.
+
       The destination format is restricted to a single element native format in
       :mod:`struct` syntax. One of the formats must be a byte format
       ('B', 'b' or 'c'). The byte length of the result must be the same
@@ -5031,8 +5037,20 @@ copying.
          >>> y.nbytes
          96
 
+      Interpret a flat buffer as a Fortran-contiguous (column-major) array::
+
+         >>> buf = bytes(range(6))
+         >>> y = memoryview(buf).cast('B', shape=[3, 2], order='F')
+         >>> y.f_contiguous
+         True
+         >>> y.tolist()
+         [[0, 3], [1, 4], [2, 5]]
+
       .. versionadded:: 3.3
 
+      .. versionchanged:: next
+         Added the *order* parameter.
+
    .. attribute:: readonly
 
       A bool indicating whether the memory is read only.

Doc/library/test.rst

@@ -963,7 +963,7 @@ The :mod:`!test.support` module defines the following functions:
 
 .. currentmodule:: test.support.isolation
 
-.. decorator:: runInSubprocess()
+.. decorator:: runInSubprocess(*, options=(), env=None, timeout=None)
 
    Decorator that runs the decorated test in a fresh interpreter subprocess, in
    isolation, so that it does not share global or interpreter state with the
@@ -997,6 +997,19 @@ The :mod:`!test.support` module defines the following functions:
    :func:`~test.support.bigmemtest` and the like behave consistently in both
    processes.
 
+   *options* is a sequence of interpreter command line options
+   to run the subprocess with,
+   and *env* is a mapping of environment variables to set in it,
+   on top of the inherited environment.
+   A value of ``None`` in *env* unsets the variable.
+   Note that :option:`-E` and :option:`-I` make the subprocess ignore
+   the ``PYTHON*`` environment variables, including :envvar:`PYTHONPATH`.
+
+   *timeout* is the number of seconds to wait for the subprocess;
+   the test is reported as an error if it does not complete in time.
+   By default there is no timeout,
+   and a hung test is left to the timeout of the test runner.
+
    The test is skipped on platforms without subprocess support.