feat: support the Python stable ABI (abi3 and abi3t)

.github/workflows/ci.yml

@@ -107,8 +107,8 @@ jobs:
       python-version: ${{ matrix.python-version }}
       cmake-args: -DPYBIND11_TEST_PRECOMPILE=ON
 
-  # The legacy PyHeapTypeObject type-creation path on CPython 3.12+
-  # (PyType_FromMetaclass is the default there).
+  # PyType_FromMetaclass type creation is the default on CPython 3.12+ (and the only
+  # path under the stable ABI); this job covers the legacy opt-out.
   type-creation-legacy:
     if: github.event.pull_request.draft == false
     strategy:
@@ -135,6 +135,244 @@ jobs:
       python-version: ${{ matrix.python-version }}
       cmake-args: ${{ matrix.cmake-args }}
 
+  # Stable ABI (Py_LIMITED_API): every test module is built as *.abi3.
+  stable-abi:
+    if: github.event.pull_request.draft == false
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runs-on: ubuntu-latest
+            python-version: '3.12'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON
+          # precompiled: the -inl.h files must not read any non-limited struct field
+          - runs-on: ubuntu-latest
+            python-version: '3.14'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON -DPYBIND11_TEST_PRECOMPILE=ON
+          # A newer limited API target: gates must follow the limited API, not PY_VERSION_HEX
+          - runs-on: ubuntu-latest
+            python-version: '3.14'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON -DPYBIND11_STABLE_ABI_VERSION=3.14
+          - runs-on: macos-latest
+            python-version: '3.13'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON -DCMAKE_CXX_STANDARD=17
+          - runs-on: windows-2022
+            python-version: '3.12'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON
+          # free-threaded stable ABI (abi3t, PEP 803): PyObject is opaque
+          - runs-on: ubuntu-latest
+            python-version: '3.15t'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON
+          - runs-on: macos-latest
+            python-version: '3.15t'
+            cmake-args: -DPYBIND11_TEST_STABLE_ABI=ON -DPYBIND11_TEST_PRECOMPILE=ON
+
+    name: 🧱
+    uses: ./.github/workflows/reusable-standard.yml
+    with:
+      runs-on: ${{ matrix.runs-on }}
+      python-version: ${{ matrix.python-version }}
+      cmake-args: ${{ matrix.cmake-args }}
+
+  # The point of the stable ABI: build the suite once against the 3.12 headers
+  # and run the same .abi3 modules on newer interpreters.
+  stable-abi-forward:
+    if: github.event.pull_request.draft == false
+    name: 🧱 abi3 on newer Pythons
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      # Relative to the working directory of the forward steps, build/tests
+      PYBIND11_STABLE_ABI_SKIPPED_TESTS: >-
+        --ignore=../../tests/test_custom_type_setup.py
+        --ignore=../../tests/test_multiple_interpreters.py
+        --ignore=../../tests/test_class_release_gil_before_calling_cpp_dtor.py
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup Python 3.12 (build)
+        id: py312
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Setup Python 3.13 and 3.14 (run)
+        uses: actions/setup-python@v7
+        with:
+          python-version: |
+            3.13
+            3.14
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Prepare env
+        run: |
+          for py in "${{ steps.py312.outputs.python-path }}" python3.13 python3.14; do
+            uv pip install --python="$py" --system -r tests/requirements.txt
+          done
+
+      - name: Configure (Python 3.12, stable ABI)
+        run: >
+          cmake -S. -Bbuild -Werror=dev -GNinja
+          -DPYBIND11_WERROR=ON
+          -DDOWNLOAD_CATCH=ON
+          -DDOWNLOAD_EIGEN=ON
+          -DPYBIND11_TEST_STABLE_ABI=ON
+          -DPYTHON_EXECUTABLE=${{ steps.py312.outputs.python-path }}
+
+      - name: Build
+        run: cmake --build build
+
+      - name: Python tests (3.12)
+        run: cmake --build build --target pytest
+
+      - name: Python tests (3.13, same binaries)
+        working-directory: build/tests
+        run: python3.13 -m pytest -v ../../tests ${{ env.PYBIND11_STABLE_ABI_SKIPPED_TESTS }}
+
+      - name: Python tests (3.14, same binaries)
+        working-directory: build/tests
+        run: python3.14 -m pytest -v ../../tests ${{ env.PYBIND11_STABLE_ABI_SKIPPED_TESTS }}
+
+  # abi3t modules also load on GIL-enabled interpreters: build the suite with
+  # 3.15t and run the same .abi3t modules on 3.15.
+  stable-abi-forward-ft:
+    if: github.event.pull_request.draft == false
+    name: 🧱 abi3t on GIL-enabled Python
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      # Relative to the working directory of the forward steps, build/tests
+      PYBIND11_STABLE_ABI_SKIPPED_TESTS: >-
+        --ignore=../../tests/test_custom_type_setup.py
+        --ignore=../../tests/test_multiple_interpreters.py
+        --ignore=../../tests/test_class_release_gil_before_calling_cpp_dtor.py
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup Python 3.15t (build)
+        id: py315t
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.15t'
+          allow-prereleases: true
+
+      - name: Setup Python 3.15 (run)
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.15'
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Prepare env
+        run: |
+          for py in "${{ steps.py315t.outputs.python-path }}" python3.15; do
+            uv pip install --python="$py" --system -r tests/requirements.txt
+          done
+
+      - name: Configure (Python 3.15t, stable ABI)
+        run: >
+          cmake -S. -Bbuild -Werror=dev -GNinja
+          -DPYBIND11_WERROR=ON
+          -DDOWNLOAD_CATCH=ON
+          -DDOWNLOAD_EIGEN=ON
+          -DPYBIND11_TEST_STABLE_ABI=ON
+          -DPYTHON_EXECUTABLE=${{ steps.py315t.outputs.python-path }}
+
+      - name: Build
+        run: cmake --build build
+
+      - name: Python tests (3.15t)
+        run: cmake --build build --target pytest
+
+      - name: Python tests (3.15, same binaries)
+        working-directory: build/tests
+        run: python3.15 -m pytest -v ../../tests ${{ env.PYBIND11_STABLE_ABI_SKIPPED_TESTS }}
+
+  # PYBIND11_ABI3T builds abi3t from GIL-enabled Python; run the same modules on 3.15t.
+  stable-abi-abi3t-from-gil:
+    if: github.event.pull_request.draft == false
+    strategy:
+      fail-fast: false
+      matrix:
+        runs-on: [ubuntu-latest, windows-latest]
+    name: 🧱 abi3t from GIL-enabled Python • ${{ matrix.runs-on }}
+    runs-on: ${{ matrix.runs-on }}
+    timeout-minutes: 60
+    defaults:
+      run:
+        shell: bash
+    env:
+      # Relative to the working directory of the forward steps, build/tests
+      PYBIND11_STABLE_ABI_SKIPPED_TESTS: >-
+        --ignore=../../tests/test_custom_type_setup.py
+        --ignore=../../tests/test_multiple_interpreters.py
+        --ignore=../../tests/test_class_release_gil_before_calling_cpp_dtor.py
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Setup Python 3.15t (run)
+        id: py315t
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.15t'
+          allow-prereleases: true
+
+      - name: Setup Python 3.15 (build)
+        id: py315
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.15'
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Prepare env
+        run: |
+          for py in "${{ steps.py315t.outputs.python-path }}" "${{ steps.py315.outputs.python-path }}"; do
+            uv pip install --python="$py" --system -r tests/requirements.txt
+          done
+
+      - name: Configure (Python 3.15, abi3t)
+        run: >
+          cmake -S. -Bbuild -Werror=dev
+          -DPYBIND11_WERROR=ON
+          -DDOWNLOAD_CATCH=ON
+          -DDOWNLOAD_EIGEN=ON
+          -DPYBIND11_TEST_STABLE_ABI=ON
+          -DPYBIND11_ABI3T=ON
+          -DCMAKE_BUILD_TYPE=Release
+          -DPYTHON_EXECUTABLE="${{ steps.py315.outputs.python-path }}"
+
+      - name: Build
+        run: cmake --build build --config Release -j 4
+
+      - name: CMake stable ABI consumer build
+        run: cmake --build build --config Release --target test_build_subdirectory_stable_abi
+
+      - name: Python tests (3.15)
+        run: cmake --build build --config Release --target pytest
+
+      - name: Python tests (3.15t, same binaries)
+        working-directory: build/tests
+        run: >
+          "${{ steps.py315t.outputs.python-path }}" -m pytest -v ../../tests
+          ${{ env.PYBIND11_STABLE_ABI_SKIPPED_TESTS }}
+
   standard-large:
     if: github.event.pull_request.draft == false
     strategy: