python.yaml

name: Python SDK

on:
  push:
    branches: [main]
    tags:
      - "python/v[0-9]+.[0-9]+.[0-9]+"
      - "python/v[0-9]+.[0-9]+.[0-9]+-*" # pre-releases: -alpha.N / -beta.N / -rc.N
    paths:
      - "sdk/python/**"
      - ".github/workflows/python.yaml"
  pull_request:
    paths:
      - "sdk/python/**"
      - ".github/workflows/python.yaml"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'main')}}

permissions:
  contents: read

jobs:

  lint:
    name: Lint Python SDK
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
      - name: Lint
        run: make lint-py

  unit:
    name: Unit tests (py${{ matrix.python }})
    runs-on: ubuntu-latest
    needs: lint
    strategy:
      fail-fast: false
      matrix:
        python: ["3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Install the latest version of uv and set the python version
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
        with:
          python-version: ${{ matrix.python }}

      # No server involved: the pure builder/client unit tests in sdk/python.
      - name: Unit tests with coverage
        run: make coverage-py

      # Uploaded under the `python` flag so the SDK's coverage is reported
      # separately from the Go server's (see codecov.yaml).
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: coverage-py.xml
          flags: python

  integration:
    name: Integration tests (${{ matrix.runner }}, py${{ matrix.python }})
    needs: unit
    # The SDK must work against the server image whichever architecture a user
    # runs it on, so every published architecture is crossed with every Python
    # the SDK supports (same version list as the unit-test job above). The
    # runners are native, so each cell exercises that arch's real image.
    runs-on: ${{ matrix.runner }}
    strategy:
      fail-fast: false
      matrix:
        runner: [ubuntu-24.04, ubuntu-24.04-arm]
        python: ["3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      # fraise runs as a docker daemon (Go builds inside the image), so only
      # uv is needed here to run pytest against it.
      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
        with:
          python-version: ${{ matrix.python }}

      - name: Run Python SDK integration tests
        run: make test-integration-py

  publish-python:
    name: Publish to PyPI
    if: startsWith(github.ref, 'refs/tags/python/v')
    # integration already requires test, so this gates on both: nothing reaches
    # PyPI unless the SDK passed against a live server on amd64 and arm64.
    needs: integration
    runs-on: ubuntu-latest
    environment: release
    permissions:
      id-token: write # PyPI trusted publishing — no token secret
    defaults:
      run:
        working-directory: sdk/python
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Install uv
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d

      - name: Version must match tag
        run: |
         RAW="${GITHUB_REF_NAME#python/v}"
          if [[ ! "$RAW" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?$ ]]; then
            echo "::error::bad tag '$GITHUB_REF_NAME' — expected python/vX.Y.Z or -alpha.N/-beta.N/-rc.N"; exit 1
          fi
          PKG_VERSION=$(uv run python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
          [ "$RAW" = "$PKG_VERSION" ] || { echo "::error::tag maps to $TAG_VERSION != pyproject $PKG_VERSION"; exit 1; }

      # --out-dir is not optional here. This is a uv workspace, so a bare
      # `uv build` writes to the *workspace root* dist/ no matter which member
      # directory it runs from, while `uv publish` below globs dist/* relative
      # to this job's working-directory (sdk/python) and finds nothing.
      - name: Build
        run: uv build --out-dir dist

      - name: Release
        run: uv publish