Build a single abi3 wheel per platform instead of one per version

Set wheel.py-api = "cp311" so scikit-build-core tags the wheel cp311-abi3,
and turn the SKBUILD_SABI_* variables it exports into USE_SABI on each
extension target.  USE_SABI defines Py_LIMITED_API, which is what flips
Cython into CYTHON_LIMITED_API mode, and together with WITH_SOABI names the
modules <name>.abi3.so.  A plain cmake invocation sets neither variable, so
the version-specific behaviour is unchanged outside of a wheel build.

No .pyx changes were needed.  The cdef classes (SChunk, vlmeta) build as
PyType_FromSpec heap types, the legacy `np.ndarray[dtype, ndim=N]` buffer
syntax in indexing_ext still compiles, and utf8_ext's NpyString usage is
limited-API clean, all with Cython 3.2.9 and NumPy 2.5.

Measured on macOS arm64, 4 interleaved runs, min-of-7 per measurement: worst
case 1.013x (compress2 of 8 KB buffers, i.e. call-overhead bound), everything
else within noise.  SChunk attribute access -- the most direct probe of the
heap-type path -- came out at 0.987x.  Full suite passes on the build
interpreter (3.14) and, using that same wheel, on 3.11/3.12/3.13.

Free-threaded builds keep their own version-specific wheels: scikit-build-core
ignores py-api when Py_GIL_DISABLED is set, so cp314t/cp315t need no extra
configuration.  Collapsing those into one wheel needs abi3t (PEP 803), which
starts at 3.15 and requires a PEP 793 module export hook that Cython cannot
emit yet.  So this is 7 wheels per platform down to 3, not 2.

Since the abi3 wheel is built only on 3.11 and cibuildwheel tests a wheel just
on the interpreter that produced it, add test_abi3_matrix: it installs the
single wheel on 3.11-3.15 across all three OSes, asserts the .abi3. module is
the one loaded, and runs a slice of the suite.  That is also the job that would
catch a future CPython breaking the stable ABI -- the risk abi3 takes on in
exchange for not rebuilding.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: FrancescAlted

.github/workflows/cibuildwheels.yml

@@ -43,38 +43,50 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # The `*` after the version list is what lets the free-threaded builds
-        # through: their identifiers are `cp314t-...`, so a bare `cp314-...`
-        # pattern silently drops them.  cibuildwheel enables free-threading by
-        # default from 3.14 on, so cp314t/cp315t are selected while cp313t is
-        # not -- deliberate, as 3.13's free-threaded build was still marked
-        # experimental (PEP 703 phase I) and carried a large single-thread
-        # penalty.  Opting into it would need CIBW_ENABLE: cpython-freethreading.
+        # Three builds per platform, not one per Python version:
+        #
+        #   cp311   -> a single `cp311-abi3` wheel serving CPython 3.11+, via
+        #              `wheel.py-api` in pyproject.toml.  Building it on any
+        #              other version would emit the *same* filename, so only
+        #              the floor version is built.
+        #   cp314t  -> free-threaded 3.14.  Cannot use abi3: the free-threaded
+        #   cp315t     ABI is distinct, and its stable variant (abi3t, PEP 803)
+        #              starts at 3.15 and needs a PEP 793 module export hook
+        #              that Cython does not emit yet.  These stay
+        #              version-specific until that lands upstream.
+        #
+        # cp313t is deliberately absent: 3.13's free-threaded build was still
+        # experimental (PEP 703 phase I) with a large single-thread penalty.
+        # cibuildwheel keeps it behind CIBW_ENABLE: cpython-freethreading.
+        #
+        # NOTE: cibuildwheel only tests a wheel on the interpreter that built
+        # it, so the abi3 wheel is exercised on 3.11 alone here.  The
+        # test_abi3_matrix job below installs it on every supported version.
         include:
           # Linux x86_64 builds
           - os: ubuntu-latest
             arch: x86_64
