Merge remote-tracking branch 'origin/3.13' into HEAD

# Conflicts:
#	Lib/test/datetimetester.py

Author: tonghuaroot

.github/workflows/build.yml

@@ -246,16 +246,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # macos-26 is Apple Silicon, macos-15-intel is Intel.
-        # macos-15-intel only runs tests against the GIL-enabled CPython.
+        # macos-26 is Apple Silicon, macos-26-intel is Intel.
+        # macos-26-intel only runs tests against the GIL-enabled CPython.
         os:
         - macos-26
-        - macos-15-intel
+        - macos-26-intel
         free-threading:
         - false
         - true
         exclude:
-        - os: macos-15-intel
+        - os: macos-26-intel
           free-threading: true
     uses: ./.github/workflows/reusable-macos.yml
     with:
@@ -351,7 +351,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Build and test
-        run: ./Android/android.py ci --fast-ci ${{ matrix.arch }}-linux-android
+        run: JAVA_HOME="${JAVA_HOME_21_X64:-$JAVA_HOME_21_arm64}" ./Android/android.py ci --fast-ci ${{ matrix.arch }}-linux-android
 
   build-wasi:
     name: 'WASI'
@@ -486,10 +486,6 @@ jobs:
       run: echo "::add-matcher::.github/problem-matchers/gcc.json"
     - name: Install dependencies
       run: sudo ./.github/workflows/posix-deps-apt.sh
-    - name: Set up GCC-10 for ASAN
-      uses: egor-tensin/setup-gcc@a2861a8b8538f49cf2850980acccf6b05a1b2ae4 # v2.0
-      with:
-        version: 10
     - name: Configure OpenSSL env vars
       run: |
         echo "MULTISSL_DIR=${GITHUB_WORKSPACE}/multissl" >> "$GITHUB_ENV"

.github/workflows/reusable-docs.yml

@@ -3,6 +3,17 @@ name: Reusable Docs
 on:
   workflow_call:
   workflow_dispatch:
+  # Pushes to CPython branches seed the pip caches under the exact keys every
+  # docs PR restores from. Without a branch-scoped copy, each PR saves a
+  # duplicate into its own refs/pull/N/merge scope that nothing else can read.
+  push:
+    branches:
+      - main
+      - '3.*'
+    paths:
+      - 'Doc/pylock.toml'
+      - 'Doc/requirements.txt'
+      - '.github/workflows/reusable-docs.yml'
 
 permissions:
   contents: read

.readthedocs.yml

@@ -11,24 +11,50 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3"
+  apt_packages:
+    - jq
 
-  commands:
-    # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
-    #
-    # Cancel building pull requests when there aren't changes in the Doc directory.
-    #
-    # If there are no changes (git diff exits with 0) we force the command to return with 183.
-    # This is a special exit code on Read the Docs that will cancel the build immediately.
-    - |
-      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && [ "$(git diff --quiet origin/main -- Doc/ .readthedocs.yml; echo $?)" -eq 0 ];
-      then
-        echo "No changes to Doc/ - exiting the build.";
-        exit 183;
-      fi
-
-    - asdf plugin add uv
-    - asdf install uv latest
-    - asdf global uv latest
-    - make -C Doc venv html
-    - mkdir _readthedocs
-    - mv Doc/build/html _readthedocs/html
+  jobs:
+    post_system_dependencies:
+      # https://docs.readthedocs.com/platform/stable/guides/build/skip-build.html#skip-builds-based-on-conditions
+      #
+      # Cancel building pull requests when there are no changes in the Doc
+      # directory or RTD configuration, or if we can't cleanly merge the base
+      # branch.
+      - |
+        set -eEux;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ];
+        then
+          base_branch=$(wget -qO- "https://api.github.com/repos/python/cpython/pulls/$READTHEDOCS_VERSION" | jq -er ".base.ref");
+          git fetch --depth=50 origin $base_branch:origin-$base_branch;
+          for attempt in $(seq 10);
+          do
+            if ! git merge-base HEAD origin-$base_branch;
+            then
+              git fetch --deepen=50 origin $base_branch;
+            else
+              break;
+            fi;
+          done;
+          if ! git -c "user.name=rtd" -c "user.email=no-reply@readthedocs.org" merge --no-stat --no-edit origin-$base_branch;
+          then
+            echo "Unsuccessful merge with '$base_branch' branch, skipping the build";
+            exit 183;
+          fi;
+          if git diff --exit-code --stat origin-$base_branch -- Doc/ .readthedocs.yml;
+          then
+            echo "No changes to Doc/ - skipping the build.";
+            exit 183;
+          fi;
+        fi;
+    create_environment:
+      - echo "Skipping default environment creation"
+    install:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    build:
+      html:
+        - make -C Doc venv html
+        - mkdir -p "$READTHEDOCS_OUTPUT"
+        - mv Doc/build/html "$READTHEDOCS_OUTPUT/"

Android/README.md

@@ -31,7 +31,8 @@ any packages it needs.
 The script also requires the following commands to be on the `PATH`:
 
 * `curl`
-* `java` (or set the `JAVA_HOME` environment variable)
+* `java` (or set the `JAVA_HOME` environment variable).
+  Java versions 17 and 21 are supported.
 
 
 ## Building

Doc/c-api/bytes.rst

@@ -176,10 +176,11 @@ called with a non-bytes parameter.
 .. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
 
    Create a new bytes object in *\*bytes* containing the contents of *newpart*
