Merge branch 'main' into fix-c-fromisoformat-empty-fraction-tz

Author: StanFromIreland

.github/workflows/reusable-emscripten.yml

@@ -63,15 +63,17 @@ jobs:
       run: python3 Platforms/emscripten configure-build-python -- --config-cache --with-pydebug
     - name: "Make build Python"
       run: python3 Platforms/emscripten make-build-python
+    - name: "Display build info of the build Python"
+      run: python3 Platforms/emscripten pythoninfo-build
     - name: "Make dependencies"
       run: >-
         python3 Platforms/emscripten make-dependencies
         ${{ steps.emsdk-cache.outputs.cache-hit == 'true' && '--check-up-to-date' || '' }}
-    - name: "Configure host Python"
+    - name: "Configure host/Emscripten Python"
       run: python3 Platforms/emscripten configure-host --host-runner node -- --config-cache
-    - name: "Make host Python"
+    - name: "Make host/Emscripten Python"
       run: python3 Platforms/emscripten make-host
-    - name: "Display build info"
-      run: python3 Platforms/emscripten run --pythoninfo
+    - name: "Display build info of the host/Emscripten Python"
+      run: python3 Platforms/emscripten pythoninfo-host
     - name: "Test"
       run: python3 Platforms/emscripten run --test

.github/workflows/reusable-wasi.yml

@@ -16,7 +16,6 @@ jobs:
     timeout-minutes: 60
     env:
       WASMTIME_VERSION: 38.0.3
-      CROSS_BUILD_PYTHON: cross-build/build
       CROSS_BUILD_WASI: cross-build/wasm32-wasip1
     steps:
     - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -54,14 +53,16 @@ jobs:
       run: python3 Platforms/WASI configure-build-python -- --config-cache --with-pydebug
     - name: "Make build Python"
       run: python3 Platforms/WASI make-build-python
-    - name: "Configure host"
+    - name: "Display build info of the build Python"
+      run: python3 Platforms/WASI pythoninfo-build
+    - name: "Configure host/WASI Python"
       # `--with-pydebug` inferred from configure-build-python
       run: python3 Platforms/WASI configure-host -- --config-cache
       env:
         WASI_SDK_PATH: ${{ steps.install-wasi-sdk.outputs.wasi-sdk-path }}
-    - name: "Make host"
+    - name: "Make host/WASI Python"
       run: python3 Platforms/WASI make-host
-    - name: "Display build info"
-      run: make --directory "${CROSS_BUILD_WASI}" pythoninfo
+    - name: "Display build info of the host/WASI Python"
+      run: python3 Platforms/WASI pythoninfo-host
     - name: "Test"
       run: make --directory "${CROSS_BUILD_WASI}" test

Doc/c-api/threads.rst

@@ -242,6 +242,61 @@ a thread state that was previously attached for the current thread.
 .. seealso::
    :pep:`788`
 
+.. _c-api-reuse-thread-state:
+
+Reusing a thread state across repeated calls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creating and destroying a :c:type:`PyThreadState` is not free, and is more
+expensive on a :term:`free-threaded build`.  A foreign thread that calls into
+the interpreter many times -- for example, a worker thread in a native thread
+pool -- should avoid creating a fresh thread state on every entry and
+destroying it on every exit.  Instead, set up one thread state when the thread
+starts (or lazily on its first call into Python), attach and detach it around
+each call, and tear it down once when the thread exits.
+
+Manage the thread state explicitly with :c:func:`PyThreadState_New`, attaching
+and detaching it with :c:func:`PyEval_RestoreThread` and
+:c:func:`PyEval_SaveThread`.  This happens in three distinct phases, at
+different points in the thread's life.
+
+When the thread starts, create one thread state for it.  ``interp`` is the
+target interpreter, captured by the code that created this thread while it held
+an attached thread state (for example via :c:func:`PyInterpreterState_Get`)::
+
+   PyThreadState *tstate = PyThreadState_New(interp);
+
+Then, on each call into Python -- which may happen many times over the thread's
+life -- attach the thread state, make the Python C API calls that require it,
+and detach again so the thread does not hold the GIL while off doing non-Python
+work::
+
+   PyEval_RestoreThread(tstate);
+   result = CallSomeFunction();  /* your Python C API calls go here */
+   PyEval_SaveThread();
+
+When the thread is finished calling into Python, destroy the thread state once::
+
+   PyEval_RestoreThread(tstate);
+   PyThreadState_Clear(tstate);
+   PyThreadState_DeleteCurrent();
+
+The general-purpose entry points for calling in from a foreign thread --
+:c:func:`PyThreadState_Ensure` and the older :c:func:`PyGILState_Ensure` -- do
+*not* guarantee a persistent thread state: their thread-state lifetime is
+deliberately implementation-defined, so a matched acquire/release pair may
+create and destroy a thread state each time.  Use :c:func:`PyThreadState_New`,
+as shown here, whenever you specifically want to reuse one thread state across
+calls.
+
+The code that created the foreign thread must arrange for the shutdown sequence
+to run before the thread exits, and before :c:func:`Py_FinalizeEx` is called.
+If interpreter finalization begins first, the shutdown
+:c:func:`PyEval_RestoreThread` call will hang the thread rather than return (see
+:ref:`cautions-regarding-runtime-finalization`).  If the thread exits without
+running the shutdown sequence, the thread state is leaked for the remainder of
+the process.
+
 .. _c-api-attach-detach:
 
 Attaching/detaching thread states

Doc/c-api/type.rst

@@ -639,7 +639,7 @@ but need extra remarks for use as slots:
    in the following situations:
 
    - The base is not variable-sized (its
-     :c:member:`~PyTypeObject.tp_itemsize`).
+     :c:member:`~PyTypeObject.tp_itemsize` is zero).
    - The requested :c:member:`PyType_Spec.basicsize` is positive,
      suggesting that the memory layout of the base class is known.
    - The requested :c:member:`PyType_Spec.basicsize` is zero,

Doc/deprecations/pending-removal-in-3.16.rst

@@ -33,12 +33,12 @@ Pending removal in Python 3.16
   * :mod:`asyncio` policy system is deprecated and will be removed in Python 3.16.
     In particular, the following classes and functions are deprecated:
 
-    * :class:`asyncio.AbstractEventLoopPolicy`
-    * :class:`asyncio.DefaultEventLoopPolicy`
-    * :class:`asyncio.WindowsSelectorEventLoopPolicy`
-    * :class:`asyncio.WindowsProactorEventLoopPolicy`
-    * :func:`asyncio.get_event_loop_policy`
-    * :func:`asyncio.set_event_loop_policy`
+    * :class:`!asyncio.AbstractEventLoopPolicy`
+    * :class:`!asyncio.DefaultEventLoopPolicy`
+    * :class:`!asyncio.WindowsSelectorEventLoopPolicy`
+    * :class:`!asyncio.WindowsProactorEventLoopPolicy`
+    * :func:`!asyncio.get_event_loop_policy`
+    * :func:`!asyncio.set_event_loop_policy`
 
     Users should use :func:`asyncio.run` or :class:`asyncio.Runner` with
     *loop_factory* to use the desired event loop implementation.

Doc/deprecations/pending-removal-in-3.17.rst

@@ -68,3 +68,13 @@ Pending removal in Python 3.17
 
     See :pep:`PEP 688 <688#current-options>` for more details.
     (Contributed by Shantanu Jain in :gh:`91896`.)
+
+* :mod:`tkinter`:
+
+  - The :class:`!tkinter.Variable` methods :meth:`!trace_variable`,
+    :meth:`!trace` (an alias of :meth:`!trace_variable`),
+    :meth:`!trace_vdelete` and :meth:`!trace_vinfo`, deprecated since
+    Python 3.14, are scheduled for removal in Python 3.17.
+    Use :meth:`!trace_add`, :meth:`!trace_remove` and :meth:`!trace_info`
+    instead.
+    (Contributed by Serhiy Storchaka in :gh:`120220`.)

Doc/deprecations/pending-removal-in-3.21.rst

@@ -17,3 +17,9 @@ Pending removal in Python 3.21
     are not generated by the parser or accepted by the code generator.
   * The ``dims`` property of ``ast.Tuple`` will be removed in Python 3.21. Use
     the ``ast.Tuple.elts`` property instead.
+
+* :mod:`struct`:
+
+  * Soft-deprecated since Python 3.15, using ``'F'`` and ``'D'`` type codes are now
+    deprecated.  These codes will be removed in Python 3.21.  Use instead
+    two-letter forms ``'Zf'`` and ``'Zd'``.

Doc/faq/design.rst

@@ -263,6 +263,8 @@ In general, structured switch statements execute one block of code
 when an expression has a particular value or set of values.
 Since Python 3.10 one can easily match literal values, or constants
 within a namespace, with a ``match ... case`` statement.
+See :ref:`the specification <match>` and :ref:`the tutorial <tut-match>`
+for more information about :keyword:`match` statements.
 An older alternative is a sequence of ``if... elif... elif... else``.
 
 For cases where you need to choose from a very large number of possibilities,

Doc/howto/curses.rst

@@ -52,8 +52,8 @@ code, all the functions described here will probably be available.  The older
 versions of curses carried by some proprietary Unixes may not support
 everything, though.
 
-The Windows version of Python doesn't include the :mod:`curses`
-module.  A ported version called :pypi:`UniCurses` is available.
+The Windows version of Python doesn't include the :mod:`curses` module.
+The third-party :pypi:`windows-curses` package provides the same interface on Windows.
 
 
 The Python curses module

Doc/howto/mro.rst

@@ -10,7 +10,7 @@ The Python 2.3 Method Resolution Order
    The Method Resolution Order discussed here was *introduced* in Python 2.3,
    but it is still used in later versions -- including Python 3.
 
-By `Michele Simionato <https://www.phyast.pitt.edu/~micheles/>`__.
+By `Michele Simionato <https://github.com/micheles>`__.
 
 :Abstract: