Merge branch 'main' into fix-issue-54873

.gitattributes

@@ -83,6 +83,7 @@ Include/opcode_ids.h                                generated
 Include/token.h                                     generated
 Lib/_opcode_metadata.py                             generated
 Lib/keyword.py                                      generated
+Lib/idlelib/help.html                               generated
 Lib/test/certdata/*.pem                             generated
 Lib/test/certdata/*.0                               generated
 Lib/test/levenshtein_examples.json                  generated

.github/dependabot.yml

@@ -12,6 +12,11 @@ updates:
         update-types:
           - "version-update:semver-minor"
           - "version-update:semver-patch"
+    cooldown:
+      # https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns
+      # Cooldowns protect against supply chain attacks by avoiding the
+      # highest-risk window immediately after new releases.
+      default-days: 14
   - package-ecosystem: "pip"
     directory: "/Tools/"
     schedule:
@@ -19,3 +24,5 @@ updates:
     labels:
       - "skip issue"
       - "skip news"
+    cooldown:
+      default-days: 14

.github/workflows/build.yml

@@ -109,20 +109,10 @@ jobs:
           python-version: '3.x'
       - name: Runner image version
         run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-      - name: Restore config.cache
-        uses: actions/cache@v4
-        with:
-          path: config.cache
-          # Include env.pythonLocation in key to avoid changes in environment when setup-python updates Python
-          key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ needs.build-context.outputs.config-hash }}-${{ env.pythonLocation }}
       - name: Install dependencies
         run: sudo ./.github/workflows/posix-deps-apt.sh
       - name: Add ccache to PATH
         run: echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-      - name: Configure ccache action
-        uses: hendrikmuhs/ccache-action@v1.2
-        with:
-          save: false
       - name: Configure CPython
         run: |
           # Build Python with the libpython dynamic library
@@ -215,7 +205,6 @@ jobs:
           free-threading: true
     uses: ./.github/workflows/reusable-macos.yml
     with:
-      config_hash: ${{ needs.build-context.outputs.config-hash }}
       free-threading: ${{ matrix.free-threading }}
       os: ${{ matrix.os }}
 
@@ -247,7 +236,6 @@ jobs:
           bolt: true
     uses: ./.github/workflows/reusable-ubuntu.yml
     with:
-      config_hash: ${{ needs.build-context.outputs.config-hash }}
       bolt-optimizations: ${{ matrix.bolt }}
       free-threading: ${{ matrix.free-threading }}
       os: ${{ matrix.os }}
@@ -278,11 +266,6 @@ jobs:
         persist-credentials: false
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ needs.build-context.outputs.config-hash }}
     - name: Register gcc problem matcher
       run: echo "::add-matcher::.github/problem-matchers/gcc.json"
     - name: Install dependencies
@@ -304,10 +287,6 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: Configure ccache action
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: false
     - name: Configure CPython
       run: ./configure CFLAGS="-fdiagnostics-format=json" --config-cache --enable-slower-safety --with-pydebug --with-openssl="$OPENSSL_DIR"
     - name: Build CPython
@@ -339,11 +318,6 @@ jobs:
         persist-credentials: false
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ needs.build-context.outputs.config-hash }}
     - name: Register gcc problem matcher
       run: echo "::add-matcher::.github/problem-matchers/gcc.json"
     - name: Install dependencies
@@ -370,10 +344,6 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: Configure ccache action
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: false
     - name: Configure CPython
       run: |
         ./configure CFLAGS="-fdiagnostics-format=json" \
@@ -442,8 +412,6 @@ jobs:
     needs: build-context
     if: needs.build-context.outputs.run-tests == 'true'
     uses: ./.github/workflows/reusable-wasi.yml
-    with:
-      config_hash: ${{ needs.build-context.outputs.config-hash }}
 
   test-hypothesis:
     name: "Hypothesis tests on Ubuntu"
@@ -479,10 +447,6 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: Configure ccache action
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: false
     - name: Setup directory envs for out-of-tree builds
       run: |
         echo "CPYTHON_RO_SRCDIR=$(realpath -m "${GITHUB_WORKSPACE}"/../cpython-ro-srcdir)" >> "$GITHUB_ENV"
@@ -493,11 +457,6 @@ jobs:
       run: sudo mount --bind -o ro "$GITHUB_WORKSPACE" "$CPYTHON_RO_SRCDIR"
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: ${{ env.CPYTHON_BUILDDIR }}/config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ needs.build-context.outputs.config-hash }}
     - name: Configure CPython out-of-tree
       working-directory: ${{ env.CPYTHON_BUILDDIR }}
       run: |
@@ -581,11 +540,6 @@ jobs:
         persist-credentials: false
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ needs.build-context.outputs.config-hash }}
     - name: Register gcc problem matcher
       run: echo "::add-matcher::.github/problem-matchers/gcc.json"
     - name: Install dependencies
@@ -611,11 +565,6 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: Configure ccache action
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: ${{ github.event_name == 'push' }}
-        max-size: "200M"
     - name: Configure CPython
       run: ./configure --config-cache --with-address-sanitizer --without-pymalloc
     - name: Build CPython
@@ -647,7 +596,6 @@ jobs:
     uses: ./.github/workflows/reusable-san.yml
     with:
       sanitizer: ${{ matrix.sanitizer }}
-      config_hash: ${{ needs.build-context.outputs.config-hash }}
       free-threading: ${{ matrix.free-threading }}
 
   cross-build-linux:
@@ -662,11 +610,6 @@ jobs:
           persist-credentials: false
       - name: Runner image version
         run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-      - name: Restore config.cache
-        uses: actions/cache@v4
-        with:
-          path: config.cache
-          key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ needs.build-context.outputs.config-hash }}
       - name: Register gcc problem matcher
         run: echo "::add-matcher::.github/problem-matchers/gcc.json"
       - name: Set build dir

.github/workflows/jit.yml

@@ -68,7 +68,7 @@ jobs:
           - true
           - false
         llvm:
-          - 19
+          - 21
         include:
           - target: i686-pc-windows-msvc/msvc
             architecture: Win32
@@ -138,7 +138,7 @@ jobs:
       fail-fast: false
       matrix:
         llvm:
-          - 19
+          - 21
     steps:
       - uses: actions/checkout@v4
         with:
@@ -166,7 +166,7 @@ jobs:
       fail-fast: false
       matrix:
         llvm:
-          - 19
+          - 21
     steps:
       - uses: actions/checkout@v4
         with:
@@ -183,3 +183,27 @@ jobs:
       - name: Run tests without optimizations
         run: |
           PYTHON_UOPS_OPTIMIZE=0 ./python -m test --multiprocess 0 --timeout 4500 --verbose2 --verbose3
+
+  tail-call-jit:
+    name: JIT with tail calling interpreter
+    needs: interpreter
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        llvm:
+          - 21
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build with JIT and tailcall
+        run: |
+          sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" ./llvm.sh ${{ matrix.llvm }}
+          export PATH="$(llvm-config-${{ matrix.llvm }} --bindir):$PATH"
+          CC=clang-${{ matrix.llvm }} ./configure --enable-experimental-jit --with-tail-call-interp --with-pydebug
+          make all --jobs 4

.github/workflows/reusable-context.yml

@@ -17,9 +17,6 @@ on:  # yamllint disable-line rule:truthy
       #        || 'falsy-branch'
       #   }}
       #
-      config-hash:
-        description: Config hash value for use in cache keys
-        value: ${{ jobs.compute-changes.outputs.config-hash }}  # str
       run-docs:
         description: Whether to build the docs
         value: ${{ jobs.compute-changes.outputs.run-docs }}  # bool
@@ -42,7 +39,6 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     outputs:
-      config-hash: ${{ steps.config-hash.outputs.hash }}
       run-ci-fuzz: ${{ steps.changes.outputs.run-ci-fuzz }}
       run-docs: ${{ steps.changes.outputs.run-docs }}
       run-tests: ${{ steps.changes.outputs.run-tests }}
@@ -100,8 +96,3 @@ jobs:
         GITHUB_EVENT_NAME: ${{ github.event_name }}
         CCF_TARGET_REF: ${{ github.base_ref || github.event.repository.default_branch }}
         CCF_HEAD_REF: ${{ github.event.pull_request.head.sha || github.sha }}
-
-    - name: Compute hash for config cache key
-      id: config-hash
-      run: |
-        echo "hash=${{ hashFiles('configure', 'configure.ac', '.github/workflows/build.yml') }}" >> "$GITHUB_OUTPUT"

.github/workflows/reusable-macos.yml

@@ -3,9 +3,6 @@ name: Reusable macOS
 on:
   workflow_call:
     inputs:
-      config_hash:
-        required: true
-        type: string
       free-threading:
         required: false
         type: boolean
@@ -36,11 +33,6 @@ jobs:
         persist-credentials: false
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ inputs.config_hash }}
     - name: Install Homebrew dependencies
       run: |
         brew install pkg-config openssl@3.0 xz gdbm tcl-tk@9 make

.github/workflows/reusable-san.yml

@@ -6,9 +6,6 @@ on:
       sanitizer:
         required: true
         type: string
-      config_hash:
-        required: true
-        type: string
       free-threading:
         description: Whether to use free-threaded mode
         required: false
@@ -34,11 +31,6 @@ jobs:
         persist-credentials: false
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ inputs.sanitizer }}-${{ inputs.config_hash }}
     - name: Install dependencies
       run: |
         sudo ./.github/workflows/posix-deps-apt.sh
@@ -77,11 +69,6 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: Configure ccache action
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: ${{ github.event_name == 'push' }}
-        max-size: "200M"
     - name: Configure CPython
       run: >-
         ./configure

.github/workflows/reusable-ubuntu.yml

@@ -3,9 +3,6 @@ name: Reusable Ubuntu
 on:
   workflow_call:
     inputs:
-      config_hash:
-        required: true
-        type: string
       bolt-optimizations:
         description: Whether to enable BOLT optimizations
         required: false
@@ -64,11 +61,6 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: Configure ccache action
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: ${{ github.event_name == 'push' }}
-        max-size: "200M"
     - name: Setup directory envs for out-of-tree builds
       run: |
         echo "CPYTHON_RO_SRCDIR=$(realpath -m "${GITHUB_WORKSPACE}"/../cpython-ro-srcdir)" >> "$GITHUB_ENV"
@@ -79,11 +71,6 @@ jobs:
       run: sudo mount --bind -o ro "$GITHUB_WORKSPACE" "$CPYTHON_RO_SRCDIR"
     - name: Runner image version
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Restore config.cache
-      uses: actions/cache@v4
-      with:
-        path: ${{ env.CPYTHON_BUILDDIR }}/config.cache
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ inputs.config_hash }}
     - name: Configure CPython out-of-tree
       working-directory: ${{ env.CPYTHON_BUILDDIR }}
       # `test_unpickle_module_race` writes to the source directory, which is

.github/workflows/reusable-wasi.yml

@@ -2,10 +2,6 @@ name: Reusable WASI
 
 on:
   workflow_call:
-    inputs:
-      config_hash:
-        required: true
-        type: string
 
 env:
   FORCE_COLOR: 1
@@ -17,7 +13,7 @@ jobs:
     timeout-minutes: 60
     env:
       WASMTIME_VERSION: 38.0.3
-      WASI_SDK_VERSION: 25
+      WASI_SDK_VERSION: 29
       WASI_SDK_PATH: /opt/wasi-sdk
       CROSS_BUILD_PYTHON: cross-build/build
       CROSS_BUILD_WASI: cross-build/wasm32-wasip1
@@ -42,11 +38,6 @@ jobs:
         mkdir "${WASI_SDK_PATH}" && \
         curl -s -S --location "https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_SDK_VERSION}/wasi-sdk-${WASI_SDK_VERSION}.0-arm64-linux.tar.gz" | \
         tar --strip-components 1 --directory "${WASI_SDK_PATH}" --extract --gunzip
-    - name: "Configure ccache action"
-      uses: hendrikmuhs/ccache-action@v1.2
-      with:
-        save: ${{ github.event_name == 'push' }}
-        max-size: "200M"
     - name: "Add ccache to PATH"
       run: echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
     - name: "Install Python"
@@ -55,29 +46,15 @@ jobs:
         python-version: '3.x'
     - name: "Runner image version"
       run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: "Restore Python build config.cache"
-      uses: actions/cache@v4
-      with:
-        path: ${{ env.CROSS_BUILD_PYTHON }}/config.cache
-        # Include env.pythonLocation in key to avoid changes in environment when setup-python updates Python.
-        # Include the hash of `Tools/wasm/wasi.py` as it may change the environment variables.
-        # (Make sure to keep the key in sync with the other config.cache step below.)
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ env.WASI_SDK_VERSION }}-${{ env.WASMTIME_VERSION }}-${{ inputs.config_hash }}-${{ hashFiles('Tools/wasm/wasi.py') }}-${{ env.pythonLocation }}
     - name: "Configure build Python"
-      run: python3 Tools/wasm/wasi.py configure-build-python -- --config-cache --with-pydebug
+      run: python3 Tools/wasm/wasi configure-build-python -- --config-cache --with-pydebug
     - name: "Make build Python"
-      run: python3 Tools/wasm/wasi.py make-build-python
+      run: python3 Tools/wasm/wasi make-build-python
-    - name: "Restore host config.cache"
-      uses: actions/cache@v4
-      with:
-        path: ${{ env.CROSS_BUILD_WASI }}/config.cache
-        # Should be kept in sync with the other config.cache step above.
-        key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ env.WASI_SDK_VERSION }}-${{ env.WASMTIME_VERSION }}-${{ inputs.config_hash }}-${{ hashFiles('Tools/wasm/wasi.py') }}-${{ env.pythonLocation }}
     - name: "Configure host"
       # `--with-pydebug` inferred from configure-build-python
-      run: python3 Tools/wasm/wasi.py configure-host -- --config-cache
+      run: python3 Tools/wasm/wasi configure-host -- --config-cache
     - name: "Make host"
-      run: python3 Tools/wasm/wasi.py make-host
+      run: python3 Tools/wasm/wasi make-host
     - name: "Display build info"
       run: make --directory "${CROSS_BUILD_WASI}" pythoninfo
     - name: "Test"

.gitignore

@@ -135,7 +135,6 @@ Tools/unicode/data/
 /config.log
 /config.status
 /config.status.lineno
-# hendrikmuhs/ccache-action@v1
 /.ccache
 /cross-build/
 /jit_stencils*.h

.pre-commit-config.yaml

@@ -2,6 +2,10 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.13.2
     hooks:
+      - id: ruff-check
+        name: Run Ruff (lint) on Apple/
+        args: [--exit-non-zero-on-fix, --config=Apple/.ruff.toml]
+        files: ^Apple/
       - id: ruff-check
         name: Run Ruff (lint) on Doc/
         args: [--exit-non-zero-on-fix]
@@ -30,6 +34,10 @@ repos:
         name: Run Ruff (lint) on Tools/wasm/
         args: [--exit-non-zero-on-fix, --config=Tools/wasm/.ruff.toml]
         files: ^Tools/wasm/
+      - id: ruff-format
+        name: Run Ruff (format) on Apple/
+        args: [--exit-non-zero-on-fix, --config=Apple/.ruff.toml]
+        files: ^Apple
       - id: ruff-format
         name: Run Ruff (format) on Doc/
         args: [--check]

Apple/.ruff.toml

@@ -0,0 +1,22 @@
+extend = "../.ruff.toml"  # Inherit the project-wide settings
+
+[format]
+preview = true
+docstring-code-format = true
+
+[lint]
+select = [
+    "C4",      # flake8-comprehensions
+    "E",       # pycodestyle
+    "F",       # pyflakes
+    "I",       # isort
+    "ISC",     # flake8-implicit-str-concat
+    "LOG",     # flake8-logging
+    "PGH",     # pygrep-hooks
+    "PT",      # flake8-pytest-style
+    "PYI",     # flake8-pyi
+    "RUF100",  # Ban unused `# noqa` comments
+    "UP",      # pyupgrade
+    "W",       # pycodestyle
+    "YTT",     # flake8-2020
+]

Apple/__main__.py

@@ -46,13 +46,12 @@
 import sys
 import sysconfig
 import time
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from contextlib import contextmanager
 from datetime import datetime, timezone
 from os.path import basename, relpath
 from pathlib import Path
 from subprocess import CalledProcessError
-from typing import Callable
 
 EnvironmentT = dict[str, str]
 ArgsT = Sequence[str | Path]
@@ -140,17 +139,15 @@ def print_env(env: EnvironmentT) -> None:
 def apple_env(host: str) -> EnvironmentT:
     """Construct an Apple development environment for the given host."""
     env = {
-        "PATH": ":".join(
+        "PATH": ":".join([
-            [
+            str(PYTHON_DIR / "Apple/iOS/Resources/bin"),
-                str(PYTHON_DIR / "Apple/iOS/Resources/bin"),
+            str(subdir(host) / "prefix"),
-                str(subdir(host) / "prefix"),
+            "/usr/bin",
-                "/usr/bin",
+            "/bin",
-                "/bin",
+            "/usr/sbin",
-                "/usr/sbin",
+            "/sbin",
-                "/sbin",
+            "/Library/Apple/usr/bin",
-                "/Library/Apple/usr/bin",
+        ]),
-            ]
-        ),
     }
 
     return env
@@ -196,14 +193,10 @@ def clean(context: argparse.Namespace, target: str = "all") -> None:
         paths.append(target)
 
     if target in {"all", "hosts", "test"}:
-        paths.extend(
+        paths.extend([
-            [
+            path.name
-                path.name
+            for path in CROSS_BUILD_DIR.glob(f"{context.platform}-testbed.*")
-                for path in CROSS_BUILD_DIR.glob(
+        ])
-                    f"{context.platform}-testbed.*"
-                )
-            ]
-        )
 
     for path in paths:
         delete_path(path)
@@ -352,18 +345,16 @@ def download(url: str, target_dir: Path) -> Path:
 
     out_path = target_path / basename(url)
     if not Path(out_path).is_file():
-        run(
+        run([
-            [
+            "curl",
-                "curl",
+            "-Lf",
-                "-Lf",
+            "--retry",
-                "--retry",
+            "5",
-                "5",
+            "--retry-all-errors",
-                "--retry-all-errors",
+            "-o",
-                "-o",
+            out_path,
-                out_path,
+            url,
-                url,
+        ])
-            ]
-        )
     else:
         print(f"Using cached version of {basename(url)}")
     return out_path
@@ -468,8 +459,7 @@ def package_version(prefix_path: Path) -> str:
 
 
 def lib_platform_files(dirname, names):
-    """A file filter that ignores platform-specific files in the lib directory.
+    """A file filter that ignores platform-specific files in lib."""
-    """
     path = Path(dirname)
     if (
         path.parts[-3] == "lib"
@@ -478,7 +468,7 @@ def lib_platform_files(dirname, names):
     ):
         return names
     elif path.parts[-2] == "lib" and path.parts[-1].startswith("python"):
-        ignored_names = set(
+        ignored_names = {
             name
             for name in names
             if (
@@ -486,7 +476,13 @@ def lib_platform_files(dirname, names):
                 or name.startswith("_sysconfig_vars_")
                 or name == "build-details.json"
             )
-        )
+        }
+    elif path.parts[-1] == "lib":
+        ignored_names = {
+            name
+            for name in names
+            if name.startswith("libpython") and name.endswith(".dylib")
+        }
     else:
         ignored_names = set()
 
@@ -499,7 +495,9 @@ def lib_non_platform_files(dirname, names):
     """
     path = Path(dirname)
     if path.parts[-2] == "lib" and path.parts[-1].startswith("python"):
-        return set(names) - lib_platform_files(dirname, names) - {"lib-dynload"}
+        return (
+            set(names) - lib_platform_files(dirname, names) - {"lib-dynload"}
+        )
     else:
         return set()
 
@@ -507,14 +505,15 @@ def lib_non_platform_files(dirname, names):
 def create_xcframework(platform: str) -> str:
     """Build an XCframework from the component parts for the platform.
 
-    :return: The version number of the Python verion that was packaged.
+    :return: The version number of the Python version that was packaged.
     """
     package_path = CROSS_BUILD_DIR / platform
     try:
         package_path.mkdir()
     except FileExistsError:
         raise RuntimeError(
-            f"{platform} XCframework already exists; do you need to run with --clean?"
+            f"{platform} XCframework already exists; do you need to run "
+            "with --clean?"
         ) from None
 
     frameworks = []
@@ -607,7 +606,7 @@ def create_xcframework(platform: str) -> str:
         print(f" - {slice_name} binaries")
         shutil.copytree(first_path / "bin", slice_path / "bin")
 
-        # Copy the include path (this will be a symlink to the framework headers)
+        # Copy the include path (a symlink to the framework headers)
         print(f" - {slice_name} include files")
         shutil.copytree(
             first_path / "include",
@@ -621,6 +620,12 @@ def create_xcframework(platform: str) -> str:
             slice_framework / "Headers/pyconfig.h",
         )
 
+        print(f" - {slice_name} shared library")
+        # Create a simlink for the fat library
+        shared_lib = slice_path / f"lib/libpython{version_tag}.dylib"
+        shared_lib.parent.mkdir()
+        shared_lib.symlink_to("../Python.framework/Python")
+
         print(f" - {slice_name} architecture-specific files")
         for host_triple, multiarch in slice_parts.items():
             print(f"   - {multiarch} standard library")
@@ -632,6 +637,7 @@ def create_xcframework(platform: str) -> str:
                     framework_path(host_triple, multiarch) / "lib",
                     package_path / "Python.xcframework/lib",
                     ignore=lib_platform_files,
+                    symlinks=True,
                 )
                 has_common_stdlib = True
 
@@ -639,6 +645,7 @@ def create_xcframework(platform: str) -> str:
                 framework_path(host_triple, multiarch) / "lib",
                 slice_path / f"lib-{arch}",
                 ignore=lib_non_platform_files,
+                symlinks=True,
             )
 
             # Copy the host's pyconfig.h to an architecture-specific name.
@@ -659,7 +666,8 @@ def create_xcframework(platform: str) -> str:
             # statically link those libraries into a Framework, you become
             # responsible for providing a privacy manifest for that framework.
             xcprivacy_file = {
-                "OpenSSL": subdir(host_triple) / "prefix/share/OpenSSL.xcprivacy"
+                "OpenSSL": subdir(host_triple)
+                / "prefix/share/OpenSSL.xcprivacy"
             }
             print(f"   - {multiarch} xcprivacy files")
             for module, lib in [
@@ -669,7 +677,8 @@ def create_xcframework(platform: str) -> str:
                 shutil.copy(
                     xcprivacy_file[lib],
                     slice_path
-                    / f"lib-{arch}/python{version_tag}/lib-dynload/{module}.xcprivacy",
+                    / f"lib-{arch}/python{version_tag}"
+                    / f"lib-dynload/{module}.xcprivacy",
                 )
 
     print(" - build tools")
@@ -692,18 +701,16 @@ def package(context: argparse.Namespace) -> None:
 
         # Clone testbed
         print()
-        run(
+        run([
-            [
+            sys.executable,
-                sys.executable,
+            "Apple/testbed",
-                "Apple/testbed",
+            "clone",
-                "clone",
+            "--platform",
-                "--platform",
+            context.platform,
-                context.platform,
+            "--framework",
-                "--framework",
+            CROSS_BUILD_DIR / context.platform / "Python.xcframework",
-                CROSS_BUILD_DIR / context.platform / "Python.xcframework",
+            CROSS_BUILD_DIR / context.platform / "testbed",
-                CROSS_BUILD_DIR / context.platform / "testbed",
+        ])
-            ]
-        )
 
         # Build the final archive
         archive_name = (
@@ -757,7 +764,7 @@ def build(context: argparse.Namespace, host: str | None = None) -> None:
         package(context)
 
 
-def test(context: argparse.Namespace, host: str | None = None) -> None:
+def test(context: argparse.Namespace, host: str | None = None) -> None:  # noqa: PT028
     """The implementation of the "test" command."""
     if host is None:
         host = context.host
@@ -795,18 +802,16 @@ def test(context: argparse.Namespace, host: str | None = None) -> None:
                     / f"Frameworks/{apple_multiarch(host)}"
                 )
 
-        run(
+        run([
-            [
+            sys.executable,
-                sys.executable,
+            "Apple/testbed",
-                "Apple/testbed",
+            "clone",
-                "clone",
+            "--platform",
-                "--platform",
+            context.platform,
-                context.platform,
+            "--framework",
-                "--framework",
+            framework_path,
-                framework_path,
+            testbed_dir,
-                testbed_dir,
+        ])
-            ]
-        )
 
         run(
             [
@@ -840,7 +845,7 @@ def apple_sim_host(platform_name: str) -> str:
     """Determine the native simulator target for this platform."""
     for _, slice_parts in HOSTS[platform_name].items():
         for host_triple in slice_parts:
-            parts = host_triple.split('-')
+            parts = host_triple.split("-")
             if parts[0] == platform.machine() and parts[-1] == "simulator":
                 return host_triple
 
@@ -968,20 +973,29 @@ def parse_args() -> argparse.Namespace:
         cmd.add_argument(
             "--simulator",
             help=(
-                "The name of the simulator to use (eg: 'iPhone 16e'). Defaults to "
+                "The name of the simulator to use (eg: 'iPhone 16e'). "
-                "the most recently released 'entry level' iPhone device. Device "
+                "Defaults to the most recently released 'entry level' "
-                "architecture and OS version can also be specified; e.g., "
+                "iPhone device. Device architecture and OS version can also "
-                "`--simulator 'iPhone 16 Pro,arch=arm64,OS=26.0'` would run on "
+                "be specified; e.g., "
-                "an ARM64 iPhone 16 Pro simulator running iOS 26.0."
+                "`--simulator 'iPhone 16 Pro,arch=arm64,OS=26.0'` would "
+                "run on an ARM64 iPhone 16 Pro simulator running iOS 26.0."
             ),
         )
         group = cmd.add_mutually_exclusive_group()
         group.add_argument(
-            "--fast-ci", action="store_const", dest="ci_mode", const="fast",
+            "--fast-ci",
-            help="Add test arguments for GitHub Actions")
+            action="store_const",
+            dest="ci_mode",
+            const="fast",
+            help="Add test arguments for GitHub Actions",
+        )
         group.add_argument(
-            "--slow-ci", action="store_const", dest="ci_mode", const="slow",
+            "--slow-ci",
-            help="Add test arguments for buildbots")
+            action="store_const",
+            dest="ci_mode",
+            const="slow",
+            help="Add test arguments for buildbots",
+        )
 
     for subcommand in [configure_build, configure_host, build, ci]:
         subcommand.add_argument(

Apple/testbed/Python.xcframework/build/utils.sh

@@ -46,7 +46,8 @@ install_stdlib() {
         rsync -au --delete "$PROJECT_DIR/$PYTHON_XCFRAMEWORK_PATH/lib/" "$CODESIGNING_FOLDER_PATH/python/lib/"
         rsync -au "$PROJECT_DIR/$PYTHON_XCFRAMEWORK_PATH/$SLICE_FOLDER/lib-$ARCHS/" "$CODESIGNING_FOLDER_PATH/python/lib/"
     else
-        rsync -au --delete "$PROJECT_DIR/$PYTHON_XCFRAMEWORK_PATH/$SLICE_FOLDER/lib/" "$CODESIGNING_FOLDER_PATH/python/lib/"
+        # A single-arch framework will have a libpython symlink; that can't be included at runtime
+        rsync -au --delete "$PROJECT_DIR/$PYTHON_XCFRAMEWORK_PATH/$SLICE_FOLDER/lib/" "$CODESIGNING_FOLDER_PATH/python/lib/" --exclude 'libpython*.dylib'
     fi
 }
 

Apple/testbed/__main__.py

@@ -2,6 +2,7 @@
 import json
 import os
 import re
+import shlex
 import shutil
 import subprocess
 import sys
@@ -31,15 +32,15 @@ def select_simulator_device(platform):
     json_data = json.loads(raw_json)
 
     if platform == "iOS":
-        # Any iOS device will do; we'll look for "SE" devices - but the name isn't
+        # Any iOS device will do; we'll look for "SE" devices - but the name
-        # consistent over time. Older Xcode versions will use "iPhone SE (Nth
+        # isn't consistent over time. Older Xcode versions will use "iPhone SE
-        # generation)"; As of 2025, they've started using "iPhone 16e".
+        # (Nth generation)"; As of 2025, they've started using "iPhone 16e".
         #
-        # When Xcode is updated after a new release, new devices will be available
+        # When Xcode is updated after a new release, new devices will be
-        # and old ones will be dropped from the set available on the latest iOS
+        # available and old ones will be dropped from the set available on the
-        # version. Select the one with the highest minimum runtime version - this
+        # latest iOS version. Select the one with the highest minimum runtime
-        # is an indicator of the "newest" released device, which should always be
+        # version - this is an indicator of the "newest" released device, which
-        # supported on the "most recent" iOS version.
+        # should always be supported on the "most recent" iOS version.
         se_simulators = sorted(
             (devicetype["minRuntimeVersion"], devicetype["name"])
             for devicetype in json_data["devicetypes"]
@@ -252,7 +253,7 @@ def update_test_plan(testbed_path, platform, args):
         test_plan = json.load(f)
 
     test_plan["defaultOptions"]["commandLineArgumentEntries"] = [
-        {"argument": arg} for arg in args
+        {"argument": shlex.quote(arg)} for arg in args
     ]
 
     with test_plan_path.open("w", encoding="utf-8") as f:
@@ -294,7 +295,8 @@ def main():
 
     parser = argparse.ArgumentParser(
         description=(
-            "Manages the process of testing an Apple Python project through Xcode."
+            "Manages the process of testing an Apple Python project "
+            "through Xcode."
         ),
     )
 
@@ -335,7 +337,10 @@ def main():
 
     run = subcommands.add_parser(
         "run",
-        usage="%(prog)s [-h] [--simulator SIMULATOR] -- <test arg> [<test arg> ...]",
+        usage=(
+            "%(prog)s [-h] [--simulator SIMULATOR] -- "
+            "<test arg> [<test arg> ...]"
+        ),
         description=(
             "Run a testbed project. The arguments provided after `--` will be "
             "passed to the running iOS process as if they were arguments to "
@@ -396,9 +401,9 @@ def main():
                 / "bin"
             ).is_dir():
                 print(
-                    f"Testbed does not contain a compiled Python framework. Use "
+                    "Testbed does not contain a compiled Python framework. "
-                    f"`python {sys.argv[0]} clone ...` to create a runnable "
+                    f"Use `python {sys.argv[0]} clone ...` to create a "
-                    f"clone of this testbed."
+                    "runnable clone of this testbed."
                 )
                 sys.exit(20)
 
@@ -410,7 +415,8 @@ def main():
             )
         else:
             print(
-                f"Must specify test arguments (e.g., {sys.argv[0]} run -- test)"
+                "Must specify test arguments "
+                f"(e.g., {sys.argv[0]} run -- test)"
             )
             print()
             parser.print_help(sys.stderr)

Doc/Makefile

@@ -241,7 +241,8 @@ dist-pdf:
 	# as otherwise the full latexmk process is run twice.
 	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
 	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
-	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
+	if [ -n "$(filter output-sync,$(value .FEATURES))" ]; then OUTPUTSYNC=--output-sync; else OUTPUTSYNC=; fi && \
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`getconf _NPROCESSORS_ONLN`+1)) $$OUTPUTSYNC LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 	@echo "Build finished and archived!"

Doc/c-api/allocation.rst

@@ -140,10 +140,6 @@ Allocating Objects on the Heap
       * :c:member:`~PyTypeObject.tp_alloc`
 
 
-.. c:function:: void PyObject_Del(void *op)
-
-   Same as :c:func:`PyObject_Free`.
-
 .. c:var:: PyObject _Py_NoneStruct
 
    Object which is visible in Python as ``None``.  This should only be accessed
@@ -156,3 +152,35 @@ Allocating Objects on the Heap
    :ref:`moduleobjects`
       To allocate and create extension modules.
 
+
+Deprecated aliases
+^^^^^^^^^^^^^^^^^^
+
+These are :term:`soft deprecated` aliases to existing functions and macros.
+They exist solely for backwards compatibility.
+
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * Deprecated alias
+     * Function
+   * * .. c:macro:: PyObject_NEW(type, typeobj)
+     * :c:macro:`PyObject_New`
+   * * .. c:macro:: PyObject_NEW_VAR(type, typeobj, n)
+     * :c:macro:`PyObject_NewVar`
+   * * .. c:macro:: PyObject_INIT(op, typeobj)
+     * :c:func:`PyObject_Init`
+   * * .. c:macro:: PyObject_INIT_VAR(op, typeobj, n)
+     * :c:func:`PyObject_InitVar`
+   * * .. c:macro:: PyObject_MALLOC(n)
+     * :c:func:`PyObject_Malloc`
+   * * .. c:macro:: PyObject_REALLOC(p, n)
+     * :c:func:`PyObject_Realloc`
+   * * .. c:macro:: PyObject_FREE(p)
+     * :c:func:`PyObject_Free`
+   * * .. c:macro:: PyObject_DEL(p)
+     * :c:func:`PyObject_Free`
+   * * .. c:macro:: PyObject_Del(p)
+     * :c:func:`PyObject_Free`

Doc/c-api/buffer.rst

@@ -261,6 +261,10 @@ readonly, format
       MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE | PyBUF_WRITABLE`
       can be used to request a simple writable buffer.
 
+   .. c:macro:: PyBUF_WRITEABLE
+
+      This is a :term:`soft deprecated` alias to :c:macro:`PyBUF_WRITABLE`.
+
    .. c:macro:: PyBUF_FORMAT
 
       Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST

Doc/c-api/bytes.rst

@@ -228,6 +228,42 @@ called with a non-bytes parameter.
       The function is :term:`soft deprecated`,
       use the :c:type:`PyBytesWriter` API instead.
 
+
+.. c:function:: PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
+
+   Get the string representation of *bytes*. This function is currently used to
+   implement :meth:`!bytes.__repr__` in Python.
+
+   This function does not do type checking; it is undefined behavior to pass
+   *bytes* as a non-bytes object or ``NULL``.
+
+   If *smartquotes* is true, the representation will use a double-quoted string
+   instead of single-quoted string when single-quotes are present in *bytes*.
+   For example, the byte string ``'Python'`` would be represented as
+   ``b"'Python'"`` when *smartquotes* is true, or ``b'\'Python\''`` when it is
+   false.
+
+   On success, this function returns a :term:`strong reference` to a
+   :class:`str` object containing the representation. On failure, this
+   returns ``NULL`` with an exception set.
+
+
+.. c:function:: PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)
+
+   Unescape a backslash-escaped string *s*. *s* must not be ``NULL``.
+   *len* must be the size of *s*.
+
+   *errors* must be one of ``"strict"``, ``"replace"``, or ``"ignore"``. If
+   *errors* is ``NULL``, then ``"strict"`` is used by default.
+
+   On success, this function returns a :term:`strong reference` to a Python
+   :class:`bytes` object containing the unescaped string. On failure, this
+   function returns ``NULL`` with an exception set.
+
+   .. versionchanged:: 3.9
+      *unicode* and *recode_encoding* are now unused.
+
+
 .. _pybyteswriter:
 
 PyBytesWriter

Doc/c-api/capsule.rst

@@ -22,6 +22,12 @@ Refer to :ref:`using-capsules` for more information on using these objects.
    loaded modules.
 
 
+.. c:var:: PyTypeObject PyCapsule_Type
+
+   The type object corresponding to capsule objects. This is the same object
+   as :class:`types.CapsuleType` in the Python layer.
+
+
 .. c:type:: PyCapsule_Destructor
 
    The type of a destructor callback for a capsule.  Defined as::

Doc/c-api/cell.rst

@@ -7,7 +7,7 @@ Cell Objects
 
 "Cell" objects are used to implement variables referenced by multiple scopes.
 For each such variable, a cell object is created to store the value; the local
-variables of each stack frame that references the value contains a reference to
+variables of each stack frame that references the value contain a reference to
 the cells from outer scopes which also use that variable.  When the value is
 accessed, the value contained in the cell is used instead of the cell object
 itself.  This de-referencing of the cell object requires support from the

Doc/c-api/code.rst

@@ -211,6 +211,17 @@ bound into a function.
    .. versionadded:: 3.12
 
 
+.. c:function:: PyObject *PyCode_Optimize(PyObject *code, PyObject *consts, PyObject *names, PyObject *lnotab_obj)
+
+   This is a :term:`soft deprecated` function that does nothing.
+
+   Prior to Python 3.10, this function would perform basic optimizations to a
+   code object.
+
+   .. versionchanged:: 3.10
+      This function now does nothing.
+
+
 .. _c_codeobject_flags:
 
 Code Object Flags

Doc/c-api/codec.rst

@@ -129,3 +129,13 @@ Registry API for Unicode encoding error handlers
    Replace the unicode encode error with ``\N{...}`` escapes.
 
    .. versionadded:: 3.5
+
+
+Codec utility variables
+-----------------------
+
+.. c:var:: const char *Py_hexdigits
+
+   A string constant containing the lowercase hexadecimal digits: ``"0123456789abcdef"``.
+
+   .. versionadded:: 3.3

Doc/c-api/complex.rst

@@ -82,7 +82,7 @@ Complex Number Objects
 
 .. c:type:: Py_complex
 
-   This C structure defines export format for a Python complex
+   This C structure defines an export format for a Python complex
    number object.
 
    .. c:member:: double real

Doc/c-api/concrete.rst

@@ -109,11 +109,20 @@ Other Objects
    descriptor.rst
    slice.rst
    memoryview.rst
+   picklebuffer.rst
    weakref.rst
    capsule.rst
    frame.rst
    gen.rst
    coro.rst
    contextvars.rst
-   datetime.rst
    typehints.rst
+
+
+C API for extension modules
+===========================
+
+.. toctree::
+
+   curses.rst
+   datetime.rst

Doc/c-api/conversion.rst

@@ -105,7 +105,7 @@ The following functions provide locale-independent string to number conversions.
 
    If ``s`` represents a value that is too large to store in a float
    (for example, ``"1e500"`` is such a string on many platforms) then
-   if ``overflow_exception`` is ``NULL`` return ``Py_INFINITY`` (with
+   if ``overflow_exception`` is ``NULL`` return :c:macro:`!INFINITY` (with
    an appropriate sign) and don't set any exception.  Otherwise,
    ``overflow_exception`` must point to a Python exception object;
    raise that exception and return ``-1.0``.  In both cases, set
@@ -128,18 +128,28 @@ The following functions provide locale-independent string to number conversions.
    must be 0 and is ignored.  The ``'r'`` format code specifies the
    standard :func:`repr` format.
 
-   *flags* can be zero or more of the values ``Py_DTSF_SIGN``,
+   *flags* can be zero or more of the following values or-ed together:
-   ``Py_DTSF_ADD_DOT_0``, or ``Py_DTSF_ALT``, or-ed together:
 
-   * ``Py_DTSF_SIGN`` means to always precede the returned string with a sign
+   .. c:macro:: Py_DTSF_SIGN
-     character, even if *val* is non-negative.
 
-   * ``Py_DTSF_ADD_DOT_0`` means to ensure that the returned string will not look
+      Always precede the returned string with a sign
-     like an integer.
+      character, even if *val* is non-negative.
 
-   * ``Py_DTSF_ALT`` means to apply "alternate" formatting rules.  See the
+   .. c:macro:: Py_DTSF_ADD_DOT_0
-     documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
+
-     details.
+      Ensure that the returned string will not look like an integer.
+
+   .. c:macro:: Py_DTSF_ALT
+
+      Apply "alternate" formatting rules.
+      See the documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
+      details.
+
+   .. c:macro:: Py_DTSF_NO_NEG_0
+
+      Negative zero is converted to positive zero.
+
+      .. versionadded:: 3.11
 
    If *ptype* is non-``NULL``, then the value it points to will be set to one of
    ``Py_DTST_FINITE``, ``Py_DTST_INFINITE``, or ``Py_DTST_NAN``, signifying that
@@ -162,3 +172,58 @@ The following functions provide locale-independent string to number conversions.
 
    Case insensitive comparison of strings. The function works almost
    identically to :c:func:`!strncmp` except that it ignores the case.
+
+
+Character classification and conversion
+=======================================
+
+The following macros provide locale-independent (unlike the C standard library
+``ctype.h``) character classification and conversion.
+The argument must be a signed or unsigned :c:expr:`char`.
+
+
+.. c:macro:: Py_ISALNUM(c)
+
+   Return true if the character *c* is an alphanumeric character.
+
+
+.. c:macro:: Py_ISALPHA(c)
+
+   Return true if the character *c* is an alphabetic character (``a-z`` and ``A-Z``).
+
+
+.. c:macro:: Py_ISDIGIT(c)
+
+   Return true if the character *c* is a decimal digit (``0-9``).
+
+
+.. c:macro:: Py_ISLOWER(c)
+
+   Return true if the character *c* is a lowercase ASCII letter (``a-z``).
+
+
+.. c:macro:: Py_ISUPPER(c)
+
+   Return true if the character *c* is an uppercase ASCII letter (``A-Z``).
+
+
+.. c:macro:: Py_ISSPACE(c)
+
+   Return true if the character *c* is a whitespace character (space, tab,
+   carriage return, newline, vertical tab, or form feed).
+
+
+.. c:macro:: Py_ISXDIGIT(c)
+
+   Return true if the character *c* is a hexadecimal digit (``0-9``, ``a-f``, and
+   ``A-F``).
+
+
+.. c:macro:: Py_TOLOWER(c)
+
+   Return the lowercase equivalent of the character *c*.
+
+
+.. c:macro:: Py_TOUPPER(c)
+
+   Return the uppercase equivalent of the character *c*.

Doc/c-api/curses.rst

@@ -0,0 +1,138 @@
+.. highlight:: c
+
+Curses C API
+------------
+
+:mod:`curses` exposes a small C interface for extension modules.
+Consumers must include the header file :file:`py_curses.h` (which is not
+included by default by :file:`Python.h`) and :c:func:`import_curses` must
+be invoked, usually as part of the module initialisation function, to populate
+:c:var:`PyCurses_API`.
+
+.. warning::
+
+   Neither the C API nor the pure Python :mod:`curses` module are compatible
+   with subinterpreters.
+
+.. c:macro:: import_curses()
+
+   Import the curses C API. The macro does not need a semi-colon to be called.
+
+   On success, populate the :c:var:`PyCurses_API` pointer.
+
+   On failure, set :c:var:`PyCurses_API` to NULL and set an exception.
+   The caller must check if an error occurred via :c:func:`PyErr_Occurred`:
+
+   .. code-block::
+
+      import_curses();  // semi-colon is optional but recommended
+      if (PyErr_Occurred()) { /* cleanup */ }
+
+
+.. c:var:: void **PyCurses_API
+
+   Dynamically allocated object containing the curses C API.
+   This variable is only available once :c:macro:`import_curses` succeeds.
+
+   ``PyCurses_API[0]`` corresponds to :c:data:`PyCursesWindow_Type`.
+
+   ``PyCurses_API[1]``, ``PyCurses_API[2]``, and ``PyCurses_API[3]``
+   are pointers to predicate functions of type ``int (*)(void)``.
+
+   When called, these predicates return whether :func:`curses.setupterm`,
+   :func:`curses.initscr`, and :func:`curses.start_color` have been called
+   respectively.
+
+   See also the convenience macros :c:macro:`PyCursesSetupTermCalled`,
+   :c:macro:`PyCursesInitialised`, and :c:macro:`PyCursesInitialisedColor`.
+
+   .. note::
+
+      The number of entries in this structure is subject to changes.
+      Consider using :c:macro:`PyCurses_API_pointers` to check if
+      new fields are available or not.
+
+
+.. c:macro:: PyCurses_API_pointers
+
+   The number of accessible fields (``4``) in :c:var:`PyCurses_API`.
+   This number is incremented whenever new fields are added.
+
+
+.. c:var:: PyTypeObject PyCursesWindow_Type
+
+   The :ref:`heap type <heap-types>` corresponding to :class:`curses.window`.
+
+
+.. c:function:: int PyCursesWindow_Check(PyObject *op)
+
+   Return true if *op* is a :class:`curses.window` instance, false otherwise.
+
+
+The following macros are convenience macros expanding into C statements.
+In particular, they can only be used as ``macro;`` or ``macro``, but not
+``macro()`` or ``macro();``.
+
+.. c:macro:: PyCursesSetupTermCalled
+
+   Macro checking if :func:`curses.setupterm` has been called.
+
+   The macro expansion is roughly equivalent to:
+
+   .. code-block::
+
+      {
+          typedef int (*predicate_t)(void);
+          predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
+          if (!was_setupterm_called()) {
+              return NULL;
+          }
+      }
+
+
+.. c:macro:: PyCursesInitialised
+
+   Macro checking if :func:`curses.initscr` has been called.
+
+   The macro expansion is roughly equivalent to:
+
+   .. code-block::
+
+      {
+          typedef int (*predicate_t)(void);
+          predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
+          if (!was_initscr_called()) {
+              return NULL;
+          }
+      }
+
+
+.. c:macro:: PyCursesInitialisedColor
+
+   Macro checking if :func:`curses.start_color` has been called.
+
+   The macro expansion is roughly equivalent to:
+
+   .. code-block::
+
+      {
+          typedef int (*predicate_t)(void);
+          predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];
+          if (!was_start_color_called()) {
+              return NULL;
+          }
+      }
+
+
+Internal data
+-------------
+
+The following objects are exposed by the C API but should be considered
+internal-only.
+
+.. c:macro:: PyCurses_CAPSULE_NAME
+
+   Name of the curses capsule to pass to :c:func:`PyCapsule_Import`.
+
+   Internal usage only. Use :c:macro:`import_curses` instead.
+