-            cibw_pattern: "cp3{11,12,13,14,15}*-manylinux*"
+            cibw_pattern: "cp311-manylinux* cp314t-manylinux* cp315t-manylinux*"
             artifact_name: "linux-x86_64"
 
           # Linux ARM64 builds (native runners)
           - os: ubuntu-24.04-arm
             arch: aarch64
-            cibw_pattern: "cp3{11,12,13,14,15}*-manylinux*"
+            cibw_pattern: "cp311-manylinux* cp314t-manylinux* cp315t-manylinux*"
             artifact_name: "linux-aarch64"
             # Don't use native runners for now (looks like wait times are too long)
             #runs-on: ["ubuntu-latest", "arm64"]
 
           # Windows builds
           - os: windows-latest
             arch: x86_64
-            cibw_pattern: "cp3{11,12,13,14,15}*-win_amd64"
+            cibw_pattern: "cp311-win_amd64 cp314t-win_amd64 cp315t-win_amd64"
             artifact_name: "windows-x86_64"
 
           # macOS builds (universal2)
           - os: macos-latest
             arch: x86_64
-            cibw_pattern: "cp3{11,12,13,14,15}*-macosx*"
+            cibw_pattern: "cp311-macosx* cp314t-macosx* cp315t-macosx*"
             artifact_name: "macos-universal2"
     steps:
       - name: Checkout repo
