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: ["*"]
  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

jobs:
  plan:
    runs-on: ubuntu-slim
    outputs:
      test: ${{ steps.decisions.outputs.test }}
      gate: ${{ steps.decisions.outputs.gate }}
    steps:
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4
        if: github.event_name == 'pull_request'
        id: filter
        with:
          filters: |
            src:
              - 'bindings/py/**'
              - 'core/**'
              - '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"

  lint:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ubuntu-24.04
    defaults:
      run:
        working-directory: bindings/py

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7

      - name: Setup environment
        run: |
          uv sync --group linters --active --no-install-project --locked
          echo "$(pwd)/.venv/bin" >> "$GITHUB_PATH"

      - name: ruff format ...
        run: ruff format --check python tests

      - name: ruff check ...
        run: ruff check python

      - name: mypy ...
        run: mypy --strict python

  windows:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      matrix:
        platform:
          - runner: windows-latest
            target: x64
            rust_target: x86_64-pc-windows-msvc
          - runner: windows-11-arm
            target: arm64 # not aarch64 because expected by setup-python
            rust_target: aarch64-pc-windows-msvc
        # It is sufficient to build wheels for the lowest supported Python
        # version, but we need to build wheels for each supported free-threaded
        # version.
        python:
          - version: "3.14t"
            label: 3.14-free-threaded
            args_suffix: --interpreter python3.14t
        include:
          # Since Python 3.10 isn't available on the arm runners, we need to
          # provide a 3.10 job for x64 and a 3.11 job for arm64.
          - platform:
              runner: windows-latest
              target: x64
              rust_target: x86_64-pc-windows-msvc
            python:
              version: "3.10"
              label: "3.10"
              args_suffix: ""
          - platform:
              runner: windows-11-arm
              target: arm64 # not aarch64 because expected by setup-python
              rust_target: aarch64-pc-windows-msvc
            python:
              version: "3.11"
              label: "3.11"
              args_suffix: ""

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ matrix.python.version }}
          architecture: ${{ matrix.platform.target }}
      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7

      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2

      - name: cargo test ... (Python bindings)
        run: |
          cd bindings/py
          cargo test --locked --package sysand-py --no-default-features --target ${{ matrix.platform.rust_target }}

      - name: Build wheels
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.rust_target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi ${{ matrix.python.args_suffix }}
          sccache: true

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

      - name: pytest
        run: |
          export UV_PYTHON=${{ matrix.python.version }}
          export ACTIVATION_SCRIPT=.venv/Scripts/activate
          .github/scripts/run-pytest.sh ${{ matrix.python.version }}

  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
          - runner: ubuntu-24.04-arm
            target: aarch64

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7

      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2

      - name: cargo test ... (Python bindings)
        run: cargo test --locked --package sysand-py --no-default-features

      - name: Build wheels (manylinux)
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi
          manylinux: manylinux2014
          sccache: true
      - name: Build wheels (musllinux)
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi
          manylinux: musllinux_1_2
          sccache: true

      - name: Build free-threaded wheels (manylinux)
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.14t
          manylinux: manylinux2014 # TODO: don't use default cross-compile containers for aarch64
          sccache: true
      - name: Build free-threaded wheels (musllinux)
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.14t
          manylinux: musllinux_1_2
          sccache: true

      - name: Upload wheels
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
        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 (musllinux)
        run: |
          docker run \
            --rm -v ${{ github.workspace }}:/io -w /io \
            ghcr.io/astral-sh/uv:python3.14-alpine \
            sh .github/scripts/run-pytest.sh

  macos:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      matrix:
        platform:
          - runner: macos-15-intel
            target: x86_64
          - runner: macos-latest
            target: aarch64

    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7

      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2

      - name: cargo test ... (Python bindings)
        run: cargo test --locked --package sysand-py --no-default-features

      - name: Build wheels
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi
          sccache: true

      - name: Build free-threaded wheels
        uses: PyO3/maturin-action@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          target: ${{ matrix.platform.target }}
          working-directory: bindings/py
          args: --release --out ../../dist --compatibility pypi --interpreter python3.14t
          sccache: true

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

      - name: pytest
        run: .github/scripts/run-pytest.sh

  sdist:
    needs: [plan]
    if: needs.plan.outputs.test == 'true'
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - 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@04ac600d27cdf7a9a280dadf7147097c42b757ad # v1
        with:
          command: sdist
          working-directory: bindings/py
          args: --out ../../dist

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

  ci-gate:
    name: Python CI Gate
    needs: [plan, lint, 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: [lint, 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@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8

      - name: Collect packages
        run: |
          mkdir dist
          cp wheels-*/* dist/

      - name: Generate artifact attestation
        uses: actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 # v4
        with:
          subject-path: "dist/*"

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
        with:
          attestations: true