Doc/c-api/datetime.rst

@@ -8,11 +8,42 @@ DateTime Objects
 Various date and time objects are supplied by the :mod:`datetime` module.
 Before using any of these functions, the header file :file:`datetime.h` must be
 included in your source (note that this is not included by :file:`Python.h`),
-and the macro :c:macro:`!PyDateTime_IMPORT` must be invoked, usually as part of
+and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
 the module initialisation function.  The macro puts a pointer to a C structure
-into a static variable, :c:data:`!PyDateTimeAPI`, that is used by the following
+into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
 macros.
 
+.. c:macro:: PyDateTime_IMPORT()
+
+   Import the datetime C API.
+
+   On success, populate the :c:var:`PyDateTimeAPI` pointer.
+   On failure, set :c:var:`PyDateTimeAPI` to ``NULL`` and set an exception.
+   The caller must check if an error occurred via :c:func:`PyErr_Occurred`:
+
+   .. code-block::
+
+      PyDateTime_IMPORT;
+      if (PyErr_Occurred()) { /* cleanup */ }
+
+   .. warning::
+
+      This is not compatible with subinterpreters.
+
+.. c:type:: PyDateTime_CAPI
+
+   Structure containing the fields for the datetime C API.
+
+   The fields of this structure are private and subject to change.
+
+   Do not use this directly; prefer ``PyDateTime_*`` APIs instead.
+
+.. c:var:: PyDateTime_CAPI *PyDateTimeAPI
+
+   Dynamically allocated object containing the datetime C API.
+
+   This variable is only available once :c:macro:`PyDateTime_IMPORT` succeeds.
+
 .. c:type:: PyDateTime_Date
 
    This subtype of :c:type:`PyObject` represents a Python date object.
