python.yml

# This file evolved from being autogenerated with maturin and then **heavily
# manually** edited. You can regenerate it as below for comparative reference.
# Last time this was done was with maturin v1.12.6 at 2026-03-17.
#
#    maturin generate-ci github --pytest --manifest-path bindings/py/Cargo.toml
#
name: Python (Bindings)

on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

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

defaults:
  run:
    shell: bash

env:
  RUST_BACKTRACE: 1
  CARGO_TERM_COLOR: always
  CARGO_NET_RETRY: 10
  RUSTUP_MAX_RETRIES: 10
  UV_HTTP_RETRIES: 5
  UV_HTTP_TIMEOUT: 60
  # sccache's GitHub cache entries follow the same main-only saving as
  # rust-cache. maturin-action forwards SCCACHE_* into its containers.
  SCCACHE_GHA_RW_MODE: ${{ github.ref == 'refs/heads/main' && 'READ_WRITE' || 'READ_ONLY' }}

jobs:
  plan:
    runs-on: ubuntu-slim
    outputs:
      test: ${{ steps.decisions.outputs.test }}
      gate: ${{ steps.decisions.outputs.gate }}
    steps:
      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
        if: github.event_name == 'pull_request'
        id: filter
        with:
          filters: |
            src:
              - 'bindings/py/**'
              - 'core/**'
              - 'macros/**'
              - 'sysand/**'
              - 'Cargo.*'
              - '.github/workflows/python.yml'
              - '.github/scripts/*'
      - id: decisions
        run: |
          test=${{ steps.filter.outputs.src == 'true' || github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
          gate=${{ github.event_name == 'pull_request' }}
          echo "test=$test" >> "$GITHUB_OUTPUT"
          echo "gate=$gate" >> "$GITHUB_OUTPUT"

  windows:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      matrix:
        # Two wheels cover all supported Python versions:
        # - abi3 for the lowest supported version (GIL-enabled 3.10+)
        # - abi3t for 3.15 (GIL-enabled and free-threaded 3.15+)
        platform:
          - runner: windows-latest
            target: x64
            rust_target: x86_64-pc-windows-msvc
            python: "3.10"
            abi3t: true
            cargo_test: true
          # Python 3.10 isn't available on the arm runners.
          - runner: windows-11-arm
            target: arm64 # not aarch64 because expected by setup-python
            rust_target: aarch64-pc-windows-msvc
            python: "3.11"
            abi3t: true

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        id: python-abi3
        with:
          python-version: ${{ matrix.platform.python }}
          architecture: ${{ matrix.platform.target }}
      # The last installed Python is the default one on PATH.
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        if: matrix.platform.abi3t
        with:
          python-version: "3.15t"
          architecture: ${{ matrix.platform.target }}
      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          enable-cache: ${{ !startsWith(github.ref, 'refs/tags/') }}
          save-cache: ${{ github.ref == 'refs/heads/main' }}

      # No caches on tag builds, see cache-poisoning in .github/zizmor.yml
      - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
        with:
          # A cache saved by a PR is visible only to that PR, and it evicts
          # main's caches once the repository's 10GB limit is reached.
          save-if: ${{ github.ref == 'refs/heads/main' }}
          key: ${{ matrix.platform.runner }}

      # `abi3` is enabled to test what the wheels are built with: abi3t on
      # 3.15t, the default Python. The Rust tests run in one job per OS.
      - name: cargo test ... (Python bindings)
        if: matrix.platform.cargo_test
        run: |
          cd bindings/py
          cargo test --locked --package sysand-py --no-default-features --features abi3,tls-aws-lc-rs --target ${{ matrix.platform.rust_target }}

      # An explicit interpreter keeps maturin from also picking up 3.15t,
      # which would select abi3t and build a version-specific wheel instead.
      - name: Build wheels
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.rust_target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter ${{ steps.python-abi3.outputs.python-path }}
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}

      - name: Build abi3t wheels
        if: matrix.platform.abi3t
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.rust_target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.15t
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}

      - name: Upload wheels
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheels-windows-${{ matrix.platform.target }}
          path: dist
          if-no-files-found: error

      - name: pytest
        run: |
          export UV_PYTHON=${{ matrix.platform.python }}
          export ACTIVATION_SCRIPT=.venv/Scripts/activate
          .github/scripts/run-pytest.sh
      - name: pytest (abi3t)
        if: matrix.platform.abi3t
        run: |
          export UV_PYTHON=3.15t
          export ACTIVATION_SCRIPT=.venv/Scripts/activate
          .github/scripts/run-pytest.sh

  linux:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      fail-fast: false
      matrix:
        platform:
          - runner: ubuntu-24.04
            target: x86_64
            cargo_test: true
          - runner: ubuntu-24.04-arm
            target: aarch64

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.10"
      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          enable-cache: ${{ !startsWith(github.ref, 'refs/tags/') }}
          save-cache: ${{ github.ref == 'refs/heads/main' }}

      # No caches on tag builds, see cache-poisoning in .github/zizmor.yml
      - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
        with:
          # A cache saved by a PR is visible only to that PR, and it evicts
          # main's caches once the repository's 10GB limit is reached.
          save-if: ${{ github.ref == 'refs/heads/main' }}
          key: ${{ matrix.platform.runner }}

      # `abi3` is enabled to test what the wheels are built with: abi3 on 3.10.
      - name: cargo test ... (Python bindings)
        if: matrix.platform.cargo_test
        run: cargo test --locked --package sysand-py --no-default-features --features abi3,tls-aws-lc-rs

      - name: Build wheels (manylinux)
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          # The image also has CPython 3.15, for which maturin would pick
          # abi3t and build version-specific wheels for 3.10-3.14.
          args: --release --out ../../dist --compatibility pypi --interpreter python3.10
          manylinux: manylinux2014
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
      - name: Build wheels (musllinux)
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi
          manylinux: musllinux_1_2
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}

      - name: Build abi3t wheels (manylinux)
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.15
          manylinux: manylinux2014 # TODO: don't use default cross-compile containers for aarch64
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
      - name: Build abi3t wheels (musllinux)
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.15
          manylinux: musllinux_1_2
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}

      - name: Upload wheels
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheels-linux-${{ matrix.platform.target }}
          path: dist
          if-no-files-found: error

      - name: pytest (manylinux)
        run: .github/scripts/run-pytest.sh
      - name: pytest (manylinux, abi3t)
        run: UV_PYTHON=3.15t .github/scripts/run-pytest.sh

      - name: pytest (musllinux)
        run: |
          docker run \
            --rm -v ${{ github.workspace }}:/io -w /io \
            ghcr.io/astral-sh/uv:python3.10-alpine \
            sh .github/scripts/run-pytest.sh

  macos:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: macos-latest
    strategy:
      matrix:
        platform:
          # Cross-compiled on the arm64 runner, so the x86_64 wheels are not
          # tested.
          - target: x86_64
          - target: aarch64
            test: true

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.10"
      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          enable-cache: ${{ !startsWith(github.ref, 'refs/tags/') }}
          save-cache: ${{ github.ref == 'refs/heads/main' }}

      # No caches on tag builds, see cache-poisoning in .github/zizmor.yml
      - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
        with:
          # A cache saved by a PR is visible only to that PR, and it evicts
          # main's caches once the repository's 10GB limit is reached.
          save-if: ${{ github.ref == 'refs/heads/main' }}
          key: ${{ matrix.platform.target }}

      # `abi3` is enabled to test what the wheels are built with: abi3 on 3.10.
      - name: cargo test ... (Python bindings)
        if: matrix.platform.test
        run: cargo test --locked --package sysand-py --no-default-features --features abi3,tls-aws-lc-rs

      - name: Build wheels
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}

      - name: Build abi3t wheels
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.15
          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}

      - name: Upload wheels
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheels-macos-${{ matrix.platform.target }}
          path: dist
          if-no-files-found: error

      - name: pytest
        if: matrix.platform.test
        run: .github/scripts/run-pytest.sh
      - name: pytest (abi3t)
        if: matrix.platform.test
        run: UV_PYTHON=3.15t .github/scripts/run-pytest.sh

  sdist:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false

      - name: Maturin workaround
        # Maturin-action blindly downloads the specified toolchain without
        # checking that it won't be needed at all for sdist
        # TODO: fix maturin so that this isn't needed
        run: rm rust-toolchain.toml

      - name: Build sdist
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          command: sdist
          working-directory: bindings/py
          args: --out ../../dist

      - name: Upload sdist
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheels-sdist
          path: dist
          if-no-files-found: error

  ci-gate:
    name: Python CI Gate
    needs: [plan, windows, linux, macos, sdist]
    if: needs.plan.outputs.gate == 'true' && !cancelled()
    runs-on: ubuntu-slim
    steps:
      - run: |
          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
            exit 1
          fi

  release:
    name: Release to PyPI
    environment: pypi-publish
    needs: [linux, macos, windows, sdist]
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-24.04
    permissions:
      id-token: write # for actions/attest and pypa/gh-action-pypi-publish
      attestations: write # for actions/attest and pypa/gh-action-pypi-publish
      artifact-metadata: write # for actions/attest

    steps:
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: wheels-*
          path: downloads

      - name: Check and collect packages
        run: |
          # Any job in this run can upload artifacts, so accept exactly the
          # expected set rather than whatever matches the pattern.
          expected="$(printf '%s\n' \
              wheels-windows-x64 \
              wheels-windows-arm64 \
              wheels-linux-x86_64 \
              wheels-linux-aarch64 \
              wheels-macos-x86_64 \
              wheels-macos-aarch64 \
              wheels-sdist \
              | sort)"
          actual="$(find downloads -mindepth 1 -maxdepth 1 -printf '%f\n' | sort)"
          if [[ "$actual" != "$expected" ]]; then
            echo "unexpected set of artifacts (keep in sync with the windows/linux/macos/sdist matrix):" >&2
            diff <(echo "$expected") <(echo "$actual") >&2
            exit 1
          fi

          mkdir dist
          cp downloads/*/* dist/

      - name: Generate artifact attestation
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: "dist/*"

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
        with:
          attestations: true