-   appended to *bytes*; the caller will own the new reference.  The reference to
-   the old value of *bytes* will be stolen.  If the new object cannot be
-   created, the old reference to *bytes* will still be discarded and the value
-   of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
+   appended to *bytes*; the caller will own the new reference.
+   The reference to the old value of *bytes* will be ":term:`stolen <steal>`".
+   If the new object cannot be created, the old reference to *bytes* will still
+   be "stolen", the value of *\*bytes* will be set to ``NULL``, and
+   the appropriate exception will be set.
 
 
 .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

Doc/c-api/dict.rst

@@ -84,8 +84,8 @@ Dictionary Objects
 
    Insert *val* into the dictionary *p* with a key of *key*.  *key* must be
    :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
-   ``0`` on success or ``-1`` on failure.  This function *does not* steal a
-   reference to *val*.
+   ``0`` on success or ``-1`` on failure.
+   This function *does not* ":term:`steal`" a reference to *val*.
 
 
 .. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

Doc/c-api/exceptions.rst

@@ -503,7 +503,8 @@ Querying the error indicator
 
    .. warning::
 
-      This call steals a reference to *exc*, which must be a valid exception.
+      This call ":term:`steals <steal>`" a reference to *exc*,
+      which must be a valid exception.
 
    .. versionadded:: 3.12
 
@@ -641,7 +642,8 @@ Querying the error indicator
 
    Set the exception info, as known from ``sys.exc_info()``.  This refers
    to an exception that was *already caught*, not to an exception that was
-   freshly raised.  This function steals the references of the arguments.
+   freshly raised.  This function ":term:`steals <steal>`" the references
+   of the arguments.
    To clear the exception state, pass ``NULL`` for all three arguments.
    This function is kept for backwards compatibility. Prefer using
    :c:func:`PyErr_SetHandledException`.
@@ -658,8 +660,8 @@ Querying the error indicator
    .. versionchanged:: 3.11
       The ``type`` and ``traceback`` arguments are no longer used and
       can be NULL. The interpreter now derives them from the exception
-      instance (the ``value`` argument). The function still steals
-      references of all three arguments.
+      instance (the ``value`` argument). The function still
+      ":term:`steals <steal>`" references of all three arguments.
 
 
 Signal Handling
@@ -845,7 +847,7 @@ Exception Objects
 
    Set the context associated with the exception to *ctx*.  Use ``NULL`` to clear
    it.  There is no type check to make sure that *ctx* is an exception instance.
-   This steals a reference to *ctx*.
+   This ":term:`steals <steal>`" a reference to *ctx*.
 
 
 .. c:function:: PyObject* PyException_GetCause(PyObject *ex)
@@ -860,7 +862,8 @@ Exception Objects
 
    Set the cause associated with the exception to *cause*.  Use ``NULL`` to clear
    it.  There is no type check to make sure that *cause* is either an exception
-   instance or ``None``.  This steals a reference to *cause*.
+   instance or ``None``.
+   This ":term:`steals <steal>`" a reference to *cause*.
 
    The :attr:`~BaseException.__suppress_context__` attribute is implicitly set
    to ``True`` by this function.

Doc/c-api/gen.rst

@@ -35,15 +35,15 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
 .. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
 
    Create and return a new generator object based on the *frame* object.
-   A reference to *frame* is stolen by this function. The argument must not be
-   ``NULL``.
+   A reference to *frame* is ":term:`stolen <steal>`" by this function (even
+   on error). The argument must not be ``NULL``.
 
 .. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
 
    Create and return a new generator object based on the *frame* object,
    with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
-   A reference to *frame* is stolen by this function.  The *frame* argument
-   must not be ``NULL``.
+   A reference to *frame* is ":term:`stolen <steal>`" by this function (even
+   on error).  The *frame* argument must not be ``NULL``.
 
 .. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen)
 
@@ -67,8 +67,9 @@ Asynchronous Generator Objects
 .. c:function:: PyObject *PyAsyncGen_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
 
    Create a new asynchronous generator wrapping *frame*, with ``__name__`` and
-   ``__qualname__`` set to *name* and *qualname*. *frame* is stolen by this
-   function and must not be ``NULL``.
+   ``__qualname__`` set to *name* and *qualname*.
+   *frame* is ":term:`stolen <steal>`" by this function (even on error) and
+   must not be ``NULL``.
 
    On success, this function returns a :term:`strong reference` to the
    new asynchronous generator. On failure, this function returns ``NULL``

Doc/c-api/intro.rst

@@ -592,9 +592,12 @@ the caller is said to *borrow* the reference. Nothing needs to be done for a
 
 Conversely, when a calling function passes in a reference to an  object, there
 are two possibilities: the function *steals* a  reference to the object, or it
-does not.  *Stealing a reference* means that when you pass a reference to a
-function, that function assumes that it now owns that reference, and you are not
-responsible for it any longer.
+does not.
+
+*Stealing a reference* means that when you pass a reference to a
+function, that function assumes that it now owns that reference.
+Since the new owner can use :c:func:`!Py_DECREF` at its discretion,
+you (the caller) must not use that reference after the call.
 
 .. index::
    single: PyList_SetItem (C function)

Doc/c-api/list.rst

@@ -88,8 +88,10 @@ List Objects
 
    .. note::
 
-      This function "steals" a reference to *item* and discards a reference to
-      an item already in the list at the affected position.
+      This function ":term:`steals <steal>`" a reference to *item*,
+      even on error.
+      On success, it discards a reference to an item already in the list
+      at the affected position (unless it was ``NULL``).
 
 
 .. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
@@ -103,7 +105,7 @@ List Objects
 
    .. note::
 
-      This macro "steals" a reference to *item*, and, unlike
+      This macro ":term:`steals <steal>`" a reference to *item*, and, unlike
       :c:func:`PyList_SetItem`, does *not* discard a reference to any item that
       is being replaced; any reference in *list* at position *i* will be
       leaked.