@@ -46,7 +77,7 @@ macros.
 
 .. c:var:: PyTypeObject PyDateTime_DeltaType
 
-   This instance of :c:type:`PyTypeObject` represents Python type for
+   This instance of :c:type:`PyTypeObject` represents the Python type for
    the difference between two datetime values;
    it is the same object as :class:`datetime.timedelta` in the Python layer.
 
@@ -325,3 +356,16 @@ Macros for the convenience of modules implementing the DB API:
 
    Create and return a new :class:`datetime.date` object given an argument
    tuple suitable for passing to :meth:`datetime.date.fromtimestamp`.
+
+
+Internal data
+-------------
+
+The following symbols are exposed by the C API but should be considered
+internal-only.
+
+.. c:macro:: PyDateTime_CAPSULE_NAME
+
+   Name of the datetime capsule to pass to :c:func:`PyCapsule_Import`.
+
+   Internal usage only. Use :c:macro:`PyDateTime_IMPORT` instead.

Doc/c-api/descriptor.rst

@@ -32,9 +32,51 @@ found in the dictionary of type objects.
 
 .. c:function:: int PyDescr_IsData(PyObject *descr)
 
-   Return non-zero if the descriptor objects *descr* describes a data attribute, or
+   Return non-zero if the descriptor object *descr* describes a data attribute, or
    ``0`` if it describes a method.  *descr* must be a descriptor object; there is
    no error checking.
 
 
 .. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
+
+
+Built-in descriptors
+^^^^^^^^^^^^^^^^^^^^
+
+.. c:var:: PyTypeObject PySuper_Type
+
+   The type object for super objects. This is the same object as
+   :class:`super` in the Python layer.
+
+
+.. c:var:: PyTypeObject PyClassMethod_Type
+
+   The type of class method objects. This is the same object as
+   :class:`classmethod` in the Python layer.
+
+
+.. c:function:: PyObject *PyClassMethod_New(PyObject *callable)
+
+   Create a new :class:`classmethod` object wrapping *callable*.
+   *callable* must be a callable object and must not be ``NULL``.
+
+   On success, this function returns a :term:`strong reference` to a new class
+   method descriptor. On failure, this function returns ``NULL`` with an
+   exception set.
+
+
+.. c:var:: PyTypeObject PyStaticMethod_Type
+
+   The type of static method objects. This is the same object as
+   :class:`staticmethod` in the Python layer.
+
+
+.. c:function:: PyObject *PyStaticMethod_New(PyObject *callable)
+
+   Create a new :class:`staticmethod` object wrapping *callable*.
+   *callable* must be a callable object and must not be ``NULL``.
+
+   On success, this function returns a :term:`strong reference` to a new static
+   method descriptor. On failure, this function returns ``NULL`` with an
+   exception set.
+

Doc/c-api/dict.rst

@@ -245,6 +245,11 @@ Dictionary Objects
    ``len(p)`` on a dictionary.
 
 
+.. c:function:: Py_ssize_t PyDict_GET_SIZE(PyObject *p)
+
+   Similar to :c:func:`PyDict_Size`, but without error checking.
+
+
 .. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
 
    Iterate over all key-value pairs in the dictionary *p*.  The
@@ -426,3 +431,138 @@ Dictionary Objects
    it before returning.
 
    .. versionadded:: 3.12
+
+
+Dictionary View Objects
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. c:function:: int PyDictViewSet_Check(PyObject *op)
+
+   Return true if *op* is a view of a set inside a dictionary. This is currently
+   equivalent to :c:expr:`PyDictKeys_Check(op) || PyDictItems_Check(op)`. This
+   function always succeeds.
+
+
+.. c:var:: PyTypeObject PyDictKeys_Type
+
+   Type object for a view of dictionary keys. In Python, this is the type of
+   the object returned by :meth:`dict.keys`.
+
+
+.. c:function:: int PyDictKeys_Check(PyObject *op)
+
+   Return true if *op* is an instance of a dictionary keys view. This function
+   always succeeds.
+
+
+.. c:var:: PyTypeObject PyDictValues_Type
+
+   Type object for a view of dictionary values. In Python, this is the type of
+   the object returned by :meth:`dict.values`.
+
+
+.. c:function:: int PyDictValues_Check(PyObject *op)
+
+   Return true if *op* is an instance of a dictionary values view. This function
+   always succeeds.
+
+
+.. c:var:: PyTypeObject PyDictItems_Type
+
+   Type object for a view of dictionary items. In Python, this is the type of
+   the object returned by :meth:`dict.items`.
+
+
+.. c:function:: int PyDictItems_Check(PyObject *op)
+
+   Return true if *op* is an instance of a dictionary items view. This function
+   always succeeds.
+
+
+Ordered Dictionaries
+^^^^^^^^^^^^^^^^^^^^
+
+Python's C API provides interface for :class:`collections.OrderedDict` from C.
+Since Python 3.7, dictionaries are ordered by default, so there is usually
+little need for these functions; prefer ``PyDict*`` where possible.
+
+
+.. c:var:: PyTypeObject PyODict_Type
+
+   Type object for ordered dictionaries. This is the same object as
+   :class:`collections.OrderedDict` in the Python layer.
+
+
+.. c:function:: int PyODict_Check(PyObject *od)
+
+   Return true if *od* is an ordered dictionary object or an instance of a
+   subtype of the :class:`~collections.OrderedDict` type.  This function
+   always succeeds.
+
+
+.. c:function:: int PyODict_CheckExact(PyObject *od)
+
+   Return true if *od* is an ordered dictionary object, but not an instance of
+   a subtype of the :class:`~collections.OrderedDict` type.
+   This function always succeeds.
+
+
+.. c:var:: PyTypeObject PyODictKeys_Type
+
+   Analogous to :c:type:`PyDictKeys_Type` for ordered dictionaries.
+
+
+.. c:var:: PyTypeObject PyODictValues_Type
+
+   Analogous to :c:type:`PyDictValues_Type` for ordered dictionaries.
+
+
+.. c:var:: PyTypeObject PyODictItems_Type
+
+   Analogous to :c:type:`PyDictItems_Type` for ordered dictionaries.
+
+
+.. c:function:: PyObject *PyODict_New(void)
+
+   Return a new empty ordered dictionary, or ``NULL`` on failure.
+
+   This is analogous to :c:func:`PyDict_New`.
+
+
+.. c:function:: int PyODict_SetItem(PyObject *od, PyObject *key, PyObject *value)
+
+   Insert *value* into the ordered dictionary *od* with a key of *key*.
+   Return ``0`` on success or ``-1`` with an exception set on failure.
+
+   This is analogous to :c:func:`PyDict_SetItem`.
+
+
+.. c:function:: int PyODict_DelItem(PyObject *od, PyObject *key)
+
+   Remove the entry in the ordered dictionary *od* with key *key*.
+   Return ``0`` on success or ``-1`` with an exception set on failure.
+
+   This is analogous to :c:func:`PyDict_DelItem`.
+
+
+These are :term:`soft deprecated` aliases to ``PyDict`` APIs:
+
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * * ``PyODict``
+     * ``PyDict``
+   * * .. c:macro:: PyODict_GetItem(od, key)
+     * :c:func:`PyDict_GetItem`
+   * * .. c:macro:: PyODict_GetItemWithError(od, key)
+     * :c:func:`PyDict_GetItemWithError`
+   * * .. c:macro:: PyODict_GetItemString(od, key)
+     * :c:func:`PyDict_GetItemString`
+   * * .. c:macro:: PyODict_Contains(od, key)
+     * :c:func:`PyDict_Contains`
+   * * .. c:macro:: PyODict_Size(od)
+     * :c:func:`PyDict_Size`
+   * * .. c:macro:: PyODict_SIZE(od)
+     * :c:func:`PyDict_GET_SIZE`

Doc/c-api/exceptions.rst

@@ -309,6 +309,14 @@ For convenience, some of these functions will always return a
    .. versionadded:: 3.4
 
 
+.. c:function:: void PyErr_RangedSyntaxLocationObject(PyObject *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)
+
+   Similar to :c:func:`PyErr_SyntaxLocationObject`, but also sets the
+   *end_lineno* and *end_col_offset* information for the current exception.
+
+   .. versionadded:: 3.10
+
+
 .. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
 
    Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
@@ -331,6 +339,23 @@ For convenience, some of these functions will always return a
    use.
 
 
+.. c:function:: PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)
+
+   Get the source line in *filename* at line *lineno*. *filename* should be a
+   Python :class:`str` object.
+
+   On success, this function returns a Python string object with the found line.
+   On failure, this function returns ``NULL`` without an exception set.
+
+
+.. c:function:: PyObject *PyErr_ProgramText(const char *filename, int lineno)
+
+   Similar to :c:func:`PyErr_ProgramTextObject`, but *filename* is a
+   :c:expr:`const char *`, which is decoded with the
+   :term:`filesystem encoding and error handler`, instead of a
+   Python object reference.
+
+
 Issuing warnings
 ================
 
@@ -394,6 +419,15 @@ an error value).
    .. versionadded:: 3.2
 
 
+.. c:function:: int PyErr_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)
+
+   Similar to :c:func:`PyErr_WarnExplicit`, but uses
+   :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
+   an ASCII-encoded string.
+
+   .. versionadded:: 3.2
+
+
 .. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
 
    Function similar to :c:func:`PyErr_WarnFormat`, but *category* is
@@ -762,6 +796,17 @@ Exception Classes
 Exception Objects
 =================
 
+.. c:function:: int PyExceptionInstance_Check(PyObject *op)
+
+   Return true if *op* is an instance of :class:`BaseException`, false
+   otherwise. This function always succeeds.
+
+
+.. c:macro:: PyExceptionInstance_Class(op)
+
+   Equivalent to :c:func:`Py_TYPE(op) <Py_TYPE>`.
+
+
 .. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
 
    Return the traceback associated with the exception as a new reference, as
@@ -939,6 +984,9 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
    be concatenated to the :exc:`RecursionError` message caused by the recursion
    depth limit.
 
+   .. seealso::
+      The :c:func:`PyUnstable_ThreadState_SetStackProtection` function.
+
    .. versionchanged:: 3.9
       This function is now also available in the :ref:`limited API <limited-c-api>`.
 
@@ -979,6 +1027,27 @@ these are the C equivalent to :func:`reprlib.recursive_repr`.
    Ends a :c:func:`Py_ReprEnter`.  Must be called once for each
    invocation of :c:func:`Py_ReprEnter` that returns zero.
 
+.. c:function:: int Py_GetRecursionLimit(void)
+
+   Get the recursion limit for the current interpreter. It can be set with
+   :c:func:`Py_SetRecursionLimit`. The recursion limit prevents the
+   Python interpreter stack from growing infinitely.
+
+   This function cannot fail, and the caller must hold an
+   :term:`attached thread state`.
+
+   .. seealso::
+      :py:func:`sys.getrecursionlimit`
+
+.. c:function:: void Py_SetRecursionLimit(int new_limit)
+
+   Set the recursion limit for the current interpreter.
+
+   This function cannot fail, and the caller must hold an
+   :term:`attached thread state`.
+
+   .. seealso::
+      :py:func:`sys.setrecursionlimit`
 
 .. _standardexceptions:
 
@@ -1207,3 +1276,37 @@ Warning types
 
 .. versionadded:: 3.10
    :c:data:`PyExc_EncodingWarning`.
+
+
+Tracebacks
+==========
+
+.. c:var:: PyTypeObject PyTraceBack_Type
+
+   Type object for traceback objects. This is available as
+   :class:`types.TracebackType` in the Python layer.
+
+
+.. c:function:: int PyTraceBack_Check(PyObject *op)
+
+   Return true if *op* is a traceback object, false otherwise. This function
+   does not account for subtypes.
+
+
+.. c:function:: int PyTraceBack_Here(PyFrameObject *f)
+
+   Replace the :attr:`~BaseException.__traceback__` attribute on the current
+   exception with a new traceback prepending *f* to the existing chain.
+
+   Calling this function without an exception set is undefined behavior.
+
+   This function returns ``0`` on success, and returns ``-1`` with an
+   exception set on failure.
+
+
+.. c:function:: int PyTraceBack_Print(PyObject *tb, PyObject *f)
+
+   Write the traceback *tb* into the file *f*.
+
+   This function returns ``0`` on success, and returns ``-1`` with an
+   exception set on failure.

Doc/c-api/file.rst

@@ -93,6 +93,29 @@ the :mod:`io` APIs instead.
    .. versionadded:: 3.8
 
 
+.. c:function:: PyObject *PyFile_OpenCodeObject(PyObject *path)
+
+   Open *path* with the mode ``'rb'``. *path* must be a Python :class:`str`
+   object. The behavior of this function may be overridden by
+   :c:func:`PyFile_SetOpenCodeHook` to allow for some preprocessing of the
+   text.
+
+   This is analogous to :func:`io.open_code` in Python.
+
+   On success, this function returns a :term:`strong reference` to a Python
+   file object. On failure, this function returns ``NULL`` with an exception
+   set.
+
+   .. versionadded:: 3.8
+
+
+.. c:function:: PyObject *PyFile_OpenCode(const char *path)
+
+   Similar to :c:func:`PyFile_OpenCodeObject`, but *path* is a
+   UTF-8 encoded :c:expr:`const char*`.
+
+   .. versionadded:: 3.8
+
 
 .. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
 

Doc/c-api/float.rst

@@ -78,6 +78,111 @@ Floating-Point Objects
    Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`.
 
 
+.. c:macro:: Py_INFINITY
+
+   This macro expands a to constant expression of type :c:expr:`double`, that
+   represents the positive infinity.
+
+   It is equivalent to the :c:macro:`!INFINITY` macro from the C11 standard
+   ``<math.h>`` header.
+
+   .. deprecated:: 3.15
+      The macro is :term:`soft deprecated`.
+
+
+.. c:macro:: Py_NAN
+
+   This macro expands a to constant expression of type :c:expr:`double`, that
+   represents a quiet not-a-number (qNaN) value.
+
+   On most platforms, this is equivalent to the :c:macro:`!NAN` macro from
+   the C11 standard ``<math.h>`` header.
+
+
+.. c:macro:: Py_HUGE_VAL
+
+   Equivalent to :c:macro:`!INFINITY`.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.
+
+
+.. c:macro:: Py_MATH_E
+
+   The definition (accurate for a :c:expr:`double` type) of the :data:`math.e` constant.
+
+
+.. c:macro:: Py_MATH_El
+
+   High precision (long double) definition of :data:`~math.e` constant.
+
+   .. deprecated-removed:: 3.15 3.20
+
+
+.. c:macro:: Py_MATH_PI
+
+   The definition (accurate for a :c:expr:`double` type) of the :data:`math.pi` constant.
+
+
+.. c:macro:: Py_MATH_PIl
+
+   High precision (long double) definition of :data:`~math.pi` constant.
+
+   .. deprecated-removed:: 3.15 3.20
+
+
+.. c:macro:: Py_MATH_TAU
+
+   The definition (accurate for a :c:expr:`double` type) of the :data:`math.tau` constant.
+
+   .. versionadded:: 3.6
+
+
+.. c:macro:: Py_RETURN_NAN
+
+   Return :data:`math.nan` from a function.
+
+   On most platforms, this is equivalent to ``return PyFloat_FromDouble(NAN)``.
+
+
+.. c:macro:: Py_RETURN_INF(sign)
+
+   Return :data:`math.inf` or :data:`-math.inf <math.inf>` from a function,
+   depending on the sign of *sign*.
+
+   On most platforms, this is equivalent to the following::
+
+      return PyFloat_FromDouble(copysign(INFINITY, sign));
+
+
+.. c:macro:: Py_IS_FINITE(X)
+
+   Return ``1`` if the given floating-point number *X* is finite,
+   that is, it is normal, subnormal or zero, but not infinite or NaN.
+   Return ``0`` otherwise.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.  Use :c:macro:`!isfinite` instead.
+
+
+.. c:macro:: Py_IS_INFINITY(X)
+
+   Return ``1`` if the given floating-point number *X* is positive or negative
+   infinity.  Return ``0`` otherwise.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.  Use :c:macro:`!isinf` instead.
+
+
+.. c:macro:: Py_IS_NAN(X)
+
+   Return ``1`` if the given floating-point number *X* is a not-a-number (NaN)
+   value.  Return ``0`` otherwise.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.  Use :c:macro:`!isnan` instead.
+
+
 Pack and Unpack functions
 -------------------------
 
@@ -96,8 +201,8 @@ NaNs (if such things exist on the platform) isn't handled correctly, and
 attempting to unpack a bytes string containing an IEEE INF or NaN will raise an
 exception.
 
-Note that NaNs type may not be preserved on IEEE platforms (silent NaN become
+Note that NaNs type may not be preserved on IEEE platforms (signaling NaN become
-quiet), for example on x86 systems in 32-bit mode.
+quiet NaN), for example on x86 systems in 32-bit mode.
 
 On non-IEEE platforms with more precision, or larger dynamic range, than IEEE
 754 supports, not all values can be packed; on non-IEEE platforms with less

Doc/c-api/frame.rst

@@ -29,6 +29,12 @@ See also :ref:`Reflection <reflection>`.
       Previously, this type was only available after including
       ``<frameobject.h>``.
 
+.. c:function:: PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)
+
+   Create a new frame object. This function returns a :term:`strong reference`
+   to the new frame object on success, and returns ``NULL`` with an exception
+   set on failure.
+
 .. c:function:: int PyFrame_Check(PyObject *obj)
 
    Return non-zero if *obj* is a frame object.
@@ -161,6 +167,57 @@ See :pep:`667` for more information.
 
    Return non-zero if *obj* is a frame :func:`locals` proxy.
 
+
+Legacy Local Variable APIs
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing.
+They exist solely for backwards compatibility.
+
+
+.. c:function:: void PyFrame_LocalsToFast(PyFrameObject *f, int clear)
+
+   This function is :term:`soft deprecated` and does nothing.
+
+   Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals`
+   attribute of *f* to the internal "fast" array of local variables, allowing
+   changes in frame objects to be visible to the interpreter. If *clear* was
+   true, this function would process variables that were unset in the locals
+   dictionary.
+
+   .. versionchanged:: 3.13
+      This function now does nothing.
+
+
+.. c:function:: void PyFrame_FastToLocals(PyFrameObject *f)
+
+   This function is :term:`soft deprecated` and does nothing.
+
+   Prior to Python 3.13, this function would copy the internal "fast" array
+   of local variables (which is used by the interpreter) to the
+   :attr:`~frame.f_locals` attribute of *f*, allowing changes in local
+   variables to be visible to frame objects.
+
+   .. versionchanged:: 3.13
+      This function now does nothing.
+
+
+.. c:function:: int PyFrame_FastToLocalsWithError(PyFrameObject *f)
+
+   This function is :term:`soft deprecated` and does nothing.
+
+   Prior to Python 3.13, this function was similar to
+   :c:func:`PyFrame_FastToLocals`, but would return ``0`` on success, and
+   ``-1`` with an exception set on failure.
+
+   .. versionchanged:: 3.13
+      This function now does nothing.
+
+
+.. seealso::
+   :pep:`667`
+
+
 Internal Frames
 ^^^^^^^^^^^^^^^
 

Doc/c-api/function.rst

@@ -102,6 +102,15 @@ There are a few functions specific to Python functions.
    dictionary of arguments or ``NULL``.
 
 
