Merge branch 'python:main' into main

Author: Santhosh-I

.github/CODEOWNERS

@@ -63,14 +63,14 @@
 .azure-pipelines/             @AA-Turner
 
 # GitHub & related scripts
-.github/                                    @ezio-melotti @hugovk @AA-Turner @webknjaz @itamaro
+.github/                                    @ezio-melotti @hugovk @AA-Turner @webknjaz @itamaro @JacobCoffee
 Tools/build/compute-changes.py              @AA-Turner @hugovk @webknjaz
 Lib/test/test_tools/test_compute_changes.py @AA-Turner @hugovk @webknjaz
 Tools/build/verify_ensurepip_wheels.py      @AA-Turner @pfmoore @pradyunsg
 
 # Pre-commit
-.pre-commit-config.yaml       @hugovk
-.ruff.toml                    @hugovk @AlexWaygood @AA-Turner
+.pre-commit-config.yaml       @hugovk @JacobCoffee
+.ruff.toml                    @hugovk @AlexWaygood @AA-Turner @JacobCoffee
 
 # Patchcheck
 Tools/patchcheck/             @AA-Turner @itamaro

.github/workflows/build.yml

@@ -601,6 +601,9 @@ jobs:
         run: ./configure --prefix="$BUILD_DIR/cross-python" --with-build-python="$BUILD_DIR/host-python/bin/python3"
       - name: Install cross Python
         run: make -j8 install
+      - name: Display build info
+        run: |
+          "$BUILD_DIR/cross-python/bin/python3" -m test.pythoninfo
       - name: Run test subset with host build
         run: |
           "$BUILD_DIR/cross-python/bin/python3" -m test test_sysconfig test_site test_embed

.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/extension-modules.rst

@@ -100,11 +100,35 @@ For example, a module called ``spam`` would be defined like this::
 The export hook is typically the only non-\ ``static``
 item defined in the module's C source.
 
-The hook should be kept short -- ideally, one line as above.
-If you do need to use Python C API in this function, it is recommended to call
-``PyABIInfo_Check(&abi_info, "modulename")`` first to raise an exception,
-rather than crash, in common cases of ABI mismatch.
+.. _pymodexport-api-caveats:
 
+The hook should be kept short.
+If it does more than ``return`` a static array, several caveats apply:
+
+- If you need to use any Python C API, it is recommended to call
+  :c:func:`PyABIInfo_Check` first to raise an exception,
+  rather than crash, in common cases of ABI mismatch.
+- Code in the export hook must never rely on the :term:`GIL`:
+  :term:`free-threaded builds <free-threaded build>` of Python can only check
+  the :c:macro:`Py_mod_gil` slot (or the lack of it) after the hook returns,
+- Similarly, the hook may be called in any subinterpreter, since the
+  :c:macro:`Py_mod_multiple_interpreters` slot (or lack of it)
+  is only checked after the hook returns.
+
+For example::
+
+   PyMODEXPORT_FUNC
+   PyModExport_modulename(void)
+   {
+      if (PyABIInfo_Check(&abi_info, "modulename") < 0) {
+         /* ABI mismatch. It's not safe to examine the raised exception. */
+         return NULL;
+      }
+
+      /* use Python API (as little as possible); don't rely on GIL */
+
+      return modulename_slots;
+   }
 
 .. note::
 

Doc/c-api/import.rst

@@ -304,6 +304,11 @@ Importing Modules
 
       Initialization function for a module built into the interpreter.
 
+      Note that the inittab uses "``PyInit``"
+      :ref:`initialization functions <extension-pyinit>`;
+      there is currently no way to include "``PyModExport_``"
+      :ref:`export hooks <extension-export-hook>`.
+
 
 .. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
 

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`.)