python-wheels.yml

name: Build wheels

# Each platform builds two wheels from the same crate:
#   1. an abi3 wheel (`--features abi3-py311`, built with a GIL-enabled 3.11)
#      that works on every GIL-enabled CPython 3.11+, and
#   2. a version-specific free-threaded `cp314-cp314t` wheel (`-i 3.14t`, no
#      abi3) — free-threaded CPython 3.14 has no stable ABI, so it needs its own
#      wheel.
#
# A third, abi3t wheel (free-threaded stable ABI, PEP 803) for Python 3.15+ is
# scaffolded but commented out below: it needs a 3.15 interpreter, and 3.15 is
# still in beta. Uncomment the `abi3t` steps (and the `3.15t` interpreter
# installs) once 3.15 is released.
#
# On pull requests, only the `emscripten` job runs (every other job is gated
# with `if: github.event_name != 'pull_request'`). This catches regressions in
# the emscripten/Pyodide build — the most fragile target — without rebuilding
# every native wheel on every PR.

on:
  push:
    tags:
      - "v*"
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  linux:
    if: github.event_name != 'pull_request'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      matrix:
        platform:
          - runner: ubuntu-latest
            target: x86_64
          - runner: ubuntu-latest
            target: aarch64
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Install Python versions
        run: uv python install 3.11 3.14t
        # When 3.15 is released, add `3.15t` above for the abi3t build.

      - name: Build abi3 wheel
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          args: --release --out dist --features abi3-py311 -i 3.11
          sccache: "true"
          manylinux: "2_28"

      - name: Build free-threaded (cp314t) wheel
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          args: --release --out dist -i 3.14t
          sccache: "true"
          manylinux: "2_28"

      # - name: Build abi3t wheel (Python 3.15+)
      #   uses: PyO3/maturin-action@v1
      #   with:
      #     target: ${{ matrix.platform.target }}
      #     args: --release --out dist --features abi3t-py315 -i 3.15t
      #     sccache: "true"
      #     manylinux: "2_28"

      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-linux-${{ matrix.platform.target }}
          path: dist

  musllinux:
    if: github.event_name != 'pull_request'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      matrix:
        platform:
          - runner: ubuntu-latest
            target: x86_64
          - runner: ubuntu-latest
            target: aarch64
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Install Python versions
        run: uv python install 3.11 3.14t
        # When 3.15 is released, add `3.15t` above for the abi3t build.

      - name: Build abi3 wheel
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          args: --release --out dist --features abi3-py311 -i 3.11
          sccache: "true"
          manylinux: musllinux_1_2

      - name: Build free-threaded (cp314t) wheel
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          args: --release --out dist -i 3.14t
          sccache: "true"
          manylinux: musllinux_1_2

      # - name: Build abi3t wheel (Python 3.15+)
      #   uses: PyO3/maturin-action@v1
      #   with:
      #     target: ${{ matrix.platform.target }}
      #     args: --release --out dist --features abi3t-py315 -i 3.15t
      #     sccache: "true"
      #     manylinux: musllinux_1_2

      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-musllinux-${{ matrix.platform.target }}
          path: dist

  windows:
    if: github.event_name != 'pull_request'
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v7

      # uv-provided Python has linking issues on Windows with maturin, so use
      # the GitHub-actions-provided interpreter. `generate-import-lib` lets
      # maturin build the version-specific wheels (e.g. 3.14t) without each of
      # those interpreters installed.
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"

      - name: Build abi3 wheel
        uses: PyO3/maturin-action@v1
        with:
          target: x64
          args: --release --out dist --features abi3-py311 --features generate-import-lib -i 3.11
          sccache: "true"

      - name: Build free-threaded (cp314t) wheel
        uses: PyO3/maturin-action@v1
        with:
          target: x64
          args: --release --out dist --features generate-import-lib -i 3.14t
          sccache: "true"

      # - name: Build abi3t wheel (Python 3.15+)
      #   uses: PyO3/maturin-action@v1
      #   with:
      #     target: x64
      #     args: --release --out dist --features abi3t-py315 --features generate-import-lib -i 3.15t
      #     sccache: "true"

      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-windows-x64
          path: dist

  macos:
    if: github.event_name != 'pull_request'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      matrix:
        platform:
          - runner: macos-15-intel
            target: x86_64
          - runner: macos-15
            target: aarch64
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true

      - name: Install Python versions
        run: uv python install 3.11 3.14t
        # When 3.15 is released, add `3.15t` above for the abi3t build.

      - name: Build abi3 wheel
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          args: --release --out dist --features abi3-py311 -i 3.11
          sccache: "true"

      - name: Build free-threaded (cp314t) wheel
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          args: --release --out dist -i 3.14t
          sccache: "true"

      # - name: Build abi3t wheel (Python 3.15+)
      #   uses: PyO3/maturin-action@v1
      #   with:
      #     target: ${{ matrix.platform.target }}
      #     args: --release --out dist --features abi3t-py315 -i 3.15t
      #     sccache: "true"

      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-macos-${{ matrix.platform.target }}
          path: dist

  # PEP 783 (pyemscripten) wheel for Pyodide, built for Python 3.14 only.
  #
  # The Emscripten version, rustflags, and platform tag are all defined by
  # pyodide-build for the target Python version. Two things differ from the
  # native jobs:
  #
  #   1. The wheel is built `--no-default-features` (sync-only). The default
  #      `async` feature pulls in object_store / tokio / icechunk, which don't
  #      build for emscripten.
  #   2. We override the Rust toolchain via `matrix.rust-toolchain-override`
  #      (falling back to the one Pyodide pins). zarrista's MSRV (1.94) is newer
  #      than the toolchain Pyodide pins for 3.14 (1.93), so we override to the
  #      MSRV. 3.14's ABI needs no nightly-only rustflags, so stable works. Drop
  #      the override once Pyodide's pinned toolchain reaches the MSRV.
  #
  # Unlike the native jobs, this also runs on every pull request to catch
  # emscripten build regressions (e.g. a dependency update that no longer
  # compiles or links for this target) before release time.
  emscripten:
    runs-on: ubuntu-latest
    # Debug build on pull requests (faster, only checks it compiles and links);
    # release build on tag pushes and manual dispatch.
    env:
      RELEASE_FLAG: ${{ github.event_name != 'pull_request' && '--release' || '' }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.14"]
        include:
          - python-version: "3.14"
            rust-toolchain-override: "1.94"
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}

      - name: Install pyodide-build
        run: uv sync --only-group pyodide

      - name: Get pyodide config
        id: pyodide-config
        run: |
          {
            echo "rust-toolchain=$(uv run --no-sync pyodide config get rust_toolchain)"
            echo "pyodide-abi-version=$(uv run --no-sync pyodide config get pyodide_abi_version)"
            echo "rustflags=$(uv run --no-sync pyodide config get rustflags)"
            echo "cflags=$(uv run --no-sync pyodide config get cflags)"
          } >> "$GITHUB_OUTPUT"

      # Install Emscripten via the Pyodide cross-build environment rather than a
      # stock emsdk: this pins the Emscripten version matching the target
      # Pyodide ABI, and applies Pyodide's patches to Emscripten, several of
      # which affect dynamic linking of Rust side modules.
      # https://github.com/pyodide/pyodide/tree/main/emsdk/patches
      - name: Install emsdk (Pyodide xbuildenv)
        env:
          PYODIDE_XBUILDENV_PATH: ${{ github.workspace }}/.pyodide-xbuildenv
        run: |
          uv run --no-sync pyodide xbuildenv install
          uv run --no-sync pyodide xbuildenv install-emscripten
          # shellcheck disable=SC1090
          source "$PYODIDE_XBUILDENV_PATH/$(uv run --no-sync pyodide xbuildenv version)/emsdk/emsdk_env.sh"
          {
            echo "EMSDK=$EMSDK"
            echo "EMSDK_NODE=$EMSDK_NODE"
          } >> "$GITHUB_ENV"
          {
            echo "$EMSDK"
            echo "$EMSDK/upstream/emscripten"
            dirname "$EMSDK_NODE"
          } >> "$GITHUB_PATH"

      - name: Build emscripten wheel
        uses: PyO3/maturin-action@v1
        env:
          CARGO_TARGET_WASM32_UNKNOWN_EMSCRIPTEN_RUSTFLAGS: ${{ steps.pyodide-config.outputs.rustflags }}
          CFLAGS_wasm32_unknown_emscripten: ${{ steps.pyodide-config.outputs.cflags }}
          MATURIN_PYEMSCRIPTEN_PLATFORM_VERSION: ${{ steps.pyodide-config.outputs.pyodide-abi-version }}
        with:
          target: wasm32-unknown-emscripten
          rust-toolchain: ${{ matrix.rust-toolchain-override || steps.pyodide-config.outputs.rust-toolchain }}
          args: --out dist -i ${{ matrix.python-version }} --no-default-features ${{ env.RELEASE_FLAG }}
          sccache: "true"

      - name: Verify pyemscripten platform tag
        # PyPI rejects the legacy `emscripten_x_y_z` tag; fail before upload if
        # maturin didn't emit the PEP 783 `pyemscripten_*` tag (this needs
        # `MATURIN_PYEMSCRIPTEN_PLATFORM_VERSION` and a recent maturin).
        run: |
          ls -lh dist/
          ls dist/*-pyemscripten_*_wasm32.whl >/dev/null

      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-emscripten-py${{ matrix.python-version }}
          path: dist

  sdist:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Build sdist
        uses: PyO3/maturin-action@v1
        with:
          command: sdist
          args: --out dist

      - name: Upload sdist
        uses: actions/upload-artifact@v7
        with:
          name: wheels-sdist
          path: dist

  release:
    name: Release
    runs-on: ubuntu-latest
    environment:
      name: pypi-release
      url: https://pypi.org/p/zarrista
    permissions:
      # IMPORTANT: this permission is mandatory for trusted publishing
      id-token: write
    if: startsWith(github.ref, 'refs/tags/')
    needs: [linux, musllinux, windows, macos, emscripten, sdist]
    steps:
      - uses: actions/download-artifact@v8
        with:
          pattern: wheels-*
          merge-multiple: true
          path: dist

      - name: Publish package distributions to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1