+.. c:function:: int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)
+
+   Set the keyword-only argument default values of the function object *op*.
+   *defaults* must be a dictionary of keyword-only arguments or ``Py_None``.
+
+   This function returns ``0`` on success, and returns ``-1`` with an exception
+   set on failure.
+
+
 .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
 
    Return the closure associated with the function object *op*. This can be ``NULL``
@@ -200,7 +209,7 @@ There are a few functions specific to Python functions.
    runtime behavior depending on optimization decisions, it does not change
    the semantics of the Python code being executed.
 
-   If *event* is ``PyFunction_EVENT_DESTROY``,  Taking a reference in the
+   If *event* is ``PyFunction_EVENT_DESTROY``, taking a reference in the
    callback to the about-to-be-destroyed function will resurrect it, preventing
    it from being freed at this time. When the resurrected object is destroyed
    later, any watcher callbacks active at that time will be called again.

Doc/c-api/gen.rst

@@ -44,3 +44,41 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
    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``.
+
+.. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen)
+
+   Return a new :term:`strong reference` to the code object wrapped by *gen*.
+   This function always succeeds.
+
+
+Asynchronous Generator Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. seealso::
+   :pep:`525`
+
+.. c:var:: PyTypeObject PyAsyncGen_Type
+
+   The type object corresponding to asynchronous generator objects. This is
+   available as :class:`types.AsyncGeneratorType` in the Python layer.
+
+   .. versionadded:: 3.6
+
+.. 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``.
+
+   On success, this function returns a :term:`strong reference` to the
+   new asynchronous generator. On failure, this function returns ``NULL``
+   with an exception set.
+
+   .. versionadded:: 3.6
+
+.. c:function:: int PyAsyncGen_CheckExact(PyObject *op)
+
+   Return true if *op* is an asynchronous generator object, false otherwise.
+   This function always succeeds.
+
+   .. versionadded:: 3.6

Doc/c-api/hash.rst

@@ -11,42 +11,98 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
    .. versionadded:: 3.2
 
+
 .. c:type:: Py_uhash_t
 
    Hash value type: unsigned integer.
 
    .. versionadded:: 3.2
 
+
+.. c:macro:: Py_HASH_ALGORITHM
+
+   A numerical value indicating the algorithm for hashing of :class:`str`,
+   :class:`bytes`, and :class:`memoryview`.
+
+   The algorithm name is exposed by :data:`sys.hash_info.algorithm`.
+
+   .. versionadded:: 3.4
+
+
+.. c:macro:: Py_HASH_FNV
+             Py_HASH_SIPHASH24
+             Py_HASH_SIPHASH13
+
+   Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine
+   which algorithm is used for hashing. The hash algorithm can be configured
+   via the configure :option:`--with-hash-algorithm` option.
+
+   .. versionadded:: 3.4
+      Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`.
+
+   .. versionadded:: 3.11
+      Add :c:macro:`!Py_HASH_SIPHASH13`.
+
+
+.. c:macro:: Py_HASH_CUTOFF
+
+   Buffers of length in range ``[1, Py_HASH_CUTOFF)`` are hashed using DJBX33A
+   instead of the algorithm described by :c:macro:`Py_HASH_ALGORITHM`.
+
+   - A :c:macro:`!Py_HASH_CUTOFF` of 0 disables the optimization.
+   - :c:macro:`!Py_HASH_CUTOFF` must be non-negative and less or equal than 7.
+
+   32-bit platforms should use a cutoff smaller than 64-bit platforms because
+   it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms
+   and 5 on 32-bit platforms should provide a decent safety margin.
+
+   This corresponds to the :data:`sys.hash_info.cutoff` constant.
+
+   .. versionadded:: 3.4
+
+
 .. c:macro:: PyHASH_MODULUS
 
-   The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P = 2**n -1``, used for numeric hash scheme.
+   The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P = 2**n -1``,
+   used for numeric hash scheme.
+
+   This corresponds to the :data:`sys.hash_info.modulus` constant.
 
    .. versionadded:: 3.13
 
+
 .. c:macro:: PyHASH_BITS
 
    The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`.
 
    .. versionadded:: 3.13
 
+
 .. c:macro:: PyHASH_MULTIPLIER
 
    Prime multiplier used in string and various other hashes.
 
    .. versionadded:: 3.13
 
+
 .. c:macro:: PyHASH_INF
 
    The hash value returned for a positive infinity.
 
+   This corresponds to the :data:`sys.hash_info.inf` constant.
+
    .. versionadded:: 3.13
 
+
 .. c:macro:: PyHASH_IMAG
 
    The multiplier used for the imaginary part of a complex number.
 
+   This corresponds to the :data:`sys.hash_info.imag` constant.
+
    .. versionadded:: 3.13
 
+
 .. c:type:: PyHash_FuncDef
 
    Hash function definition used by :c:func:`PyHash_GetFuncDef`.
@@ -59,14 +115,20 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
       Hash function name (UTF-8 encoded string).
 
+      This corresponds to the :data:`sys.hash_info.algorithm` constant.
+
    .. c:member:: const int hash_bits
 
       Internal size of the hash value in bits.
 
+      This corresponds to the :data:`sys.hash_info.hash_bits` constant.
+
    .. c:member:: const int seed_bits
 
       Size of seed input in bits.
 
+      This corresponds to the :data:`sys.hash_info.seed_bits` constant.
+
    .. versionadded:: 3.4
 
 

Doc/c-api/import.rst

@@ -333,3 +333,24 @@ Importing Modules
    strings instead of Python :class:`str` objects.
 
    .. versionadded:: 3.14
+
+.. c:function:: PyObject* PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject* (*initfunc)(void))
+
+   This function is a building block that enables embedders to implement
+   the :py:meth:`~importlib.abc.Loader.create_module` step of custom
+   static extension importers (e.g. of statically-linked extensions).
+
+   *spec* must be a :class:`~importlib.machinery.ModuleSpec` object.
+
+   *initfunc* must be an :ref:`initialization function <extension-export-hook>`,
+   the same as for :c:func:`PyImport_AppendInittab`.
+
+   On success, create and return a module object.
+   This module will not be initialized; call :c:func:`!PyModule_Exec`
+   to initialize it.
+   (Custom importers should do this in their
+   :py:meth:`~importlib.abc.Loader.exec_module` method.)
+
+   On error, return NULL with an exception set.
+
+   .. versionadded:: 3.15

Doc/c-api/init.rst

@@ -1366,6 +1366,43 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    .. versionadded:: 3.11
 
 
+.. c:function:: int PyUnstable_ThreadState_SetStackProtection(PyThreadState *tstate, void *stack_start_addr, size_t stack_size)
+
+   Set the stack protection start address and stack protection size
+   of a Python thread state.
+
+   On success, return ``0``.
+   On failure, set an exception and return ``-1``.
+
+   CPython implements :ref:`recursion control <recursion>` for C code by raising
+   :py:exc:`RecursionError` when it notices that the machine execution stack is close
+   to overflow. See for example the :c:func:`Py_EnterRecursiveCall` function.
+   For this, it needs to know the location of the current thread's stack, which it
+   normally gets from the operating system.
+   When the stack is changed, for example using context switching techniques like the
+   Boost library's ``boost::context``, you must call
+   :c:func:`~PyUnstable_ThreadState_SetStackProtection` to inform CPython of the change.
+
+   Call :c:func:`~PyUnstable_ThreadState_SetStackProtection` either before
+   or after changing the stack.
+   Do not call any other Python C API between the call and the stack
+   change.
+
+   See :c:func:`PyUnstable_ThreadState_ResetStackProtection` for undoing this operation.
+
+   .. versionadded:: 3.15
+
+
+.. c:function:: void PyUnstable_ThreadState_ResetStackProtection(PyThreadState *tstate)
+
+   Reset the stack protection start address and stack protection size
+   of a Python thread state to the operating system defaults.
+
+   See :c:func:`PyUnstable_ThreadState_SetStackProtection` for an explanation.
+
+   .. versionadded:: 3.15
+
+
 .. c:function:: PyInterpreterState* PyInterpreterState_Get(void)
 
    Get the current interpreter.
@@ -1854,6 +1891,25 @@ pointer and a void pointer argument.
       This function now always schedules *func* to be run in the main
       interpreter.
 
+
+.. c:function:: int Py_MakePendingCalls(void)
+
+   Execute all pending calls. This is usually executed automatically by the
+   interpreter.
+
+   This function returns ``0`` on success, and returns ``-1`` with an exception
+   set on failure.
+
+   If this is not called in the main thread of the main
+   interpreter, this function does nothing and returns ``0``.
+   The caller must hold an :term:`attached thread state`.
+
+   .. versionadded:: 3.1
+
+   .. versionchanged:: 3.12
+      This function only runs pending calls in the main interpreter.
+
+
 .. _profiling:
 
 Profiling and Tracing

Doc/c-api/init_config.rst

@@ -102,7 +102,7 @@ Error Handling
    * Set *\*err_msg* and return ``1`` if an error is set.
    * Set *\*err_msg* to ``NULL`` and return ``0`` otherwise.
 
-   An error message is an UTF-8 encoded string.
+   An error message is a UTF-8 encoded string.
 
    If *config* has an exit code, format the exit code as an error
    message.

Doc/c-api/intro.rst

@@ -121,6 +121,10 @@ complete listing.
 
    Return the absolute value of ``x``.
 
+   If the result cannot be represented (for example, if ``x`` has
+   :c:macro:`!INT_MIN` value for :c:expr:`int` type), the behavior is
+   undefined.
+
    .. versionadded:: 3.3
 
 .. c:macro:: Py_ALWAYS_INLINE
@@ -167,6 +171,17 @@ complete listing.
    Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
    command line (see :c:member:`PyConfig.use_environment`).
 
+.. c:macro:: Py_LOCAL(type)
+
+   Declare a function returning the specified *type* using a fast-calling
+   qualifier for functions that are local to the current file.
+   Semantically, this is equivalent to ``static type``.
+
+.. c:macro:: Py_LOCAL_INLINE(type)
+
+   Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
+   be inlined.
+
 .. c:macro:: Py_MAX(x, y)
 
    Return the maximum value between ``x`` and ``y``.
@@ -179,6 +194,14 @@ complete listing.
 
    .. versionadded:: 3.6
 
+.. c:macro:: Py_MEMCPY(dest, src, n)
+
+   This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
+   Use :c:func:`!memcpy` directly instead.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.
+
 .. c:macro:: Py_MIN(x, y)
 
    Return the minimum value between ``x`` and ``y``.
@@ -233,9 +256,32 @@ complete listing.
 
    .. versionadded:: 3.4
 
+.. c:macro:: Py_BUILD_ASSERT(cond)
+
+   Asserts a compile-time condition *cond*, as a statement.
+   The build will fail if the condition is false or cannot be evaluated at compile time.
+
+   For example::
+
+      Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
+
+   .. versionadded:: 3.3
+
+.. c:macro:: Py_BUILD_ASSERT_EXPR(cond)
+
+   Asserts a compile-time condition *cond*, as an expression that evaluates to ``0``.
+   The build will fail if the condition is false or cannot be evaluated at compile time.
+
+   For example::
+
+      #define foo_to_char(foo) \
+          ((char *)(foo) + Py_BUILD_ASSERT_EXPR(offsetof(struct foo, string) == 0))
+
+   .. versionadded:: 3.3
+
 .. c:macro:: PyDoc_STRVAR(name, str)
 
-   Creates a variable with name ``name`` that can be used in docstrings.
+   Creates a variable with name *name* that can be used in docstrings.
    If Python is built without docstrings, the value will be empty.
 
    Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
@@ -267,6 +313,15 @@ complete listing.
           {NULL, NULL}
       };
 
+.. c:macro:: PyDoc_VAR(name)
+
+   Declares a static character array variable with the given name *name*.
+
+   For example::
+
+      PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
+                                        "to the tropics and subtropics of the Eastern Hemisphere.");
+
 
 .. _api-objects:
 

Doc/c-api/iterator.rst

@@ -50,3 +50,72 @@ sentinel value is returned.
    callable object that can be called with no parameters; each call to it should
    return the next item in the iteration.  When *callable* returns a value equal to
    *sentinel*, the iteration will be terminated.
+
+
+Range Objects
+^^^^^^^^^^^^^
+
+.. c:var:: PyTypeObject PyRange_Type
+
+   The type object for :class:`range` objects.
+
+
+.. c:function:: int PyRange_Check(PyObject *o)
+
+   Return true if the object *o* is an instance of a :class:`range` object.
+   This function always succeeds.
+
+
+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`
+
+
+Other Iterator Objects
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. c:var:: PyTypeObject PyByteArrayIter_Type
+.. c:var:: PyTypeObject PyBytesIter_Type
+.. c:var:: PyTypeObject PyListIter_Type
+.. c:var:: PyTypeObject PyListRevIter_Type
+.. c:var:: PyTypeObject PySetIter_Type
+.. c:var:: PyTypeObject PyTupleIter_Type
+.. c:var:: PyTypeObject PyRangeIter_Type
+.. c:var:: PyTypeObject PyLongRangeIter_Type
+.. c:var:: PyTypeObject PyDictIterKey_Type
+.. c:var:: PyTypeObject PyDictRevIterKey_Type
+.. c:var:: PyTypeObject PyDictIterValue_Type
+.. c:var:: PyTypeObject PyDictRevIterValue_Type
+.. c:var:: PyTypeObject PyDictIterItem_Type
+.. c:var:: PyTypeObject PyDictRevIterItem_Type
+.. c:var:: PyTypeObject PyODictIter_Type
+
+   Type objects for iterators of various built-in objects.
+
+   Do not create instances of these directly; prefer calling
+   :c:func:`PyObject_GetIter` instead.
+
+   Note that there is no guarantee that a given built-in type uses a given iterator
+   type. For example, iterating over :class:`range` will use one of two iterator
+   types depending on the size of the range. Other types may start using a
+   similar scheme in the future, without warning.

Doc/c-api/long.rst

@@ -161,6 +161,17 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
+.. c:macro:: PyLong_FromPid(pid)
+
+   Macro for creating a Python integer from a process identifier.
+
+   This can be defined as an alias to :c:func:`PyLong_FromLong` or
+   :c:func:`PyLong_FromLongLong`, depending on the size of the system's
+   PID type.
+
+   .. versionadded:: 3.2
+
+
 .. c:function:: long PyLong_AsLong(PyObject *obj)
 
    .. index::
@@ -575,6 +586,17 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
+.. c:macro:: PyLong_AsPid(pid)
+
+   Macro for converting a Python integer into a process identifier.
+
+   This can be defined as an alias to :c:func:`PyLong_AsLong`,
+   :c:func:`PyLong_FromLongLong`, or :c:func:`PyLong_AsInt`, depending on the
+   size of the system's PID type.
+
+   .. versionadded:: 3.2
+
+
 .. c:function:: int PyLong_GetSign(PyObject *obj, int *sign)
 
    Get the sign of the integer object *obj*.

Doc/c-api/mapping.rst

@@ -102,7 +102,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
    .. note::
 
-      Exceptions which occur when this calls :meth:`~object.__getitem__`
+      Exceptions which occur when this calls the :meth:`~object.__getitem__`
       method are silently ignored.
       For proper error handling, use :c:func:`PyMapping_HasKeyWithError`,
       :c:func:`PyMapping_GetOptionalItem` or :c:func:`PyObject_GetItem()` instead.
@@ -116,7 +116,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
    .. note::
 
-      Exceptions that occur when this calls :meth:`~object.__getitem__`
+      Exceptions that occur when this calls the :meth:`~object.__getitem__`
       method or while creating the temporary :class:`str`
       object are silently ignored.
       For proper error handling, use :c:func:`PyMapping_HasKeyStringWithError`,

Doc/c-api/marshal.rst

@@ -82,7 +82,7 @@ The following functions allow marshalled values to be read back in.
    assumes that no further objects will be read from the file, allowing it to
    aggressively load file data into memory so that the de-serialization can
    operate from data in memory rather than reading a byte at a time from the
-   file.  Only use these variant if you are certain that you won't be reading
+   file.  Only use this variant if you are certain that you won't be reading
    anything else from the file.
 
    On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`

Doc/c-api/memory.rst

@@ -102,7 +102,7 @@ All allocating functions belong to one of three different "domains" (see also
 strategies and are optimized for different purposes. The specific details on
 how every domain allocates memory or what internal functions each domain calls
 is considered an implementation detail, but for debugging purposes a simplified
-table can be found at :ref:`here <default-memory-allocators>`.
+table can be found at :ref:`default-memory-allocators`.
 The APIs used to allocate and free a block of memory must be from the same domain.
 For example, :c:func:`PyMem_Free` must be used to free memory allocated using :c:func:`PyMem_Malloc`.
 

Doc/c-api/memoryview.rst

@@ -13,6 +13,12 @@ A :class:`memoryview` object exposes the C level :ref:`buffer interface
 any other object.
 
 
+.. c:var:: PyTypeObject PyMemoryView_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python memoryview
+   type. This is the same object as :class:`memoryview` in the Python layer.
+
+
 .. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
 
    Create a memoryview object from an object that provides the buffer interface.

Doc/c-api/module.rst

@@ -13,7 +13,7 @@ Module Objects
    .. index:: single: ModuleType (in module types)
 
    This instance of :c:type:`PyTypeObject` represents the Python module type.  This
-   is exposed to Python programs as ``types.ModuleType``.
+   is exposed to Python programs as :py:class:`types.ModuleType`.
 
 
 .. c:function:: int PyModule_Check(PyObject *p)
@@ -71,6 +71,9 @@ Module Objects
    ``PyObject_*`` functions rather than directly manipulate a module's
    :attr:`~object.__dict__`.
 
+   The returned reference is borrowed from the module; it is valid until
+   the module is destroyed.
+
 
 .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
 
@@ -90,6 +93,10 @@ Module Objects
    Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
    ``'utf-8'``.
 
+   The returned buffer is only valid until the module is renamed or destroyed.
+   Note that Python code may rename a module by setting its :py:attr:`~module.__name__`
+   attribute.
+
 .. c:function:: void* PyModule_GetState(PyObject *module)
 
    Return the "state" of the module, that is, a pointer to the block of memory
@@ -103,7 +110,7 @@ Module Objects
    created, or ``NULL`` if the module wasn't created from a definition.
 
    On error, return ``NULL`` with an exception set.
-   Use :c:func:`PyErr_Occurred` to tell this case apart from a mising
+   Use :c:func:`PyErr_Occurred` to tell this case apart from a missing
    :c:type:`!PyModuleDef`.
 
 
@@ -126,6 +133,9 @@ Module Objects
    Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
    encoded to 'utf-8'.
 
+   The returned buffer is only valid until the module's :py:attr:`~module.__file__` attribute
+   is reassigned or the module is destroyed.
+
    .. deprecated:: 3.2
       :c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on
       unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
@@ -671,6 +681,9 @@ or code that creates modules dynamically.
    :c:type:`PyMethodDef` arrays; in that case they should call this function
    directly.
 
+   The *functions* array must be statically allocated (or otherwise guaranteed
+   to outlive the module object).
+
    .. versionadded:: 3.5
 
 .. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)

Doc/c-api/monitoring.rst

@@ -136,7 +136,7 @@ Managing the Monitoring State
 -----------------------------
 
 Monitoring states can be managed with the help of monitoring scopes. A scope
-would typically correspond to a python function.
+would typically correspond to a Python function.
 
 .. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
 

Doc/c-api/object.rst

@@ -73,7 +73,7 @@ Object Protocol
 
    Flag to be used with multiple functions that print the object (like
    :c:func:`PyObject_Print` and :c:func:`PyFile_WriteObject`).
-   If passed, these function would use the :func:`str` of the object
+   If passed, these functions use the :func:`str` of the object
    instead of the :func:`repr`.
 
 
@@ -85,6 +85,35 @@ Object Protocol
    instead of the :func:`repr`.
 
 
+.. c:function:: void PyUnstable_Object_Dump(PyObject *op)
+
+   Dump an object *op* to ``stderr``. This should only be used for debugging.
+
+   The output is intended to try dumping objects even after memory corruption:
+
+   * Information is written starting with fields that are the least likely to
+     crash when accessed.
+   * This function can be called without an :term:`attached thread state`, but
+     it's not recommended to do so: it can cause deadlocks.
+   * An object that does not belong to the current interpreter may be dumped,
+     but this may also cause crashes or unintended behavior.
+   * Implement a heuristic to detect if the object memory has been freed. Don't
+     display the object contents in this case, only its memory address.
+   * The output format may change at any time.
+
+   Example of output:
+
+   .. code-block:: output
+
+       object address  : 0x7f80124702c0
+       object refcount : 2
+       object type     : 0x9902e0
+       object type name: str
+       object repr     : 'abcdef'
+
+   .. versionadded:: next
+
+
 .. c:function:: int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)
 
    Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.

Doc/c-api/picklebuffer.rst

@@ -0,0 +1,59 @@
+.. highlight:: c
+
+.. _picklebuffer-objects:
+
+.. index::
+   pair: object; PickleBuffer
+
+Pickle buffer objects
+---------------------
+
+.. versionadded:: 3.8
+
+A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object
+<bufferobjects>` for out-of-band data transfer with the :mod:`pickle` module.
+
+
+.. c:var:: PyTypeObject PyPickleBuffer_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python pickle buffer type.
+   This is the same object as :class:`pickle.PickleBuffer` in the Python layer.
+
+
+.. c:function:: int PyPickleBuffer_Check(PyObject *op)
+
+   Return true if *op* is a pickle buffer instance.
+   This function always succeeds.
+
+
+.. c:function:: PyObject *PyPickleBuffer_FromObject(PyObject *obj)
+
+   Create a pickle buffer from the object *obj*.
+
+   This function will fail if *obj* doesn't support the :ref:`buffer protocol <bufferobjects>`.
+
+   On success, return a new pickle buffer instance.
+   On failure, set an exception and return ``NULL``.
+
+   Analogous to calling :class:`pickle.PickleBuffer` with *obj* in Python.
+
+
+.. c:function:: const Py_buffer *PyPickleBuffer_GetBuffer(PyObject *picklebuf)
+
+   Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer wraps.
+
+   The returned pointer is valid as long as *picklebuf* is alive and has not been
+   released. The caller must not modify or free the returned :c:type:`Py_buffer`.
+   If the pickle buffer has been released, raise :exc:`ValueError`.
+
+   On success, return a pointer to the buffer view.
+   On failure, set an exception and return ``NULL``.
+
+
+.. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf)
+
+   Release the underlying buffer held by the pickle buffer.
+
+   Return ``0`` on success. On failure, set an exception and return ``-1``.
+
+   Analogous to calling :meth:`pickle.PickleBuffer.release` in Python.

Doc/c-api/stable.rst

@@ -279,7 +279,7 @@ The full API is described below for advanced use cases.
 
    .. c:member:: uint8_t abiinfo_minor_version
 
-      The major version of :c:struct:`PyABIInfo`.
+      The minor version of :c:struct:`PyABIInfo`.
       Must be set to ``0``; larger values are reserved for backwards-compatible
       future versions of :c:struct:`!PyABIInfo`.
 

Doc/c-api/structures.rst

@@ -447,6 +447,25 @@ definition with the same method name.
    slot.  This is helpful because calls to PyCFunctions are optimized more
    than wrapper object calls.
 
+
+.. c:var:: PyTypeObject PyCMethod_Type
+
+   The type object corresponding to Python C method objects. This is
+   available as :class:`types.BuiltinMethodType` in the Python layer.
+
+
+.. c:function:: int PyCMethod_Check(PyObject *op)
+
+   Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type
+   or a subtype of it. This function always succeeds.
+
+
+.. c:function:: int PyCMethod_CheckExact(PyObject *op)
+
+   This is the same as :c:func:`PyCMethod_Check`, but does not account for
+   subtypes.
+
+
 .. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
 
    Turn *ml* into a Python :term:`callable` object.
@@ -472,6 +491,24 @@ definition with the same method name.
    .. versionadded:: 3.9
 
 
+.. c:var:: PyTypeObject PyCFunction_Type
+
+   The type object corresponding to Python C function objects. This is
+   available as :class:`types.BuiltinFunctionType` in the Python layer.
+
+
+.. c:function:: int PyCFunction_Check(PyObject *op)
+
+   Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type
+   or a subtype of it. This function always succeeds.
+
+
+.. c:function:: int PyCFunction_CheckExact(PyObject *op)
+
+   This is the same as :c:func:`PyCFunction_Check`, but does not account for
+   subtypes.
+
+
 .. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
 
    Equivalent to ``PyCMethod_New(ml, self, module, NULL)``.
@@ -482,6 +519,62 @@ definition with the same method name.
    Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``.
 
 
+.. c:function:: int PyCFunction_GetFlags(PyObject *func)
+
+   Get the function's flags on *func* as they were passed to
+   :c:member:`~PyMethodDef.ml_flags`.
+
+   If *func* is not a C function object, this fails with an exception.
+   *func* must not be ``NULL``.
+
+   This function returns the function's flags on success, and ``-1`` with an
+   exception set on failure.
+
+
+.. c:function:: int PyCFunction_GET_FLAGS(PyObject *func)
+
+   This is the same as :c:func:`PyCFunction_GetFlags`, but without error
+   or type checking.
+
+
+.. c:function:: PyCFunction PyCFunction_GetFunction(PyObject *func)
+
+   Get the function pointer on *func* as it was passed to
+   :c:member:`~PyMethodDef.ml_meth`.
+
+   If *func* is not a C function object, this fails with an exception.
+   *func* must not be ``NULL``.
+
+   This function returns the function pointer on success, and ``NULL`` with an
+   exception set on failure.
+
+
+.. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func)
+
+   This is the same as :c:func:`PyCFunction_GetFunction`, but without error
+   or type checking.
+
+
+.. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func)
+
+   Get the "self" object on *func*. This is the object that would be passed
+   to the first argument of a :c:type:`PyCFunction`. For C function objects
+   created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this
+   is the resulting module object.
+
+   If *func* is not a C function object, this fails with an exception.
+   *func* must not be ``NULL``.
+
+   This function returns a :term:`borrowed reference` to the "self" object
+   on success, and ``NULL`` with an exception set on failure.
+
+
+.. c:function:: PyObject *PyCFunction_GET_SELF(PyObject *func)
+
+   This is the same as :c:func:`PyCFunction_GetSelf`, but without error or
+   type checking.
+
+
 Accessing attributes of extension types
 ---------------------------------------
 
@@ -605,14 +698,12 @@ The following flags can be used with :c:member:`PyMemberDef.flags`:
    entry indicates an offset from the subclass-specific data, rather than
    from ``PyObject``.
 
-   Can only be used as part of :c:member:`Py_tp_members <PyTypeObject.tp_members>`
+   Can only be used as part of the :c:data:`Py_tp_members`
    :c:type:`slot <PyType_Slot>` when creating a class using negative
    :c:member:`~PyType_Spec.basicsize`.
    It is mandatory in that case.
-
+   When setting :c:member:`~PyTypeObject.tp_members` from the slot during
-   This flag is only used in :c:type:`PyType_Slot`.
+   class creation, Python clears the flag and sets
-   When setting :c:member:`~PyTypeObject.tp_members` during
-   class creation, Python clears it and sets
    :c:member:`PyMemberDef.offset` to the offset from the ``PyObject`` struct.
 
 .. index::

Doc/c-api/sys.rst

@@ -123,6 +123,24 @@ Operating System Utilities
    This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`.  Do
    not call those functions directly!
 
+
+.. c:function:: int PyOS_InterruptOccurred(void)
+
+   Check if a :c:macro:`!SIGINT` signal has been received.
+
+   Returns ``1`` if a :c:macro:`!SIGINT` has occurred and clears the signal flag,
+   or ``0`` otherwise.
+
+   In most cases, you should prefer :c:func:`PyErr_CheckSignals` over this function.
+   :c:func:`!PyErr_CheckSignals` invokes the appropriate signal handlers
+   for all pending signals, allowing Python code to handle the signal properly.
+   This function only detects :c:macro:`!SIGINT` and does not invoke any Python
+   signal handlers.
+
+   This function is async-signal-safe and this function cannot fail.
+   The caller must hold an :term:`attached thread state`.
+
+
 .. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
 
    .. warning::

Doc/c-api/tuple.rst

@@ -61,7 +61,7 @@ Tuple Objects
 .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
 
    Take a pointer to a tuple object, and return the size of that tuple.
-   On error, return ``-1`` and with an exception set.
+   On error, return ``-1`` with an exception set.
 
 
 .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

Doc/c-api/type.rst

@@ -116,6 +116,20 @@ Type Objects
    .. versionadded:: 3.12
 
 
+.. c:function:: int PyType_Unwatch(int watcher_id, PyObject *type)
+
+   Mark *type* as not watched. This undoes a previous call to
+   :c:func:`PyType_Watch`. *type* must not be ``NULL``.
+
+   An extension should never call this function with a *watcher_id* that was
+   not returned to it by a previous call to :c:func:`PyType_AddWatcher`.
+
+   On success, this function returns ``0``. On failure, this function returns
+   ``-1`` with an exception set.
+
+   .. versionadded:: 3.12
+
+
 .. c:type:: int (*PyType_WatchCallback)(PyObject *type)
 
    Type of a type-watcher callback function.
@@ -133,6 +147,18 @@ Type Objects
    Type features are denoted by single bit flags.
 
 
+.. c:function:: int PyType_FastSubclass(PyTypeObject *type, int flag)
+
+   Return non-zero if the type object *type* sets the subclass flag *flag*.
+   Subclass flags are denoted by
+   :c:macro:`Py_TPFLAGS_*_SUBCLASS <Py_TPFLAGS_LONG_SUBCLASS>`.
+   This function is used by many ``_Check`` functions for common types.
+
+   .. seealso::
+       :c:func:`PyObject_TypeCheck`, which is used as a slower alternative in
+       ``_Check`` functions for types that don't come with subclass flags.
+
+
 .. c:function:: int PyType_IS_GC(PyTypeObject *o)
 
    Return true if the type object includes support for the cycle detector; this
@@ -169,12 +195,14 @@ Type Objects
    before initialization) and should be paired with :c:func:`PyObject_Free` in
    :c:member:`~PyTypeObject.tp_free`.
 
+
 .. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
 
    Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type
    object.  Creates a new instance using the type's
    :c:member:`~PyTypeObject.tp_alloc` slot and returns the resulting object.
 
+
 .. c:function:: int PyType_Ready(PyTypeObject *type)
 
    Finalize a type object.  This should be called on all type objects to finish
@@ -191,6 +219,7 @@ Type Objects
        GC protocol itself by at least implementing the
        :c:member:`~PyTypeObject.tp_traverse` handle.
 
+
 .. c:function:: PyObject* PyType_GetName(PyTypeObject *type)
 
    Return the type's name. Equivalent to getting the type's
@@ -198,6 +227,7 @@ Type Objects
 
    .. versionadded:: 3.11
 
+
 .. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
 
    Return the type's qualified name. Equivalent to getting the
@@ -213,6 +243,7 @@ Type Objects
 
    .. versionadded:: 3.13
 
+
 .. c:function:: PyObject* PyType_GetModuleName(PyTypeObject *type)
 
    Return the type's module name. Equivalent to getting the
@@ -220,6 +251,7 @@ Type Objects
 
    .. versionadded:: 3.13
 
+
 .. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
 
    Return the function pointer stored in the given slot. If the
@@ -236,6 +268,7 @@ Type Objects
       :c:func:`PyType_GetSlot` can now accept all types.
       Previously, it was limited to :ref:`heap types <heap-types>`.
 
+
 .. c:function:: PyObject* PyType_GetModule(PyTypeObject *type)
 
    Return the module object associated with the given type when the type was
@@ -255,6 +288,7 @@ Type Objects
 
    .. versionadded:: 3.9
 
+
 .. c:function:: void* PyType_GetModuleState(PyTypeObject *type)
 
    Return the state of the module object associated with the given type.
@@ -269,6 +303,7 @@ Type Objects
 
    .. versionadded:: 3.9
 
+
 .. c:function:: PyObject* PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
 
    Find the first superclass whose module was created from
@@ -288,6 +323,7 @@ Type Objects
 
    .. versionadded:: 3.11
 
+
 .. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)
 
    Find the first superclass in *type*'s :term:`method resolution order` whose
@@ -306,6 +342,7 @@ Type Objects
 
    .. versionadded:: 3.14
 
+
 .. c:function:: int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
 
    Attempt to assign a version tag to the given type.
@@ -316,6 +353,16 @@ Type Objects
    .. versionadded:: 3.12
 
 
+.. c:function:: int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)
+
+   Return true if instances of *type* support creating weak references, false
+   otherwise. This function always succeeds. *type* must not be ``NULL``.
+
+   .. seealso::
+      * :ref:`weakrefobjects`
+      * :py:mod:`weakref`
+
+
 Creating Heap-Allocated Types
 .............................
 
@@ -336,8 +383,8 @@ The following functions and structs are used to create
 
    The *bases* argument can be used to specify base classes; it can either
    be only one class or a tuple of classes.
-   If *bases* is ``NULL``, the *Py_tp_bases* slot is used instead.
+   If *bases* is ``NULL``, the :c:data:`Py_tp_bases` slot is used instead.
-   If that also is ``NULL``, the *Py_tp_base* slot is used instead.
+   If that also is ``NULL``, the :c:data:`Py_tp_base` slot is used instead.
    If that also is ``NULL``, the new type derives from :class:`object`.
 
    The *module* argument can be used to record the module in which the new
@@ -364,6 +411,7 @@ The following functions and structs are used to create
 
    .. versionadded:: 3.12
 
+
 .. c:function:: PyObject* PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
 
    Equivalent to ``PyType_FromMetaclass(NULL, module, spec, bases)``.
@@ -390,6 +438,7 @@ The following functions and structs are used to create
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
+
 .. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
 
    Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, bases)``.
@@ -411,6 +460,7 @@ The following functions and structs are used to create
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
+
 .. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
 
    Equivalent to ``PyType_FromMetaclass(NULL, NULL, spec, NULL)``.
@@ -431,6 +481,7 @@ The following functions and structs are used to create
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
+
 .. c:function:: int PyType_Freeze(PyTypeObject *type)
 
    Make a type immutable: set the :c:macro:`Py_TPFLAGS_IMMUTABLETYPE` flag.
@@ -539,9 +590,9 @@ The following functions and structs are used to create
       :c:type:`PyAsyncMethods` with an added ``Py_`` prefix.
       For example, use:
 
-      * ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc`
+      * :c:data:`Py_tp_dealloc` to set :c:member:`PyTypeObject.tp_dealloc`
-      * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
+      * :c:data:`Py_nb_add` to set :c:member:`PyNumberMethods.nb_add`
-      * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
+      * :c:data:`Py_sq_length` to set :c:member:`PySequenceMethods.sq_length`
 
       An additional slot is supported that does not correspond to a
       :c:type:`!PyTypeObject` struct field:
@@ -560,7 +611,7 @@ The following functions and structs are used to create
 
       If it is not possible to switch to a ``MANAGED`` flag (for example,
       for vectorcall or to support Python older than 3.12), specify the
-      offset in :c:member:`Py_tp_members <PyTypeObject.tp_members>`.
+      offset in :c:data:`Py_tp_members`.
       See :ref:`PyMemberDef documentation <pymemberdef-offsets>`
       for details.
 
@@ -587,8 +638,8 @@ The following functions and structs are used to create
          under the :ref:`limited API <limited-c-api>`.
 
       .. versionchanged:: 3.14
-         The field :c:member:`~PyTypeObject.tp_vectorcall` can now set
+         The field :c:member:`~PyTypeObject.tp_vectorcall` can now be set
-         using ``Py_tp_vectorcall``.  See the field's documentation
+         using :c:data:`Py_tp_vectorcall`.  See the field's documentation
          for details.
 
    .. c:member:: void *pfunc
@@ -598,10 +649,11 @@ The following functions and structs are used to create
 
       *pfunc* values may not be ``NULL``, except for the following slots:
 
-      * ``Py_tp_doc``
+      * :c:data:`Py_tp_doc`
       * :c:data:`Py_tp_token` (for clarity, prefer :c:data:`Py_TP_USE_SPEC`
         rather than ``NULL``)
 
+
 .. c:macro:: Py_tp_token
 
    A :c:member:`~PyType_Slot.slot` that records a static memory layout ID

Doc/c-api/typeobj.rst

@@ -676,6 +676,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: destructor PyTypeObject.tp_dealloc
 
+   .. corresponding-type-slot:: Py_tp_dealloc
+
    A pointer to the instance destructor function.  The function signature is::
 
       void tp_dealloc(PyObject *self);
@@ -860,6 +862,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: getattrfunc PyTypeObject.tp_getattr
 
+   .. corresponding-type-slot:: Py_tp_getattr
+
    An optional pointer to the get-attribute-string function.
 
    This field is deprecated.  When it is defined, it should point to a function
@@ -877,6 +881,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: setattrfunc PyTypeObject.tp_setattr
 
+   .. corresponding-type-slot:: Py_tp_setattr
+
    An optional pointer to the function for setting and deleting attributes.
 
    This field is deprecated.  When it is defined, it should point to a function
@@ -909,6 +915,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: reprfunc PyTypeObject.tp_repr
 
+   .. corresponding-type-slot:: Py_tp_repr
+
    .. index:: pair: built-in function; repr
 
    An optional pointer to a function that implements the built-in function
@@ -974,6 +982,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: hashfunc PyTypeObject.tp_hash
 
+   .. corresponding-type-slot:: Py_tp_hash
+
    .. index:: pair: built-in function; hash
 
    An optional pointer to a function that implements the built-in function
@@ -1015,6 +1025,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: ternaryfunc PyTypeObject.tp_call
 
+   .. corresponding-type-slot:: Py_tp_call
+
    An optional pointer to a function that implements calling the object.  This
    should be ``NULL`` if the object is not callable.  The signature is the same as
    for :c:func:`PyObject_Call`::
@@ -1028,6 +1040,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: reprfunc PyTypeObject.tp_str
 
+   .. corresponding-type-slot:: Py_tp_str
+
    An optional pointer to a function that implements the built-in operation
    :func:`str`.  (Note that :class:`str` is a type now, and :func:`str` calls the
    constructor for that type.  This constructor calls :c:func:`PyObject_Str` to do
@@ -1053,6 +1067,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: getattrofunc PyTypeObject.tp_getattro
 
+   .. corresponding-type-slot:: Py_tp_getattro
+
    An optional pointer to the get-attribute function.
 
    The signature is the same as for :c:func:`PyObject_GetAttr`::
@@ -1077,6 +1093,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: setattrofunc PyTypeObject.tp_setattro
 
+   .. corresponding-type-slot:: Py_tp_setattro
+
    An optional pointer to the function for setting and deleting attributes.
 
    The signature is the same as for :c:func:`PyObject_SetAttr`::
@@ -1333,8 +1351,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    .. c:macro:: Py_TPFLAGS_BASE_EXC_SUBCLASS
    .. c:macro:: Py_TPFLAGS_TYPE_SUBCLASS
 
-      These flags are used by functions such as
+      Functions such as :c:func:`PyLong_Check` will call :c:func:`PyType_FastSubclass`
-      :c:func:`PyLong_Check` to quickly determine if a type is a subclass
+      with one of these flags to quickly determine if a type is a subclass
       of a built-in type; such specific checks are faster than a generic
       check, like :c:func:`PyObject_IsInstance`. Custom types that inherit
       from built-ins should have their :c:member:`~PyTypeObject.tp_flags`
@@ -1475,6 +1493,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: const char* PyTypeObject.tp_doc
 
+   .. corresponding-type-slot:: Py_tp_doc
+
    An optional pointer to a NUL-terminated C string giving the docstring for this
    type object.  This is exposed as the :attr:`~type.__doc__` attribute on the
    type and instances of the type.
@@ -1486,6 +1506,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: traverseproc PyTypeObject.tp_traverse
 
+   .. corresponding-type-slot:: Py_tp_traverse
+
    An optional pointer to a traversal function for the garbage collector.  This is
    only used if the :c:macro:`Py_TPFLAGS_HAVE_GC` flag bit is set.  The signature is::
 
@@ -1582,6 +1604,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: inquiry PyTypeObject.tp_clear
 
+   .. corresponding-type-slot:: Py_tp_clear
+
    An optional pointer to a clear function.  The signature is::
 
       int tp_clear(PyObject *);
@@ -1730,6 +1754,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: richcmpfunc PyTypeObject.tp_richcompare
 
+   .. corresponding-type-slot:: Py_tp_richcompare
+
    An optional pointer to the rich comparison function, whose signature is::
 
       PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);
@@ -1832,6 +1858,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: getiterfunc PyTypeObject.tp_iter
 
+   .. corresponding-type-slot:: Py_tp_iter
+
    An optional pointer to a function that returns an :term:`iterator` for the
    object.  Its presence normally signals that the instances of this type are
    :term:`iterable` (although sequences may be iterable without this function).
@@ -1847,6 +1875,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: iternextfunc PyTypeObject.tp_iternext
 
+   .. corresponding-type-slot:: Py_tp_iternext
+
    An optional pointer to a function that returns the next item in an
    :term:`iterator`. The signature is::
 
@@ -1870,6 +1900,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: struct PyMethodDef* PyTypeObject.tp_methods
 
+   .. corresponding-type-slot:: Py_tp_methods
+
    An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMethodDef`
    structures, declaring regular methods of this type.
 
@@ -1884,6 +1916,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: struct PyMemberDef* PyTypeObject.tp_members
 
+   .. corresponding-type-slot:: Py_tp_members
+
    An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMemberDef`
    structures, declaring regular data members (fields or slots) of instances of
    this type.
@@ -1899,6 +1933,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset
 
+   .. corresponding-type-slot:: Py_tp_getset
+
    An optional pointer to a static ``NULL``-terminated array of :c:type:`PyGetSetDef`
    structures, declaring computed attributes of instances of this type.
 
@@ -1913,6 +1949,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: PyTypeObject* PyTypeObject.tp_base
 
+   .. corresponding-type-slot:: Py_tp_base
+
    An optional pointer to a base type from which type properties are inherited.  At
    this level, only single inheritance is supported; multiple inheritance require
    dynamically creating a type object by calling the metatype.
@@ -1985,6 +2023,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: descrgetfunc PyTypeObject.tp_descr_get
 
+   .. corresponding-type-slot:: Py_tp_descr_get
+
    An optional pointer to a "descriptor get" function.
 
    The function signature is::
@@ -2000,6 +2040,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: descrsetfunc PyTypeObject.tp_descr_set
 
+   .. corresponding-type-slot:: Py_tp_descr_set
+
    An optional pointer to a function for setting and deleting
    a descriptor's value.
 
@@ -2060,6 +2102,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: initproc PyTypeObject.tp_init
 
+   .. corresponding-type-slot:: Py_tp_init
+
    An optional pointer to an instance initialization function.
 
    This function corresponds to the :meth:`~object.__init__` method of classes.  Like
@@ -2095,6 +2139,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: allocfunc PyTypeObject.tp_alloc
 
+   .. corresponding-type-slot:: Py_tp_alloc
+
    An optional pointer to an instance allocation function.
 
    The function signature is::
@@ -2118,6 +2164,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: newfunc PyTypeObject.tp_new
 
+   .. corresponding-type-slot:: Py_tp_new
+
    An optional pointer to an instance creation function.
 
    The function signature is::
@@ -2157,6 +2205,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: freefunc PyTypeObject.tp_free
 
+   .. corresponding-type-slot:: Py_tp_free
+
    An optional pointer to an instance deallocation function.  Its signature is::
 
       void tp_free(void *self);
@@ -2186,6 +2236,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: inquiry PyTypeObject.tp_is_gc
 
+   .. corresponding-type-slot:: Py_tp_is_gc
+
    An optional pointer to a function called by the garbage collector.
 
    The garbage collector needs to know whether a particular object is collectible
@@ -2214,12 +2266,14 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: PyObject* PyTypeObject.tp_bases
 
+   .. corresponding-type-slot:: Py_tp_bases
+
    Tuple of base types.
 
    This field should be set to ``NULL`` and treated as read-only.
    Python will fill it in when the type is :c:func:`initialized <PyType_Ready>`.
 
-   For dynamically created classes, the ``Py_tp_bases``
+   For dynamically created classes, the :c:data:`Py_tp_bases`
    :c:type:`slot <PyType_Slot>` can be used instead of the *bases* argument
    of :c:func:`PyType_FromSpecWithBases`.
    The argument form is preferred.
@@ -2294,6 +2348,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: destructor PyTypeObject.tp_del
 
+   .. corresponding-type-slot:: Py_tp_del
+
    This field is deprecated.  Use :c:member:`~PyTypeObject.tp_finalize` instead.
 
 