@@ -195,8 +207,75 @@ jobs:
           path: ./wheelhouse/*.whl
 
 
+  # The abi3 wheel is built once, on 3.11, and cibuildwheel only tests a wheel
+  # on the interpreter that produced it.  Every other supported version would
+  # therefore ship untested, so install the one wheel on each of them and run a
+  # slice of the suite.  This is also the job that would catch a CPython release
+  # breaking the stable ABI -- the failure mode abi3 trades away rebuilds for.
+  test_abi3_matrix:
+    name: Test abi3 wheel on ${{ matrix.python-version }} (${{ matrix.os }})
+    needs: [ build_wheels ]
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Both are real matrix dimensions so they cross-product (15 short jobs).
+        # The `include` entries key on `os`, which is an existing dimension, so
+        # they attach artifact_name to the matching combinations rather than
+        # being appended as extra jobs.
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        include:
+          - os: ubuntu-latest
+            artifact_name: "linux-x86_64"
+          - os: windows-latest
+            artifact_name: "windows-x86_64"
+          - os: macos-latest
+            artifact_name: "macos-universal2"
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          # 3.15 is still a pre-release until October
+          allow-prereleases: true
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: ./wheelhouse
+
+      # Pin the exact version so pip resolves blosc2 from ./wheelhouse (picking
+      # the arch-compatible file) while still pulling dependencies from PyPI.
+      - name: Install the abi3 wheel
+        shell: bash
+        run: |
+          WHL=$(ls wheelhouse/blosc2-*abi3*.whl | head -1)
+          echo "Installing $WHL on $(python -V)"
+          python -m pip install --upgrade pip
+          python -m pip install --find-links ./wheelhouse "blosc2==$(basename "$WHL" | cut -d- -f2)"
+
+      - name: Confirm the abi3 module was the one loaded
+        shell: bash
+        run: |
+          python -c "
+          import blosc2, blosc2.blosc2_ext as ext
+          assert '.abi3.' in ext.__file__, f'not an abi3 module: {ext.__file__}'
+          print('OK:', ext.__file__)
+          blosc2.print_versions()
+          "
+
+      - name: Run a slice of the test suite
+        shell: bash
+        run: |
+          python -m pip install pytest
+          python -m pytest tests/test_open.py tests/test_vlmeta.py \
+                           tests/ndarray/test_evaluate.py -q -p no:cacheprovider
+
+
   upload_pypi:
-    needs: [ build_wheels, build_wheels_wasm ]
+    needs: [ build_wheels, build_wheels_wasm, test_abi3_matrix ]
     runs-on: ubuntu-latest
     # Only upload wheels when tagging (typically a release)
     if: startsWith(github.event.ref, 'refs/tags')

CMakeLists.txt

@@ -27,7 +27,27 @@ endif()
 # does not include a python symbolic link to python3.
 # find_package(Python 3.12 COMPONENTS Interpreter NumPy Development.Module REQUIRED)
 # IMO, this would need to be solved in Fedora, so we can just use the following line:
-find_package(Python COMPONENTS Interpreter NumPy Development.Module REQUIRED)
+find_package(Python COMPONENTS Interpreter NumPy Development.Module
+             ${SKBUILD_SABI_COMPONENT} REQUIRED)
+
+# abi3 (Stable ABI) support.  scikit-build-core sets SKBUILD_SABI_COMPONENT to
+# "Development.SABIModule" and SKBUILD_SABI_VERSION to e.g. "3.11" when
+# `wheel.py-api` requests a limited-API build; both are empty otherwise, so a
+# plain CMake invocation keeps the version-specific behaviour.  Passing
+# USE_SABI to Python_add_library defines Py_LIMITED_API for the target (which
+# is what flips Cython into CYTHON_LIMITED_API mode) and, together with
+# WITH_SOABI, names the module `<name>.abi3.so` instead of
+# `<name>.cpython-3XY-<plat>.so`.
+#
+# Note scikit-build-core silently ignores py-api on free-threaded
+# interpreters, so cp3XXt builds fall back to version-specific wheels on their
+# own -- abi3t (PEP 803) is a separate ABI that Cython cannot emit yet.
+if(SKBUILD_SABI_VERSION)
+  set(B2_SABI USE_SABI ${SKBUILD_SABI_VERSION})
+  message(STATUS "Building limited-API (abi3) modules for Python ${SKBUILD_SABI_VERSION}+")
+else()
+  set(B2_SABI "")
+endif()
 
 # Add custom command to generate the version file
 add_custom_command(
@@ -68,15 +88,15 @@ add_custom_command(
   VERBATIM)
 
 # ...and add it to the target
-Python_add_library(blosc2_ext MODULE blosc2_ext.c WITH_SOABI)
+Python_add_library(blosc2_ext MODULE ${B2_SABI} WITH_SOABI blosc2_ext.c)
 target_sources(blosc2_ext PRIVATE src/blosc2/matmul_kernels.c)
 target_include_directories(blosc2_ext PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/blosc2)
 if(UNIX)
   target_link_libraries(blosc2_ext PRIVATE ${CMAKE_DL_LIBS})
 endif()
-Python_add_library(indexing_ext MODULE indexing_ext.c WITH_SOABI)
-Python_add_library(groupby_ext MODULE groupby_ext.c WITH_SOABI)
-Python_add_library(utf8_ext MODULE utf8_ext.c WITH_SOABI)
+Python_add_library(indexing_ext MODULE ${B2_SABI} WITH_SOABI indexing_ext.c)
+Python_add_library(groupby_ext MODULE ${B2_SABI} WITH_SOABI groupby_ext.c)
+Python_add_library(utf8_ext MODULE ${B2_SABI} WITH_SOABI utf8_ext.c)
 # NpyString_pack() and friends are part of NumPy's 2.0 C API; opt in
 # explicitly since numpy/*.h otherwise targets an older API version by
 # default for source compatibility.

pyproject.toml

@@ -119,6 +119,17 @@ test-command = "python -c \"import blosc2; blosc2.print_versions()\""
 manylinux-x86_64-image = "manylinux_2_28"
 manylinux-aarch64-image = "manylinux_2_28"
 
+[tool.scikit-build]
+# Build a single Stable ABI (abi3) wheel covering CPython 3.11+ instead of one
+# wheel per minor version.  CMakeLists.txt turns the SKBUILD_SABI_* variables
+# this produces into USE_SABI on each extension target.
+#
+# On free-threaded interpreters scikit-build-core ignores this and falls back to
+# a version-specific wheel, because abi3t (PEP 803) is a distinct ABI that
+# starts at 3.15 and that Cython cannot emit yet.  So cp314t/cp315t keep
+# building as normal cp3XXt wheels with no extra configuration.
+wheel.py-api = "cp311"
+
 [tool.scikit-build.sdist]
 exclude = ["bench*", ".github*"]