@@ -2308,6 +2364,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: destructor PyTypeObject.tp_finalize
 
+   .. corresponding-type-slot:: Py_tp_finalize
+
    An optional pointer to an instance finalization function.  This is the C
    implementation of the :meth:`~object.__del__` special method.  Its signature
    is::
@@ -2466,6 +2524,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
 
 .. c:member:: vectorcallfunc PyTypeObject.tp_vectorcall
 
+   .. corresponding-type-slot:: Py_tp_vectorcall
+
    A :ref:`vectorcall function <vectorcall>` to use for calls of this type
    object (rather than instances).
    In other words, ``tp_vectorcall`` can be used to optimize ``type.__call__``,
@@ -2631,42 +2691,148 @@ Number Object Structures
       Python 3.0.1.
 
 .. c:member:: binaryfunc PyNumberMethods.nb_add
+
+   .. corresponding-type-slot:: Py_nb_add
+
 .. c:member:: binaryfunc PyNumberMethods.nb_subtract
+
+   .. corresponding-type-slot:: Py_nb_subtract
+
 .. c:member:: binaryfunc PyNumberMethods.nb_multiply
+
+   .. corresponding-type-slot:: Py_nb_multiply
+
 .. c:member:: binaryfunc PyNumberMethods.nb_remainder
+
+   .. corresponding-type-slot:: Py_nb_remainder
+
 .. c:member:: binaryfunc PyNumberMethods.nb_divmod
+
+   .. corresponding-type-slot:: Py_nb_divmod
+
 .. c:member:: ternaryfunc PyNumberMethods.nb_power
+
+   .. corresponding-type-slot:: Py_nb_power
+
 .. c:member:: unaryfunc PyNumberMethods.nb_negative
+
+   .. corresponding-type-slot:: Py_nb_negative
+
 .. c:member:: unaryfunc PyNumberMethods.nb_positive
+
+   .. corresponding-type-slot:: Py_nb_positive
+
 .. c:member:: unaryfunc PyNumberMethods.nb_absolute
+
+   .. corresponding-type-slot:: Py_nb_absolute
+
 .. c:member:: inquiry PyNumberMethods.nb_bool
+
+   .. corresponding-type-slot:: Py_nb_bool
+
 .. c:member:: unaryfunc PyNumberMethods.nb_invert
+
+   .. corresponding-type-slot:: Py_nb_invert
+
 .. c:member:: binaryfunc PyNumberMethods.nb_lshift
+
+   .. corresponding-type-slot:: Py_nb_lshift
+
 .. c:member:: binaryfunc PyNumberMethods.nb_rshift
+
+   .. corresponding-type-slot:: Py_nb_rshift
+
 .. c:member:: binaryfunc PyNumberMethods.nb_and
+
+   .. corresponding-type-slot:: Py_nb_and
+
 .. c:member:: binaryfunc PyNumberMethods.nb_xor
+
+   .. corresponding-type-slot:: Py_nb_xor
+
 .. c:member:: binaryfunc PyNumberMethods.nb_or
+
+   .. corresponding-type-slot:: Py_nb_or
+
 .. c:member:: unaryfunc PyNumberMethods.nb_int
+
+   .. corresponding-type-slot:: Py_nb_int
+
 .. c:member:: void *PyNumberMethods.nb_reserved
+
 .. c:member:: unaryfunc PyNumberMethods.nb_float
+
+   .. corresponding-type-slot:: Py_nb_float
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_add
+
+   .. corresponding-type-slot:: Py_nb_inplace_add
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract
+
+   .. corresponding-type-slot:: Py_nb_inplace_subtract
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_multiply
+
+   .. corresponding-type-slot:: Py_nb_inplace_multiply
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_remainder
+
+   .. corresponding-type-slot:: Py_nb_inplace_remainder
+
 .. c:member:: ternaryfunc PyNumberMethods.nb_inplace_power
+
+   .. corresponding-type-slot:: Py_nb_inplace_power
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_lshift
+
+   .. corresponding-type-slot:: Py_nb_inplace_lshift
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_rshift
+
+   .. corresponding-type-slot:: Py_nb_inplace_rshift
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_and
+
+   .. corresponding-type-slot:: Py_nb_inplace_and
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_xor
+
+   .. corresponding-type-slot:: Py_nb_inplace_xor
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_or
+
+   .. corresponding-type-slot:: Py_nb_inplace_or
+
 .. c:member:: binaryfunc PyNumberMethods.nb_floor_divide
+
+   .. corresponding-type-slot:: Py_nb_floor_divide
+
 .. c:member:: binaryfunc PyNumberMethods.nb_true_divide
+
+   .. corresponding-type-slot:: Py_nb_true_divide
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_floor_divide
+
+   .. corresponding-type-slot:: Py_nb_inplace_floor_divide
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_true_divide
+
+   .. corresponding-type-slot:: Py_nb_inplace_true_divide
+
 .. c:member:: unaryfunc PyNumberMethods.nb_index
+
+   .. corresponding-type-slot:: Py_nb_index
+
 .. c:member:: binaryfunc PyNumberMethods.nb_matrix_multiply
+
+   .. corresponding-type-slot:: Py_nb_matrix_multiply
+
 .. c:member:: binaryfunc PyNumberMethods.nb_inplace_matrix_multiply
 
+   .. corresponding-type-slot:: Py_nb_inplace_matrix_multiply
+
+
 
 .. _mapping-structs:
 
@@ -2683,12 +2849,16 @@ Mapping Object Structures
 
 .. c:member:: lenfunc PyMappingMethods.mp_length
 
+   .. corresponding-type-slot:: Py_mp_length
+
    This function is used by :c:func:`PyMapping_Size` and
    :c:func:`PyObject_Size`, and has the same signature.  This slot may be set to
    ``NULL`` if the object has no defined length.
 
 .. c:member:: binaryfunc PyMappingMethods.mp_subscript
 
+   .. corresponding-type-slot:: Py_mp_subscript
+
    This function is used by :c:func:`PyObject_GetItem` and
    :c:func:`PySequence_GetSlice`, and has the same signature as
    :c:func:`!PyObject_GetItem`.  This slot must be filled for the
@@ -2697,6 +2867,8 @@ Mapping Object Structures
 
 .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
 
+   .. corresponding-type-slot:: Py_mp_ass_subscript
+
    This function is used by :c:func:`PyObject_SetItem`,
    :c:func:`PyObject_DelItem`, :c:func:`PySequence_SetSlice` and
    :c:func:`PySequence_DelSlice`.  It has the same signature as
@@ -2720,6 +2892,8 @@ Sequence Object Structures
 
 .. c:member:: lenfunc PySequenceMethods.sq_length
 
+   .. corresponding-type-slot:: Py_sq_length
+
    This function is used by :c:func:`PySequence_Size` and
    :c:func:`PyObject_Size`, and has the same signature.  It is also used for
    handling negative indices via the :c:member:`~PySequenceMethods.sq_item`
@@ -2727,18 +2901,24 @@ Sequence Object Structures
 
 .. c:member:: binaryfunc PySequenceMethods.sq_concat
 
+   .. corresponding-type-slot:: Py_sq_concat
+
    This function is used by :c:func:`PySequence_Concat` and has the same
    signature.  It is also used by the ``+`` operator, after trying the numeric
    addition via the :c:member:`~PyNumberMethods.nb_add` slot.
 
 .. c:member:: ssizeargfunc PySequenceMethods.sq_repeat
 
+   .. corresponding-type-slot:: Py_sq_repeat
+
    This function is used by :c:func:`PySequence_Repeat` and has the same
    signature.  It is also used by the ``*`` operator, after trying numeric
    multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot.
 
 .. c:member:: ssizeargfunc PySequenceMethods.sq_item
 
+   .. corresponding-type-slot:: Py_sq_item
+
    This function is used by :c:func:`PySequence_GetItem` and has the same
    signature.  It is also used by :c:func:`PyObject_GetItem`, after trying
    the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot.
@@ -2752,6 +2932,8 @@ Sequence Object Structures
 
 .. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
 
+   .. corresponding-type-slot:: Py_sq_ass_item
+
    This function is used by :c:func:`PySequence_SetItem` and has the same
    signature.  It is also used by :c:func:`PyObject_SetItem` and
    :c:func:`PyObject_DelItem`, after trying the item assignment and deletion
@@ -2761,6 +2943,8 @@ Sequence Object Structures
 
 .. c:member:: objobjproc PySequenceMethods.sq_contains
 
+   .. corresponding-type-slot:: Py_sq_contains
+
    This function may be used by :c:func:`PySequence_Contains` and has the same
    signature.  This slot may be left to ``NULL``, in this case
    :c:func:`!PySequence_Contains` simply traverses the sequence until it
@@ -2768,6 +2952,8 @@ Sequence Object Structures
 
 .. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat
 
+   .. corresponding-type-slot:: Py_sq_inplace_concat
+
    This function is used by :c:func:`PySequence_InPlaceConcat` and has the same
    signature.  It should modify its first operand, and return it.  This slot
    may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat`
@@ -2777,6 +2963,8 @@ Sequence Object Structures
 
 .. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
 
+   .. corresponding-type-slot:: Py_sq_inplace_repeat
+
    This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same
    signature.  It should modify its first operand, and return it.  This slot
    may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat`
@@ -2802,6 +2990,8 @@ Buffer Object Structures
 
 .. c:member:: getbufferproc PyBufferProcs.bf_getbuffer
 
+   .. corresponding-type-slot:: Py_bf_getbuffer
+
    The signature of this function is::
 
        int (PyObject *exporter, Py_buffer *view, int flags);
@@ -2851,6 +3041,8 @@ Buffer Object Structures
 
 .. c:member:: releasebufferproc PyBufferProcs.bf_releasebuffer
 
+   .. corresponding-type-slot:: Py_bf_releasebuffer
+
    The signature of this function is::
 
        void (PyObject *exporter, Py_buffer *view);
@@ -2905,6 +3097,8 @@ Async Object Structures
 
 .. c:member:: unaryfunc PyAsyncMethods.am_await
 
+   .. corresponding-type-slot:: Py_am_await
+
    The signature of this function is::
 
       PyObject *am_await(PyObject *self);
@@ -2916,6 +3110,8 @@ Async Object Structures
 
 .. c:member:: unaryfunc PyAsyncMethods.am_aiter
 
+   .. corresponding-type-slot:: Py_am_aiter
+
    The signature of this function is::
 
       PyObject *am_aiter(PyObject *self);
@@ -2928,6 +3124,8 @@ Async Object Structures
 
 .. c:member:: unaryfunc PyAsyncMethods.am_anext
 
+   .. corresponding-type-slot:: Py_am_anext
+
    The signature of this function is::
 
       PyObject *am_anext(PyObject *self);
@@ -2938,6 +3136,8 @@ Async Object Structures
 
 .. c:member:: sendfunc PyAsyncMethods.am_send
 
+   .. corresponding-type-slot:: Py_am_send
+
    The signature of this function is::
 
       PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);

Doc/c-api/unicode.rst

@@ -321,12 +321,22 @@ These APIs can be used to work with surrogates:
 
    Check if *ch* is a low surrogate (``0xDC00 <= ch <= 0xDFFF``).
 
+.. c:function:: Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)
+
+    Return the high UTF-16 surrogate (``0xD800`` to ``0xDBFF``) for a Unicode
+    code point in the range ``[0x10000; 0x10FFFF]``.
+
+.. c:function:: Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)
+
+    Return the low UTF-16 surrogate (``0xDC00`` to ``0xDFFF``) for a Unicode
+    code point in the range ``[0x10000; 0x10FFFF]``.
+
 .. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
 
    Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
    *high* and *low* are respectively the leading and trailing surrogates in a
-   surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
+   surrogate pair. *high* must be in the range ``[0xD800; 0xDBFF]`` and *low* must
-   be in the range [0xDC00; 0xDFFF].
+   be in the range ``[0xDC00; 0xDFFF]``.
 
 
 Creating and accessing Unicode strings

Doc/c-api/veryhigh.rst

@@ -13,8 +13,9 @@ the interpreter.
 
 Several of these functions accept a start symbol from the grammar as a
 parameter.  The available start symbols are :c:data:`Py_eval_input`,
-:c:data:`Py_file_input`, and :c:data:`Py_single_input`.  These are described
+:c:data:`Py_file_input`, :c:data:`Py_single_input`, and
-following the functions which accept them as parameters.
+:c:data:`Py_func_type_input`.  These are described following the functions
+which accept them as parameters.
 
 Note also that several of these functions take :c:expr:`FILE*` parameters.  One
 particular issue which needs to be handled carefully is that the :c:type:`FILE`
@@ -99,6 +100,20 @@ the same library that the Python runtime is using.
       Otherwise, Python may not handle script file with LF line ending correctly.
 
 
+.. c:function:: int PyRun_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)
+
+   Read and execute a single statement from a file associated with an
+   interactive device according to the *flags* argument.  The user will be
+   prompted using ``sys.ps1`` and ``sys.ps2``. *filename* must be a Python
+   :class:`str` object.
+
+   Returns ``0`` when the input was
+   executed successfully, ``-1`` if there was an exception, or an error code
+   from the :file:`errcode.h` include file distributed as part of Python if
+   there was a parse error.  (Note that :file:`errcode.h` is not included by
+   :file:`Python.h`, so must be included specifically if needed.)
+
+
 .. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
 
    This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
@@ -107,17 +122,10 @@ the same library that the Python runtime is using.
 
 .. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
 
-   Read and execute a single statement from a file associated with an
+   Similar to :c:func:`PyRun_InteractiveOneObject`, but *filename* is a
-   interactive device according to the *flags* argument.  The user will be
+   :c:expr:`const char*`, which is decoded from the
-   prompted using ``sys.ps1`` and ``sys.ps2``.  *filename* is decoded from the
    :term:`filesystem encoding and error handler`.
 
-   Returns ``0`` when the input was
-   executed successfully, ``-1`` if there was an exception, or an error code
-   from the :file:`errcode.h` include file distributed as part of Python if
-   there was a parse error.  (Note that :file:`errcode.h` is not included by
-   :file:`Python.h`, so must be included specifically if needed.)
-
 
 .. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
 
@@ -140,7 +148,7 @@ the same library that the Python runtime is using.
    interpreter prompt is about to become idle and wait for user input
    from the terminal.  The return value is ignored.  Overriding this
    hook can be used to integrate the interpreter's prompt with other
-   event loops, as done in the :file:`Modules/_tkinter.c` in the
+   event loops, as done in :file:`Modules/_tkinter.c` in the
    Python source code.
 
    .. versionchanged:: 3.12
@@ -183,8 +191,7 @@ the same library that the Python runtime is using.
    objects *globals* and *locals* with the compiler flags specified by
    *flags*.  *globals* must be a dictionary; *locals* can be any object
    that implements the mapping protocol.  The parameter *start* specifies
-   the start symbol and must one of the following:
+   the start symbol and must one of the :ref:`available start symbols <start-symbols>`.
-   :c:data:`Py_eval_input`, :c:data:`Py_file_input`, or :c:data:`Py_single_input`.
 
    Returns the result of executing the code as a Python object, or ``NULL`` if an
    exception was raised.
@@ -233,8 +240,8 @@ the same library that the Python runtime is using.
 
    Parse and compile the Python source code in *str*, returning the resulting code
    object.  The start symbol is given by *start*; this can be used to constrain the
-   code which can be compiled and should be :c:data:`Py_eval_input`,
+   code which can be compiled and should be :ref:`available start symbols
-   :c:data:`Py_file_input`, or :c:data:`Py_single_input`.  The filename specified by
+   <start-symbols>`.  The filename specified by
    *filename* is used to construct the code object and may appear in tracebacks or
    :exc:`SyntaxError` exception messages.  This returns ``NULL`` if the code
    cannot be parsed or compiled.
@@ -297,32 +304,6 @@ the same library that the Python runtime is using.
    true on success, false on failure.
 
 
-.. c:var:: int Py_eval_input
-
-   .. index:: single: Py_CompileString (C function)
-
-   The start symbol from the Python grammar for isolated expressions; for use with
-   :c:func:`Py_CompileString`.
-
-
-.. c:var:: int Py_file_input
-
-   .. index:: single: Py_CompileString (C function)
-
-   The start symbol from the Python grammar for sequences of statements as read
-   from a file or other source; for use with :c:func:`Py_CompileString`.  This is
-   the symbol to use when compiling arbitrarily long Python source code.
-
-
-.. c:var:: int Py_single_input
-
-   .. index:: single: Py_CompileString (C function)
-
-   The start symbol from the Python grammar for a single statement; for use with
-   :c:func:`Py_CompileString`. This is the symbol used for the interactive
-   interpreter loop.
-
-
 .. c:struct:: PyCompilerFlags
 
    This is the structure used to hold compiler flags.  In cases where code is only
@@ -366,3 +347,52 @@ the same library that the Python runtime is using.
    as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
    selectable using :ref:`future statements <future>`.
    See :ref:`c_codeobject_flags` for a complete list.
+
+
+.. _start-symbols:
+
+Available start symbols
+^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. c:var:: int Py_eval_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for isolated expressions; for use with
+   :c:func:`Py_CompileString`.
+
+
+.. c:var:: int Py_file_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for sequences of statements as read
+   from a file or other source; for use with :c:func:`Py_CompileString`.  This is
+   the symbol to use when compiling arbitrarily long Python source code.
+
+
+.. c:var:: int Py_single_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for a single statement; for use with
+   :c:func:`Py_CompileString`. This is the symbol used for the interactive
+   interpreter loop.
+
+
+.. c:var:: int Py_func_type_input
+
+   .. index:: single: Py_CompileString (C function)
+
+   The start symbol from the Python grammar for a function type; for use with
+   :c:func:`Py_CompileString`. This is used to parse "signature type comments"
+   from :pep:`484`.
+
+   This requires the :c:macro:`PyCF_ONLY_AST` flag to be set.
+
+   .. seealso::
+      * :py:class:`ast.FunctionType`
+      * :pep:`484`
+
+   .. versionadded:: 3.8

Doc/c-api/weakref.rst

@@ -19,7 +19,14 @@ as much as it can.
 
 .. c:function:: int PyWeakref_CheckRef(PyObject *ob)
 
-   Return non-zero if *ob* is a reference object.  This function always succeeds.
+   Return non-zero if *ob* is a reference object or a subclass of the reference
+   type.  This function always succeeds.
+
+
+.. c:function:: int PyWeakref_CheckRefExact(PyObject *ob)
+
+   Return non-zero if *ob* is a reference object, but not a subclass of the
+   reference type.  This function always succeeds.
 
 
 .. c:function:: int PyWeakref_CheckProxy(PyObject *ob)
@@ -38,6 +45,10 @@ as much as it can.
    weakly referenceable object, or if *callback* is not callable, ``None``, or
    ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
+   .. seealso::
+      :c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly
+      referenceable.
+
 
 .. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
 
@@ -50,6 +61,10 @@ as much as it can.
    is not a weakly referenceable object, or if *callback* is not callable,
    ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
 
+   .. seealso::
+      :c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly
+      referenceable.
+
 
 .. c:function:: int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
 

Doc/conf.py

@@ -226,9 +226,6 @@
 # Temporary undocumented names.
 # In future this list must be empty.
 nitpick_ignore += [
-    # Undocumented public C macros
-    ('c:macro', 'Py_BUILD_ASSERT'),
-    ('c:macro', 'Py_BUILD_ASSERT_EXPR'),
     # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
     # be resolved, as the method is currently undocumented. For context, see
     # https://github.com/python/cpython/pull/103289.
@@ -364,7 +361,7 @@
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
-_stdauthor = 'Guido van Rossum and the Python development team'
+_stdauthor = 'The Python development team'
 latex_documents = [
     ('c-api/index', 'c-api.tex', 'The Python/C API', _stdauthor, 'manual'),
     (

Doc/data/stable_abi.dat

@@ -1,7 +1,21 @@
 role,name,added,ifdef_note,struct_abi_kind
+macro,METH_CLASS,3.2,,
+macro,METH_COEXIST,3.2,,
+macro,METH_FASTCALL,3.7,,
+macro,METH_METHOD,3.7,,
+macro,METH_NOARGS,3.2,,
+macro,METH_O,3.2,,
+macro,METH_STATIC,3.2,,
+macro,METH_VARARGS,3.2,,
 macro,PY_VECTORCALL_ARGUMENTS_OFFSET,3.12,,
 type,PyABIInfo,3.15,,full-abi
 func,PyABIInfo_Check,3.15,,
+macro,PyABIInfo_DEFAULT_ABI_VERSION,3.15,,
+macro,PyABIInfo_DEFAULT_FLAGS,3.15,,
+macro,PyABIInfo_FREETHREADED,3.15,,
+macro,PyABIInfo_FREETHREADING_AGNOSTIC,3.15,,
+macro,PyABIInfo_GIL,3.15,,
+macro,PyABIInfo_STABLE,3.15,,
 macro,PyABIInfo_VAR,3.15,,
 func,PyAIter_Check,3.10,,
 func,PyArg_Parse,3.2,,
@@ -11,6 +25,26 @@ func,PyArg_UnpackTuple,3.2,,
 func,PyArg_VaParse,3.2,,
 func,PyArg_VaParseTupleAndKeywords,3.2,,
 func,PyArg_ValidateKeywordArguments,3.2,,
+macro,PyBUF_ANY_CONTIGUOUS,3.11,,
+macro,PyBUF_CONTIG,3.11,,
+macro,PyBUF_CONTIG_RO,3.11,,
+macro,PyBUF_C_CONTIGUOUS,3.11,,
+macro,PyBUF_FORMAT,3.11,,
+macro,PyBUF_FULL,3.11,,
+macro,PyBUF_FULL_RO,3.11,,
+macro,PyBUF_F_CONTIGUOUS,3.11,,
+macro,PyBUF_INDIRECT,3.11,,
+macro,PyBUF_MAX_NDIM,3.11,,
+macro,PyBUF_ND,3.11,,
+macro,PyBUF_READ,3.11,,
+macro,PyBUF_RECORDS,3.11,,
+macro,PyBUF_RECORDS_RO,3.11,,
+macro,PyBUF_SIMPLE,3.11,,
+macro,PyBUF_STRIDED,3.11,,
+macro,PyBUF_STRIDED_RO,3.11,,
+macro,PyBUF_STRIDES,3.11,,
+macro,PyBUF_WRITABLE,3.11,,
+macro,PyBUF_WRITE,3.11,,
 data,PyBaseObject_Type,3.2,,
 func,PyBool_FromLong,3.2,,
 data,PyBool_Type,3.2,,
@@ -126,6 +160,7 @@ func,PyDict_Merge,3.2,,
 func,PyDict_MergeFromSeq2,3.2,,
 func,PyDict_New,3.2,,
 func,PyDict_Next,3.2,,
+func,PyDict_SetDefaultRef,3.15,,
 func,PyDict_SetItem,3.2,,
 func,PyDict_SetItemString,3.2,,
 func,PyDict_Size,3.2,,
@@ -391,6 +426,7 @@ func,PyLong_FromUnsignedNativeBytes,3.14,,
 func,PyLong_FromVoidPtr,3.2,,
 func,PyLong_GetInfo,3.2,,
 data,PyLong_Type,3.2,,
+macro,PyMODEXPORT_FUNC,3.15,,
 data,PyMap_Type,3.2,,
 func,PyMapping_Check,3.2,,
 func,PyMapping_GetItemString,3.2,,
@@ -437,8 +473,10 @@ func,PyModule_AddObjectRef,3.10,,
 func,PyModule_AddStringConstant,3.2,,
 func,PyModule_AddType,3.10,,
 func,PyModule_Create2,3.2,,
+func,PyModule_Exec,3.15,,
 func,PyModule_ExecDef,3.7,,
 func,PyModule_FromDefAndSpec2,3.7,,
+func,PyModule_FromSlotsAndSpec,3.15,,
 func,PyModule_GetDef,3.2,,
 func,PyModule_GetDict,3.2,,
 func,PyModule_GetFilename,3.2,,
@@ -446,6 +484,8 @@ func,PyModule_GetFilenameObject,3.2,,
 func,PyModule_GetName,3.2,,
 func,PyModule_GetNameObject,3.7,,
 func,PyModule_GetState,3.2,,
+func,PyModule_GetStateSize,3.15,,
+func,PyModule_GetToken,3.15,,
 func,PyModule_New,3.2,,
 func,PyModule_NewObject,3.7,,
 func,PyModule_SetDocString,3.7,,
@@ -704,6 +744,7 @@ func,PyType_GetFlags,3.2,,
 func,PyType_GetFullyQualifiedName,3.13,,
 func,PyType_GetModule,3.10,,
 func,PyType_GetModuleByDef,3.13,,
+func,PyType_GetModuleByToken,3.15,,
 func,PyType_GetModuleName,3.13,,
 func,PyType_GetModuleState,3.10,,
 func,PyType_GetName,3.11,,
@@ -836,6 +877,14 @@ func,PyWeakref_NewRef,3.2,,
 data,PyWrapperDescr_Type,3.2,,
 func,PyWrapper_New,3.2,,
 data,PyZip_Type,3.2,,
+macro,Py_ASNATIVEBYTES_ALLOW_INDEX,3.14,,
+macro,Py_ASNATIVEBYTES_BIG_ENDIAN,3.14,,
+macro,Py_ASNATIVEBYTES_DEFAULTS,3.14,,
+macro,Py_ASNATIVEBYTES_LITTLE_ENDIAN,3.14,,
+macro,Py_ASNATIVEBYTES_NATIVE_ENDIAN,3.14,,
+macro,Py_ASNATIVEBYTES_REJECT_NEGATIVE,3.14,,
+macro,Py_ASNATIVEBYTES_UNSIGNED_BUFFER,3.14,,
+macro,Py_AUDIT_READ,3.12,,
 func,Py_AddPendingCall,3.2,,
 func,Py_AtExit,3.2,,
 macro,Py_BEGIN_ALLOW_THREADS,3.2,,
@@ -882,22 +931,141 @@ func,Py_NewInterpreter,3.2,,
 func,Py_NewRef,3.10,,
 func,Py_PACK_FULL_VERSION,3.14,,
 func,Py_PACK_VERSION,3.14,,
+macro,Py_READONLY,3.12,,
 func,Py_REFCNT,3.14,,
+macro,Py_RELATIVE_OFFSET,3.12,,
 func,Py_ReprEnter,3.2,,
 func,Py_ReprLeave,3.2,,
 func,Py_SetProgramName,3.2,,
 func,Py_SetPythonHome,3.2,,
 func,Py_SetRecursionLimit,3.2,,
+macro,Py_TPFLAGS_BASETYPE,3.2,,
+macro,Py_TPFLAGS_DEFAULT,3.2,,
+macro,Py_TPFLAGS_HAVE_GC,3.2,,
+macro,Py_TPFLAGS_HAVE_VECTORCALL,3.12,,
+macro,Py_TPFLAGS_ITEMS_AT_END,3.12,,
+macro,Py_TPFLAGS_METHOD_DESCRIPTOR,3.8,,
+macro,Py_TP_USE_SPEC,3.14,,
 func,Py_TYPE,3.14,,
+macro,Py_T_BOOL,3.12,,
+macro,Py_T_BYTE,3.12,,
+macro,Py_T_CHAR,3.12,,
+macro,Py_T_DOUBLE,3.12,,
+macro,Py_T_FLOAT,3.12,,
+macro,Py_T_INT,3.12,,
+macro,Py_T_LONG,3.12,,
+macro,Py_T_LONGLONG,3.12,,
+macro,Py_T_OBJECT_EX,3.12,,
+macro,Py_T_PYSSIZET,3.12,,
+macro,Py_T_SHORT,3.12,,
+macro,Py_T_STRING,3.12,,
+macro,Py_T_STRING_INPLACE,3.12,,
+macro,Py_T_UBYTE,3.12,,
+macro,Py_T_UINT,3.12,,
+macro,Py_T_ULONG,3.12,,
+macro,Py_T_ULONGLONG,3.12,,
+macro,Py_T_USHORT,3.12,,
 type,Py_UCS4,3.2,,
 macro,Py_UNBLOCK_THREADS,3.2,,
 data,Py_UTF8Mode,3.8,,
 func,Py_VaBuildValue,3.2,,
 data,Py_Version,3.11,,
 func,Py_XNewRef,3.10,,
+macro,Py_am_aiter,3.5,,
+macro,Py_am_anext,3.5,,
+macro,Py_am_await,3.5,,
+macro,Py_am_send,3.10,,
+macro,Py_bf_getbuffer,3.11,,
+macro,Py_bf_releasebuffer,3.11,,
 type,Py_buffer,3.11,,full-abi
 type,Py_intptr_t,3.2,,
+macro,Py_mod_abi,3.15,,
+macro,Py_mod_doc,3.15,,
+macro,Py_mod_methods,3.15,,
+macro,Py_mod_name,3.15,,
+macro,Py_mod_state_clear,3.15,,
+macro,Py_mod_state_free,3.15,,
+macro,Py_mod_state_size,3.15,,
+macro,Py_mod_state_traverse,3.15,,
+macro,Py_mod_token,3.15,,
+macro,Py_mp_ass_subscript,3.2,,
+macro,Py_mp_length,3.2,,
+macro,Py_mp_subscript,3.2,,
+macro,Py_nb_absolute,3.2,,
+macro,Py_nb_add,3.2,,
+macro,Py_nb_and,3.2,,
+macro,Py_nb_bool,3.2,,
+macro,Py_nb_divmod,3.2,,
+macro,Py_nb_float,3.2,,
+macro,Py_nb_floor_divide,3.2,,
+macro,Py_nb_index,3.2,,
+macro,Py_nb_inplace_add,3.2,,
+macro,Py_nb_inplace_and,3.2,,
+macro,Py_nb_inplace_floor_divide,3.2,,
+macro,Py_nb_inplace_lshift,3.2,,
+macro,Py_nb_inplace_matrix_multiply,3.5,,
+macro,Py_nb_inplace_multiply,3.2,,
+macro,Py_nb_inplace_or,3.2,,
+macro,Py_nb_inplace_power,3.2,,
+macro,Py_nb_inplace_remainder,3.2,,
+macro,Py_nb_inplace_rshift,3.2,,
+macro,Py_nb_inplace_subtract,3.2,,
+macro,Py_nb_inplace_true_divide,3.2,,
+macro,Py_nb_inplace_xor,3.2,,
+macro,Py_nb_int,3.2,,
+macro,Py_nb_invert,3.2,,
+macro,Py_nb_lshift,3.2,,
+macro,Py_nb_matrix_multiply,3.5,,
+macro,Py_nb_multiply,3.2,,
+macro,Py_nb_negative,3.2,,
+macro,Py_nb_or,3.2,,
+macro,Py_nb_positive,3.2,,
+macro,Py_nb_power,3.2,,
+macro,Py_nb_remainder,3.2,,
+macro,Py_nb_rshift,3.2,,
+macro,Py_nb_subtract,3.2,,
+macro,Py_nb_true_divide,3.2,,
+macro,Py_nb_xor,3.2,,
+macro,Py_sq_ass_item,3.2,,
+macro,Py_sq_concat,3.2,,
+macro,Py_sq_contains,3.2,,
+macro,Py_sq_inplace_concat,3.2,,
+macro,Py_sq_inplace_repeat,3.2,,
+macro,Py_sq_item,3.2,,
+macro,Py_sq_length,3.2,,
+macro,Py_sq_repeat,3.2,,
 type,Py_ssize_t,3.2,,
+macro,Py_tp_alloc,3.2,,
+macro,Py_tp_base,3.2,,
+macro,Py_tp_bases,3.2,,
+macro,Py_tp_call,3.2,,
+macro,Py_tp_clear,3.2,,
+macro,Py_tp_dealloc,3.2,,
+macro,Py_tp_del,3.2,,
+macro,Py_tp_descr_get,3.2,,
+macro,Py_tp_descr_set,3.2,,
+macro,Py_tp_doc,3.2,,
+macro,Py_tp_finalize,3.5,,
+macro,Py_tp_free,3.2,,
+macro,Py_tp_getattr,3.2,,
+macro,Py_tp_getattro,3.2,,
+macro,Py_tp_getset,3.2,,
+macro,Py_tp_hash,3.2,,
+macro,Py_tp_init,3.2,,
+macro,Py_tp_is_gc,3.2,,
+macro,Py_tp_iter,3.2,,
+macro,Py_tp_iternext,3.2,,
+macro,Py_tp_members,3.2,,
+macro,Py_tp_methods,3.2,,
+macro,Py_tp_new,3.2,,
+macro,Py_tp_repr,3.2,,
+macro,Py_tp_richcompare,3.2,,
+macro,Py_tp_setattr,3.2,,
+macro,Py_tp_setattro,3.2,,
+macro,Py_tp_str,3.2,,
+macro,Py_tp_token,3.14,,
+macro,Py_tp_traverse,3.2,,
+macro,Py_tp_vectorcall,3.14,,
 type,Py_uintptr_t,3.2,,
 type,allocfunc,3.2,,
 type,binaryfunc,3.2,,

Doc/deprecations/c-api-pending-removal-in-3.20.rst

@@ -5,3 +5,5 @@ Pending removal in Python 3.20
   Use :c:func:`PyComplex_AsCComplex` and :c:func:`PyComplex_FromCComplex`
   to convert a Python complex number to/from the C :c:type:`Py_complex`
   representation.
+
+* Macros :c:macro:`!Py_MATH_PIl` and :c:macro:`!Py_MATH_El`.

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

@@ -38,15 +38,3 @@ APIs:
 * :meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)
 * :class:`!webbrowser.MacOSX` (:gh:`86421`)
 * :class:`classmethod` descriptor chaining (:gh:`89519`)
-* :mod:`importlib.resources` deprecated methods:
-
-  * ``contents()``
-  * ``is_resource()``
-  * ``open_binary()``
-  * ``open_text()``
-  * ``path()``
-  * ``read_binary()``
-  * ``read_text()``
-
-  Use :func:`importlib.resources.files` instead.  Refer to `importlib-resources: Migrating from Legacy
-  <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_ (:gh:`106531`)

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

@@ -63,9 +63,9 @@ Pending removal in Python 3.16
 
 * :mod:`logging`:
 
-  Support for custom logging handlers with the *strm* argument is deprecated
+  * Support for custom logging handlers with the *strm* argument is deprecated
-  and scheduled for removal in Python 3.16. Define handlers with the *stream*
+    and scheduled for removal in Python 3.16. Define handlers with the *stream*
-  argument instead. (Contributed by Mariusz Felisiak in :gh:`115032`.)
+    argument instead. (Contributed by Mariusz Felisiak in :gh:`115032`.)
 
 * :mod:`mimetypes`:
 

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

@@ -23,6 +23,12 @@ Pending removal in Python 3.17
     (Contributed by Shantanu Jain in :gh:`91896`.)
 
 
+* :mod:`encodings`:
+
+  - Passing non-ascii *encoding* names to :func:`encodings.normalize_encoding`
+    is deprecated and scheduled for removal in Python 3.17.
+    (Contributed by Stan Ulbrych in :gh:`136702`)
+
 * :mod:`typing`:
 
   - Before Python 3.14, old-style unions were implemented using the private class

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

@@ -76,7 +76,7 @@ although there is currently no date scheduled for their removal.
 * :mod:`mailbox`: Use of StringIO input and text mode is deprecated, use
   BytesIO and binary mode instead.
 
-* :mod:`os`: Calling :func:`os.register_at_fork` in multi-threaded process.
+* :mod:`os`: Calling :func:`os.register_at_fork` in a multi-threaded process.
 
 * :class:`!pydoc.ErrorDuringImport`: A tuple value for *exc_info* parameter is
   deprecated, use an exception instance.

Doc/glossary.rst

@@ -1025,6 +1025,15 @@ Glossary
       applied to all scopes, only those relying on a known set of local
       and nonlocal variable names are restricted to optimized scopes.
 
+   optional module
+      An :term:`extension module` that is part of the :term:`standard library`,
+      but may be absent in some builds of :term:`CPython`,
+      usually due to missing third-party libraries or because the module
+      is not available for a given platform.
+
+      See :ref:`optional-module-requirements` for a list of optional modules
+      that require third-party libraries.
+
    package
       A Python :term:`module` which can contain submodules or recursively,
       subpackages.  Technically, a package is a Python module with a

Doc/howto/a-conceptual-overview-of-asyncio.rst

@@ -1,7 +1,7 @@
 .. _a-conceptual-overview-of-asyncio:
 
 ****************************************
-A Conceptual Overview of :mod:`!asyncio`
+A conceptual overview of :mod:`!asyncio`
 ****************************************
 
 This :ref:`HOWTO <how-tos>` article seeks to help you build a sturdy mental
@@ -37,15 +37,15 @@ In part 1, we'll cover the main, high-level building blocks of :mod:`!asyncio`:
 the event loop, coroutine functions, coroutine objects, tasks, and ``await``.
 
 ==========
-Event Loop
+Event loop
 ==========
 
 Everything in :mod:`!asyncio` happens relative to the event loop.
-It's the star of the show.
+It's the star of the show, but prefers to work behind the scenes, managing
+and coordinating resources.
 It's like an orchestra conductor.
-It's behind the scenes managing resources.
 Some power is explicitly granted to it, but a lot of its ability to get things
-done comes from the respect and cooperation of its worker bees.
+done comes from the respect and cooperation of its band members.
 
 In more technical terms, the event loop contains a collection of jobs to be run.
 Some jobs are added directly by you, and some indirectly by :mod:`!asyncio`.
@@ -59,7 +59,7 @@ This process repeats indefinitely, with the event loop cycling endlessly
 onwards.
 If there are no more jobs pending execution, the event loop is smart enough to
 rest and avoid needlessly wasting CPU cycles, and will come back when there's
-more work to be done.
+more work to be done, such as when I/O operations complete or timers expire.
 
 Effective execution relies on jobs sharing well and cooperating; a greedy job
 could hog control and leave the other jobs to starve, rendering the overall
@@ -170,14 +170,14 @@ Roughly speaking, :ref:`tasks <asyncio-task-obj>` are coroutines (not coroutine
 functions) tied to an event loop.
 A task also maintains a list of callback functions whose importance will become
 clear in a moment when we discuss :keyword:`await`.
-The recommended way to create tasks is via :func:`asyncio.create_task`.
 
 Creating a task automatically schedules it for execution (by adding a
 callback to run it in the event loop's to-do list, that is, collection of jobs).
+The recommended way to create tasks is via :func:`asyncio.create_task`.
 
-Since there's only one event loop (in each thread), :mod:`!asyncio` takes care of
+Since there's only one event loop (in each thread), :mod:`!asyncio` takes
-associating the task with the event loop for you. As such, there's no need
+care of associating the task with the event loop for you.
-to specify the event loop.
+As such, there's no need to specify the event loop.
 
 ::
 
@@ -250,6 +250,10 @@ different ways::
 In a crucial way, the behavior of ``await`` depends on the type of object
 being awaited.
 
+^^^^^^^^^^^^^^
+Awaiting tasks
+^^^^^^^^^^^^^^
+
 Awaiting a task will cede control from the current task or coroutine to
 the event loop.
 In the process of relinquishing control, a few important things happen.
@@ -281,6 +285,10 @@ This is a basic, yet reliable mental model.
 In practice, the control handoffs are slightly more complex, but not by much.
 In part 2, we'll walk through the details that make this possible.
 
+^^^^^^^^^^^^^^^^^^^
+Awaiting coroutines
+^^^^^^^^^^^^^^^^^^^
+
 **Unlike tasks, awaiting a coroutine does not hand control back to the event
 loop!**
 Wrapping a coroutine in a task first, then awaiting that would cede
@@ -347,8 +355,10 @@ The design intentionally trades off some conceptual clarity around usage of
 ``await`` for improved performance.
 Each time a task is awaited, control needs to be passed all the way up the
 call stack to the event loop.
-That might sound minor, but in a large program with many ``await`` statements and a deep
+Then, the event loop needs to manage its internal state and work through
-call stack, that overhead can add up to a meaningful performance drag.
+its processing logic to resume the next job.
+That might sound minor, but in a large program with many ``await``\ s, that
+overhead can add up to a non-negligible performance drag.
 
 ------------------------------------------------
 A conceptual overview part 2: the nuts and bolts
@@ -364,7 +374,8 @@ and how to make your own asynchronous operators.
 The inner workings of coroutines
 ================================
 
-:mod:`!asyncio` leverages four components to pass around control.
+:mod:`!asyncio` leverages four components of Python to pass
+around control.
 
 :meth:`coroutine.send(arg) <generator.send>` is the method used to start or
 resume a coroutine.
@@ -448,9 +459,9 @@ That might sound odd to you. You might be thinking:
    That causes the error: ``SyntaxError: yield from not allowed in a coroutine.``
    This was intentionally designed for the sake of simplicity -- mandating only
    one way of using coroutines.
+   Despite that, ``yield from`` and ``await`` effectively do the same thing.
    Initially ``yield`` was barred as well, but was re-accepted to allow for
    async generators.
-   Despite that, ``yield from`` and ``await`` effectively do the same thing.
 
 =======
 Futures

Doc/howto/free-threading-extensions.rst

@@ -203,7 +203,7 @@ Memory Allocation APIs
 Python's memory management C API provides functions in three different
 :ref:`allocation domains <allocator-domains>`: "raw", "mem", and "object".
 For thread-safety, the free-threaded build requires that only Python objects
-are allocated using the object domain, and that all Python object are
+are allocated using the object domain, and that all Python objects are
 allocated using that domain.  This differs from the prior Python versions,
 where this was only a best practice and not a hard requirement.
 
@@ -344,12 +344,12 @@ This means you cannot rely on nested critical sections to lock multiple objects
 at once, as the inner critical section may suspend the outer ones. Instead, use
 :c:macro:`Py_BEGIN_CRITICAL_SECTION2` to lock two objects simultaneously.
 
-Note that the locks described above are only :c:type:`!PyMutex` based locks.
+Note that the locks described above are only :c:type:`PyMutex` based locks.
 The critical section implementation does not know about or affect other locking
 mechanisms that might be in use, like POSIX mutexes.  Also note that while
-blocking on any :c:type:`!PyMutex` causes the critical sections to be
+blocking on any :c:type:`PyMutex` causes the critical sections to be
 suspended, only the mutexes that are part of the critical sections are
-released.  If :c:type:`!PyMutex` is used without a critical section, it will
+released.  If :c:type:`PyMutex` is used without a critical section, it will
 not be released and therefore does not get the same deadlock avoidance.
 
 Important Considerations
@@ -397,7 +397,8 @@ The wheels, shared libraries, and binaries are indicated by a ``t`` suffix.
 * `pypa/manylinux <https://github.com/pypa/manylinux>`_ supports the
   free-threaded build, with the ``t`` suffix, such as ``python3.13t``.
 * `pypa/cibuildwheel <https://github.com/pypa/cibuildwheel>`_ supports the
-  free-threaded build if you set
+  free-threaded build on Python 3.13 and 3.14. On Python 3.14, free-threaded
+  wheels will be built by default. On Python 3.13, you will need to set
   `CIBW_ENABLE to cpython-freethreading <https://cibuildwheel.pypa.io/en/stable/options/#enable>`_.
 
 Limited C API and Stable ABI

Doc/howto/free-threading-python.rst

@@ -116,12 +116,14 @@ after the main thread is running.  The following objects are immortalized:
 * :ref:`classes <classes>` (type objects)
 
 Because immortal objects are never deallocated, applications that create many
-objects of these types may see increased memory usage.  This is expected to be
+objects of these types may see increased memory usage under Python 3.13.  This
-addressed in the 3.14 release.
+has been addressed in the 3.14 release, where the aforementioned objects use
+deferred reference counting to avoid reference count contention.
 
 Additionally, numeric and string literals in the code as well as strings
-returned by :func:`sys.intern` are also immortalized.  This behavior is
+returned by :func:`sys.intern` are also immortalized in the 3.13 release.  This
-expected to remain in the 3.14 free-threaded build.
+behavior is part of the 3.14 release as well and it is expected to remain in
+future free-threaded builds.
 
 
 Frame objects
@@ -150,11 +152,12 @@ compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of their time in C extensions or I/O will see
 less of an impact.  The largest impact is because the specializing adaptive
-interpreter (:pep:`659`) is disabled in the free-threaded build.  We expect
+interpreter (:pep:`659`) is disabled in the free-threaded build.
-to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
+
-expected to be reduced in upcoming Python release.   We are aiming for an
+The specializing adaptive interpreter has been re-enabled in a thread-safe way
-overhead of 10% or less on the pyperformance suite compared to the default
+in the 3.14 release.  The performance penalty on single-threaded code in
-GIL-enabled build.
+free-threaded mode is now roughly 5-10%, depending on the platform and C
+compiler used.
 
 
 Behavioral changes

Doc/howto/isolating-extensions.rst

@@ -353,7 +353,7 @@ garbage collection protocol.
 That is, heap types should:
 
 - Have the :c:macro:`Py_TPFLAGS_HAVE_GC` flag.
-- Define a traverse function using ``Py_tp_traverse``, which
+- Define a traverse function using :c:data:`Py_tp_traverse`, which
   visits the type (e.g. using ``Py_VISIT(Py_TYPE(self))``).
 
 Please refer to the documentation of

Doc/includes/optional-module.rst

@@ -0,0 +1,9 @@
+This is an :term:`optional module`.
+If it is missing from your copy of CPython,
+look for documentation from your distributor (that is,
+whoever provided Python to you).
+If you are the distributor, see :ref:`optional-module-requirements`.
+
+.. Similar notes appear in the docs of the modules:
+   - zipfile
+   - tarfile

Doc/library/argparse.rst

@@ -638,6 +638,11 @@ by setting ``color`` to ``False``::
    ...                     help='an integer for the accumulator')
    >>> parser.parse_args(['--help'])
 
+Note that when ``color=True``, colored output depends on both environment
+variables and terminal capabilities.  However, if ``color=False``, colored
+output is always disabled, even if environment variables like ``FORCE_COLOR``
+are set.
+
 .. versionadded:: 3.14
 
 
@@ -1317,8 +1322,12 @@ attribute is determined by the ``dest`` keyword argument of
 
 For optional argument actions, the value of ``dest`` is normally inferred from
 the option strings.  :class:`ArgumentParser` generates the value of ``dest`` by
-taking the first long option string and stripping away the initial ``--``
+taking the first double-dash long option string and stripping away the initial
-string.  If no long option strings were supplied, ``dest`` will be derived from
+``-`` characters.
+If no double-dash long option strings were supplied, ``dest`` will be derived
+from the first single-dash long option string by stripping the initial ``-``
+character.
+If no long option strings were supplied, ``dest`` will be derived from
 the first short option string by stripping the initial ``-`` character.  Any
 internal ``-`` characters will be converted to ``_`` characters to make sure
 the string is a valid attribute name.  The examples below illustrate this
@@ -1326,11 +1335,12 @@ behavior::
 
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('-f', '--foo-bar', '--foo')
+   >>> parser.add_argument('-q', '-quz')
    >>> parser.add_argument('-x', '-y')
-   >>> parser.parse_args('-f 1 -x 2'.split())
+   >>> parser.parse_args('-f 1 -q 2 -x 3'.split())
-   Namespace(foo_bar='1', x='2')
+   Namespace(foo_bar='1', quz='2', x='3')
-   >>> parser.parse_args('--foo 1 -y 2'.split())
+   >>> parser.parse_args('--foo 1 -quz 2 -y 3'.split())
-   Namespace(foo_bar='1', x='2')
+   Namespace(foo_bar='1', quz='2', x='2')
 
 ``dest`` allows a custom attribute name to be provided::
 
@@ -1339,6 +1349,9 @@ behavior::
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')
 
+.. versionchanged:: next
+   Single-dash long option now takes precedence over short options.
+
 
 .. _deprecated:
 
@@ -1432,8 +1445,18 @@ this API may be passed as the ``action`` parameter to
        >>> parser.parse_args(['--no-foo'])
        Namespace(foo=False)
 
+   Single-dash long options are also supported.
+   For example, negative option ``-nofoo`` is automatically added for
+   positive option ``-foo``.
+   But no additional options are added for short options such as ``-f``.
+
    .. versionadded:: 3.9
 
+   .. versionchanged:: next
+      Added support for single-dash options.
+
+      Added support for alternate prefix_chars_.
+
 
 The parse_args() method
 -----------------------
@@ -2065,7 +2088,9 @@ Parser defaults
      >>> parser.parse_args(['736'])
      Namespace(bar=42, baz='badger', foo=736)
 
-   Note that parser-level defaults always override argument-level defaults::
+   Note that defaults can be set at both the parser level using :meth:`set_defaults`
+   and at the argument level using :meth:`add_argument`. If both are called for the
+   same argument, the last default set for an argument is used::
 
      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='bar')

Doc/library/ast.rst

@@ -2205,10 +2205,10 @@ Async and await
 Apart from the node classes, the :mod:`ast` module defines these utility functions
 and classes for traversing abstract syntax trees:
 
-.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1)
+.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1, module=None)
 
    Parse the source into an AST node.  Equivalent to ``compile(source,
-   filename, mode, flags=FLAGS_VALUE, optimize=optimize)``,
+   filename, mode, flags=FLAGS_VALUE, optimize=optimize, module=module)``,
    where ``FLAGS_VALUE`` is ``ast.PyCF_ONLY_AST`` if ``optimize <= 0``
    and ``ast.PyCF_OPTIMIZED_AST`` otherwise.
 
@@ -2261,6 +2261,9 @@ and classes for traversing abstract syntax trees:
       The minimum supported version for ``feature_version`` is now ``(3, 7)``.
       The ``optimize`` argument was added.
 
+   .. versionadded:: 3.15
+      Added the *module* parameter.
+
 
 .. function:: unparse(ast_obj)
 

Doc/library/asyncio-eventloop.rst

@@ -1631,6 +1631,9 @@ async/await code consider using the high-level
    conforms to the :class:`asyncio.SubprocessTransport` base class and
    *protocol* is an object instantiated by the *protocol_factory*.
 
+   If the transport is closed or is garbage collected, the child process
+   is killed if it is still running.
+
 .. method:: loop.subprocess_shell(protocol_factory, cmd, *, \
                stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
                stderr=subprocess.PIPE, **kwargs)
@@ -1654,6 +1657,9 @@ async/await code consider using the high-level
    conforms to the :class:`SubprocessTransport` base class and
    *protocol* is an object instantiated by the *protocol_factory*.
 
+   If the transport is closed or is garbage collected, the child process
+   is killed if it is still running.
+
 .. note::
    It is the application's responsibility to ensure that all whitespace
    and special characters are quoted appropriately to avoid `shell injection

Doc/library/asyncio-subprocess.rst

@@ -76,6 +76,9 @@ Creating Subprocesses
    See the documentation of :meth:`loop.subprocess_exec` for other
    parameters.
 
+   If the process object is garbage collected while the process is still
+   running, the child process will be killed.
+
    .. versionchanged:: 3.10
       Removed the *loop* parameter.
 
@@ -95,6 +98,9 @@ Creating Subprocesses
    See the documentation of :meth:`loop.subprocess_shell` for other
    parameters.
 
+   If the process object is garbage collected while the process is still
+   running, the child process will be killed.
+
    .. important::
 
       It is the application's responsibility to ensure that all whitespace and

Doc/library/asyncio-task.rst

@@ -1221,8 +1221,8 @@ Task Object
 
    To cancel a running Task use the :meth:`cancel` method.  Calling it
    will cause the Task to throw a :exc:`CancelledError` exception into
-   the wrapped coroutine.  If a coroutine is awaiting on a Future
+   the wrapped coroutine.  If a coroutine is awaiting on a future-like
-   object during cancellation, the Future object will be cancelled.
+   object during cancellation, the awaited object will be cancelled.
 
    :meth:`cancelled` can be used to check if the Task was cancelled.
    The method returns ``True`` if the wrapped coroutine did not
@@ -1411,6 +1411,10 @@ Task Object
       the cancellation, it needs to call :meth:`Task.uncancel` in addition
       to catching the exception.
 
+      If the Task being cancelled is currently awaiting on a future-like
+      object, that awaited object will also be cancelled. This cancellation
+      propagates down the entire chain of awaited objects.
+
       .. versionchanged:: 3.9
          Added the *msg* parameter.
 

Doc/library/asyncio.rst

@@ -79,6 +79,10 @@ You can experiment with an ``asyncio`` concurrent context in the :term:`REPL`:
    >>> await asyncio.sleep(10, result='hello')
    'hello'
 
+This REPL provides limited compatibility with :envvar:`PYTHON_BASIC_REPL`.
+It is recommended that the default REPL is used
+for full functionality and the latest features.
+
 .. audit-event:: cpython.run_stdin "" ""
 
 .. versionchanged:: 3.12.5 (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20)

Doc/library/bdb.rst

@@ -236,7 +236,7 @@ The :mod:`bdb` module also defines two classes:
    Normally derived classes don't override the following methods, but they may
    if they want to redefine the definition of stopping and breakpoints.
 
-   .. method:: is_skipped_line(module_name)
+   .. method:: is_skipped_module(module_name)
 
       Return ``True`` if *module_name* matches any skip pattern.
 

Doc/library/bz2.rst

@@ -25,6 +25,8 @@ The :mod:`bz2` module contains:
 * The :func:`compress` and :func:`decompress` functions for one-shot
   (de)compression.
 
+.. include:: ../includes/optional-module.rst
+
 
 (De)compression of files
 ------------------------

Doc/library/cmdline.rst

@@ -16,17 +16,17 @@ The following modules have a command-line interface.
 * :ref:`dis <dis-cli>`
 * :ref:`doctest <doctest-cli>`
 * :mod:`!encodings.rot_13`
-* :mod:`ensurepip`
+* :ref:`ensurepip <ensurepip-cli>`
 * :mod:`filecmp`
 * :mod:`fileinput`
 * :mod:`ftplib`
 * :ref:`gzip <gzip-cli>`
 * :ref:`http.server <http-server-cli>`
-* :mod:`!idlelib`
+* :ref:`idlelib <idlelib-cli>`
 * :ref:`inspect <inspect-module-cli>`
 * :ref:`json <json-commandline>`
 * :ref:`mimetypes <mimetypes-cli>`
-* :mod:`pdb`
+* :ref:`pdb <pdb-cli>`
 * :ref:`pickle <pickle-cli>`
 * :ref:`pickletools <pickletools-cli>`
 * :ref:`platform <platform-cli>`
@@ -52,8 +52,8 @@ The following modules have a command-line interface.
 * :mod:`turtledemo`
 * :ref:`unittest <unittest-command-line-interface>`
 * :ref:`uuid <uuid-cli>`
-* :mod:`venv`
+* :ref:`venv <venv-cli>`
-* :mod:`webbrowser`
+* :ref:`webbrowser <webbrowser-cli>`
 * :ref:`zipapp <zipapp-command-line-interface>`
 * :ref:`zipfile <zipfile-commandline>`
 

Doc/library/codecs.rst

@@ -1088,7 +1088,7 @@ alias for the ``'utf_8'`` codec.
    refer to the source :source:`aliases.py <Lib/encodings/aliases.py>` file.
 
 On Windows, ``cpXXX`` codecs are available for all code pages.
-But only codecs listed in the following table are guarantead to exist on
+But only codecs listed in the following table are guaranteed to exist on
 other platforms.
 
 .. impl-detail::

Doc/library/collections.rst

@@ -1209,7 +1209,7 @@ If a new entry overwrites an existing entry, the
 original insertion position is changed and moved to the end::
 
     class LastUpdatedOrderedDict(OrderedDict):
-        'Store items in the order the keys were last added'
+        'Store items in the order that the keys were last updated.'
 
         def __setitem__(self, key, value):
             super().__setitem__(key, value)

Doc/library/compression.zstd.rst

@@ -33,6 +33,8 @@ The :mod:`!compression.zstd` module contains:
 * The :class:`CompressionParameter`, :class:`DecompressionParameter`, and
   :class:`Strategy` classes for setting advanced (de)compression parameters.
 
+.. include:: ../includes/optional-module.rst
+
 
 Exceptions
 ----------

Doc/library/concurrent.interpreters.rst

@@ -29,12 +29,12 @@ Actual concurrency is available separately through
 .. seealso::
 
    :class:`~concurrent.futures.InterpreterPoolExecutor`
-      combines threads with interpreters in a familiar interface.
+      Combines threads with interpreters in a familiar interface.
 
-    .. XXX Add references to the upcoming HOWTO docs in the seealso block.
+   .. XXX Add references to the upcoming HOWTO docs in the seealso block.
 
    :ref:`isolating-extensions-howto`
-       how to update an extension module to support multiple interpreters
+      How to update an extension module to support multiple interpreters.
 
    :pep:`554`
 

Doc/library/contextvars.rst

@@ -313,7 +313,7 @@ client::
         addr = writer.transport.get_extra_info('socket').getpeername()
         client_addr_var.set(addr)
 
-        # In any code that we call is now possible to get
+        # In any code that we call, it is now possible to get the
         # client's address by calling 'client_addr_var.get()'.
 
         while True:

Doc/library/csv.rst

@@ -295,8 +295,8 @@ The :mod:`csv` module defines the following classes:
       - the second through n-th rows contain strings where at least one value's
         length differs from that of the putative header of that column.
 
-      Twenty rows after the first row are sampled; if more than half of columns +
+      Twenty-one rows after the header are sampled; if more than half of the
-      rows meet the criteria, :const:`True` is returned.
+      columns + rows meet the criteria, :const:`True` is returned.
 
    .. note::
 

Doc/library/ctypes.rst

@@ -14,6 +14,8 @@
 data types, and allows calling functions in DLLs or shared libraries.  It can be
 used to wrap these libraries in pure Python.
 
+.. include:: ../includes/optional-module.rst
+
 
 .. _ctypes-ctypes-tutorial:
 

Doc/library/curses.rst

@@ -23,6 +23,8 @@ Linux and the BSD variants of Unix.
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
+.. include:: ../includes/optional-module.rst
+
 .. note::
 
    Whenever the documentation mentions a *character* it can be specified
@@ -1349,7 +1351,6 @@ The :mod:`curses` module defines the following data members:
 
 
 .. data:: version
-.. data:: __version__
 
    A bytes object representing the current version of the module.
 

Doc/library/decimal.rst

@@ -264,7 +264,7 @@ allows the settings to be changed.  This approach meets the needs of most
 applications.
 
 For more advanced work, it may be useful to create alternate contexts using the
-Context() constructor.  To make an alternate active, use the :func:`setcontext`
+:meth:`Context` constructor.  To make an alternate active, use the :func:`setcontext`
 function.
 
 In accordance with the standard, the :mod:`decimal` module provides two ready to
@@ -1575,7 +1575,7 @@ Constants
    Specification that this implementation complies with.
    See https://speleotrove.com/decimal/decarith.html for the specification.
 
-   .. versionadded:: next
+   .. versionadded:: 3.15
 
 
 The following constants are only relevant for the C module. They

Doc/library/dis.rst

@@ -1673,9 +1673,13 @@ iterations of the loop.
    * ``0x02`` a dictionary of keyword-only parameters' default values
    * ``0x04`` a tuple of strings containing parameters' annotations
    * ``0x08`` a tuple containing cells for free variables, making a closure
+   * ``0x10`` the :term:`annotate function` for the function object
 
    .. versionadded:: 3.13
 
+   .. versionchanged:: 3.14
+      Added ``0x10`` to indicate the annotate function for the function object.
+
 
 .. opcode:: BUILD_SLICE (argc)
 

Doc/library/email.headerregistry.rst

@@ -294,7 +294,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
        ``inline`` and ``attachment`` are the only valid values in common use.
 
 
-.. class:: ContentTransferEncoding
+.. class:: ContentTransferEncodingHeader
 
    Handles the :mailheader:`Content-Transfer-Encoding` header.
 

Doc/library/ensurepip.rst

@@ -30,6 +30,8 @@ when creating a virtual environment) or after explicitly uninstalling
    needed to bootstrap ``pip`` are included as internal parts of the
    package.
 
+.. include:: ../includes/optional-module.rst
+
 .. seealso::
 
    :ref:`installing-index`
@@ -40,7 +42,9 @@ when creating a virtual environment) or after explicitly uninstalling
 
 .. include:: ../includes/wasm-mobile-notavail.rst
 
-Command line interface
+.. _ensurepip-cli:
+
+Command-line interface
 ----------------------
 
 .. program:: ensurepip

Doc/library/functions.rst

@@ -292,7 +292,9 @@ are always available.  They are listed here in alphabetical order.
       :func:`property`.
 
 
-.. function:: compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)
+.. function:: compile(source, filename, mode, flags=0, \
+                      dont_inherit=False, optimize=-1, \
+                      *, module=None)
 
    Compile the *source* into a code or AST object.  Code objects can be executed
    by :func:`exec` or :func:`eval`.  *source* can either be a normal string, a
@@ -334,6 +336,10 @@ are always available.  They are listed here in alphabetical order.
    ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
    or ``2`` (docstrings are removed too).
 
+   The optional argument *module* specifies the module name.
+   It is needed to unambiguous :ref:`filter <warning-filter>` syntax warnings
+   by module name.
+
    This function raises :exc:`SyntaxError` if the compiled source is invalid,
    and :exc:`ValueError` if the source contains null bytes.
 
@@ -371,6 +377,9 @@ are always available.  They are listed here in alphabetical order.
       ``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` can now be passed in flags to enable
       support for top-level ``await``, ``async for``, and ``async with``.
 
+   .. versionadded:: 3.15
+      Added the *module* parameter.
+
 
 .. class:: complex(number=0, /)
            complex(string, /)
@@ -1859,7 +1868,7 @@ are always available.  They are listed here in alphabetical order.
    the same data with other ordering tools such as :func:`max` that rely
    on a different underlying method.  Implementing all six comparisons
    also helps avoid confusion for mixed type comparisons which can call
-   reflected the :meth:`~object.__gt__` method.
+   the reflected :meth:`~object.__gt__` method.
 
    For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
 

Doc/library/functools.rst

@@ -42,11 +42,11 @@ The :mod:`functools` module defines the following functions:
         def factorial(n):
             return n * factorial(n-1) if n else 1
 
-        >>> factorial(10)      # no previously cached result, makes 11 recursive calls
+        >>> factorial(10)   # no previously cached result, makes 11 recursive calls
         3628800
-        >>> factorial(5)       # just looks up cached value result
+        >>> factorial(5)    # no new calls, just returns the cached result
         120
-        >>> factorial(12)      # makes two new recursive calls, the other 10 are cached
+        >>> factorial(12)   # two new recursive calls, factorial(10) is cached
         479001600
 
    The cache is threadsafe so that the wrapped function can be used in
@@ -672,7 +672,7 @@ The :mod:`functools` module defines the following functions:
    dispatch>` :term:`generic function`.
 
    To define a generic method, decorate it with the ``@singledispatchmethod``
-   decorator. When defining a function using ``@singledispatchmethod``, note
+   decorator. When defining a method using ``@singledispatchmethod``, note
    that the dispatch happens on the type of the first non-*self* or non-*cls*
    argument::
 
@@ -716,6 +716,9 @@ The :mod:`functools` module defines the following functions:
 
    .. versionadded:: 3.8
 
+   .. versionchanged:: 3.15
+      Added support of non-:term:`descriptor` callables.
+
 
 .. function:: update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)
 

Doc/library/gc.rst

@@ -108,10 +108,19 @@ The :mod:`gc` module provides the following functions:
 
    * ``uncollectable`` is the total number of objects which were found
      to be uncollectable (and were therefore moved to the :data:`garbage`
-     list) inside this generation.
+     list) inside this generation;
+
+   * ``candidates`` is the total number of objects in this generation which were
+     considered for collection and traversed;
+
+   * ``duration`` is the total time in seconds spent in collections for this
+     generation.
 
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      Add ``duration`` and ``candidates``.
+
 
 .. function:: set_threshold(threshold0, [threshold1, [threshold2]])
 
@@ -313,6 +322,12 @@ values but should not rebind them):
       "uncollectable": When *phase* is "stop", the number of objects
       that could not be collected and were put in :data:`garbage`.
 
+      "candidates": When *phase* is "stop", the total number of objects in this
+      generation which were considered for collection and traversed.
+
+      "duration": When *phase* is "stop", the time in seconds spent in the
+      collection.
+
    Applications can add their own callbacks to this list.  The primary
    use cases are:
 
@@ -325,6 +340,9 @@ values but should not rebind them):
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: next
+      Add "duration" and "candidates".
+
 
 The following constants are provided for use with :func:`set_debug`:
 

Doc/library/gzip.rst

@@ -11,6 +11,8 @@
 This module provides a simple interface to compress and decompress files just
 like the GNU programs :program:`gzip` and :program:`gunzip` would.
 
+.. include:: ../includes/optional-module.rst
+
 The data compression is provided by the :mod:`zlib` module.
 
 The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the
@@ -281,7 +283,7 @@ Example of how to GZIP compress a binary string::
 
 .. _gzip-cli:
 
-Command Line Interface
+Command-line interface
 ----------------------
 
 The :mod:`gzip` module provides a simple command line interface to compress or
@@ -294,7 +296,7 @@ Once executed the :mod:`gzip` module keeps the input file(s).
    Add a new command line interface with a usage.
    By default, when you will execute the CLI, the default compression level is 6.
 
-Command line options
+Command-line options
 ^^^^^^^^^^^^^^^^^^^^
 
 .. option:: file

Doc/library/heapq.rst

@@ -58,6 +58,11 @@ functions, respectively.
 The following functions are provided for min-heaps:
 
 
+.. function:: heapify(x)
+
+   Transform list *x* into a min-heap, in-place, in linear time.
+
+
 .. function:: heappush(heap, item)
 
    Push the value *item* onto the *heap*, maintaining the min-heap invariant.
@@ -77,11 +82,6 @@ The following functions are provided for min-heaps:
    followed by a separate call to :func:`heappop`.
 
 
-.. function:: heapify(x)
-
-   Transform list *x* into a min-heap, in-place, in linear time.
-
-
 .. function:: heapreplace(heap, item)
 
    Pop and return the smallest item from the *heap*, and also push the new *item*.

Doc/library/http.client.rst

@@ -133,7 +133,7 @@ This module provides the following function:
 
    Parse the headers from a file pointer *fp* representing a HTTP
    request/response. The file has to be a :class:`~io.BufferedIOBase` reader
-   (i.e. not text) and must provide a valid :rfc:`2822` style header.
+   (i.e. not text) and must provide a valid :rfc:`5322` style header.
 
    This function returns an instance of :class:`http.client.HTTPMessage`
    that holds the header fields, but no payload