kcl-python-bindings.yml

name: kcl-python-bindings
on:
  push:
    branches:
      - main
    paths:
      - '**/Cargo.toml'
      - '**/Cargo.lock'
      - '**/rust-toolchain.toml'
      - 'rust/kcl-python-bindings/**'
      - '**.rs'
      - .github/workflows/kcl-python-bindings.yml
    tags:
      - 'kcl-*'
  pull_request:
    paths:
      - '**/Cargo.toml'
      - '**/Cargo.lock'
      - '**/rust-toolchain.toml'
      - 'rust/kcl-python-bindings/**'
      - '**.rs'
      - .github/workflows/kcl-python-bindings.yml
  workflow_dispatch:
  schedule:
    - cron: 0 * * * * # hourly
permissions:
  contents: read
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true
jobs:
  changes:
    runs-on: namespace-profile-ubuntu-2-cores
    if: github.event_name != 'schedule'
    outputs:
      packaging: ${{ steps.filter.outputs.packaging == 'true' || steps.gates.outputs.found == 'true' }}
    steps:
      - uses: actions/checkout@v7.0.1
      - id: filter
        name: Check for packaging changes
        uses: dorny/paths-filter@v4.0.3
        # A tag push has no previous ref to diff against, so this step can
        # fail there. A tag forces the full matrix on its own.
        continue-on-error: true
        with:
          # These inputs decide whether a wheel builds and links on one
          # architecture but not another.
          filters: |
            packaging:
              - 'rust/kcl-python-bindings/**'
              - 'rust/Cargo.lock'
              - 'rust/**/Cargo.toml'
              - 'rust/rust-toolchain.toml'
              - '.tool-versions'
              - '.github/workflows/kcl-python-bindings.yml'
      - id: gates
        name: Check for platform-gated code
        shell: bash
        # Linux stands in for Windows and macOS only while no crate in the
        # wheel compiles differently per platform. This step tests that
        # premise on every run instead of assuming it. A hit forces the full
        # matrix. Unlisted crates are scanned, so a new crate fails safe.
        # kcl-language-server is excluded because it is not in the wheel, and
        # wasm32 gates are excluded because no wheel targets wasm.
        run: |
          if rg -n 'cfg\([^)]*target_(os|family|env|arch)' \
               --glob '*.rs' \
               --glob '!rust/kcl-language-server/**' \
               rust/ | rg -v wasm32; then
            echo 'Platform-gated code found; building every architecture.'
            echo 'found=true' >> "$GITHUB_OUTPUT"
          else
            echo 'found=false' >> "$GITHUB_OUTPUT"
          fi
  linux:
    name: kcl-python-bindings (linux-${{ matrix.target }})
    runs-on: namespace-profile-ubuntu-8-cores;overrides.cache-tag=modeling-app-general-v2
    # The hourly schedule exists to observe flaky tests. It runs the test job
    # and nothing else.
    if: github.event_name != 'schedule'
    strategy:
      fail-fast: false
      matrix:
        target: [x86_64, aarch64]
    steps:
      - uses: actions/checkout@v7.0.1
      - name: sccache cache on the Namespace volume
        # See the macos job.
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          path: .sccache
      - name: Build wheels
        uses: PyO3/maturin-action@v1
        env:
          # The workspace sets `[profile.release] debug = true`, but no wheel
          # ships debug info: Linux embeds DWARF in the .so and --strip removes
          # it, while mac and Windows write it to .dSYM and .pdb sidecars that
          # are not packaged. Generating it costs build time for output that is
          # then discarded.
          CARGO_PROFILE_RELEASE_DEBUG: '0'
          # maturin-action mounts GITHUB_WORKSPACE at the same path inside the
          # container, so this resolves on both sides. The SCCACHE_ prefix is
          # on its list of variables forwarded into the container.
          RUSTC_WRAPPER: sccache
          SCCACHE_DIR: ${{ github.workspace }}/.sccache
          SCCACHE_CACHE_SIZE: 20G
        with:
          working-directory: rust/kcl-python-bindings
          target: ${{ matrix.target }}
          # --strip is a backstop. Without it a debug .so exceeds PyPI's 100MB
          # limit.
          args: --release --out dist --strip -i python3.11 python3.12 python3.13 python3.14
          # Off so the volume above is used instead of the GitHub cache. That
          # also means the container has no sccache, so before-script installs
          # one.
          sccache: 'false'
          # Maturin selects a cross-compilation container for aarch64. Both
          # containers run on x86_64, so they use the same sccache binary.
          manylinux: auto
          before-script-linux: |
            curl -fsSL https://github.com/mozilla/sccache/releases/download/v0.10.0/sccache-v0.10.0-x86_64-unknown-linux-musl.tar.gz \
              | tar -xz -C /tmp
            install -m 0755 /tmp/sccache-v0.10.0-x86_64-unknown-linux-musl/sccache /usr/local/bin/sccache
            sccache --version
      - name: sccache cache contents
        # sccache ran inside the container and its server exited with
        # it. Measuring the directory answers whether the container wrote to
        # the mounted volume path.
        if: always()
        shell: bash
        run: |
          du -sh .sccache 2>&1 || true
          echo "objects: $(find .sccache -type f 2>/dev/null | wc -l)"
      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-linux-${{ matrix.target }}
          path: rust/kcl-python-bindings/dist
  windows:
    name: kcl-python-bindings (windows)
    runs-on: namespace-profile-windows-8-cores
    needs: changes
    # Linux is the representative target on every other run.
    if: needs.changes.outputs.packaging == 'true' || startsWith(github.ref, 'refs/tags/')
    strategy:
      matrix:
        target:
          - x64
      fail-fast: false
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: actions/setup-python@v7.1.0
        with:
          # Same reason as the macos job: install the set instead of letting
          # the runner image decide what gets published.
          python-version: |
            3.11
            3.12
            3.13
            3.14
          architecture: ${{ matrix.target }}
      - name: Install sccache
        uses: taiki-e/install-action@sccache
      - name: sccache cache on the Namespace volume
        # See the macos job.
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          path: .sccache
      - name: Build wheels
        uses: PyO3/maturin-action@v1
        env:
          RUSTC_WRAPPER: sccache
          SCCACHE_DIR: ${{ github.workspace }}/.sccache
          SCCACHE_CACHE_SIZE: 20G
          # See the linux job.
          CARGO_PROFILE_RELEASE_DEBUG: '0'
        with:
          working-directory: rust/kcl-python-bindings
          target: ${{ matrix.target }}
          args: --release --out dist --find-interpreter --strip
          # Off so the volume above is used instead of the GitHub cache.
          sccache: 'false'
      - name: sccache stats
        if: always()
        run: sccache --show-stats
      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-windows-${{ matrix.target }}
          path: rust/kcl-python-bindings/dist
  macos:
    name: kcl-python-bindings (macos)
    needs: changes
    if: needs.changes.outputs.packaging == 'true' || startsWith(github.ref, 'refs/tags/')
    runs-on: namespace-profile-macos-6-cores
    strategy:
      matrix:
        target:
          - aarch64
      fail-fast: false
    steps:
      - uses: actions/checkout@v7.0.1
      - name: Install sccache
        uses: taiki-e/install-action@sccache
      - name: sccache cache on the Namespace volume
        # The GitHub Actions cache is capped at 10GB per repository, and
        # sccache alone filled it: 8.5GB across 3069 entries, after which every
        # write failed. This volume reports 100GB.
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          path: .sccache
      - name: Install uv
        uses: astral-sh/setup-uv@v10.3.3
      - name: Build wheels
        # Namespace persists /Users/runner/hostedtoolcache across macOS VMs, but
        # not its Python symlink targets under /Library/Frameworks. setup-python
        # then selects a cached Python whose executable is missing.
        run: |
          uv tool run --from cibuildwheel==4.2.1 cibuildwheel \
            rust/kcl-python-bindings \
            --output-dir rust/kcl-python-bindings/dist
        env:
          CIBW_ARCHS_MACOS: arm64
          CIBW_BUILD: cp{311,312,313,314}-macosx_arm64
          CIBW_TEST_COMMAND: python -c 'import kcl'
          RUSTC_WRAPPER: sccache
          SCCACHE_DIR: ${{ github.workspace }}/.sccache
          # sccache evicts its own contents at this size. The volume is shared
          # with nothing else on this profile.
          SCCACHE_CACHE_SIZE: 20G
          # See the linux job.
          CARGO_PROFILE_RELEASE_DEBUG: '0'
          MATURIN_STRIP: 'true'
      - name: sccache stats
        # cibuildwheel does not report compiler-cache statistics.
        if: always()
        run: sccache --show-stats
      - name: Upload wheels
        uses: actions/upload-artifact@v7
        with:
          name: wheels-macos-${{ matrix.target }}
          path: rust/kcl-python-bindings/dist
  test:
    name: kcl-python-bindings (test)
    runs-on: namespace-profile-ubuntu-8-cores;overrides.cache-tag=modeling-app-general-v2
    steps:
      - uses: actions/checkout@v7.0.1
      - name: Track setup
        run: .github/ci-cd-scripts/track-step.sh
        env:
          TAB_API_URL: ${{ vars.TAB_API_URL }}
          TAB_API_KEY: ${{ secrets.TAB_API_KEY }}
          CI_COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
          CI_PR_NUMBER: ${{ github.event.pull_request.number }}
          CI_SUITE: integration:kcl
          CI_STEP: setup
      - name: Install uv
        uses: astral-sh/setup-uv@v10.3.3
      - uses: actions-rust-lang/setup-rust-toolchain@v1.17.0
        with:
          rust-src-dir: rust
          rustflags: '' # Use .cargo/config.toml
      - uses: taiki-e/install-action@just
      - name: Track start
        run: .github/ci-cd-scripts/track-step.sh
        env:
          TAB_API_URL: ${{ vars.TAB_API_URL }}
          TAB_API_KEY: ${{ secrets.TAB_API_KEY }}
          CI_COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
          CI_PR_NUMBER: ${{ github.event.pull_request.number }}
          CI_SUITE: integration:kcl
          CI_STEP: start
      - name: Run tests
        run: |
          cd rust/kcl-python-bindings
          just setup-uv
          just test || true # let TAB determine failure
          ../../.github/ci-cd-scripts/upload-results.sh
        env:
          ZOO_API_TOKEN: ${{ secrets.ZOO_API_TOKEN }}
          ZOO_HOST: https://api.dev.zoo.dev
          TAB_API_URL: ${{ vars.TAB_API_URL }}
          TAB_API_KEY: ${{ secrets.TAB_API_KEY }}
          CI_COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
          CI_PR_NUMBER: ${{ github.event.pull_request.number }}
          CI_SUITE: integration:kcl
  sdist:
    name: kcl-python-bindings (sdist)
    runs-on: namespace-profile-ubuntu-8-cores;overrides.cache-tag=modeling-app-general-v2
    if: github.event_name != 'schedule'
    steps:
      - uses: actions/checkout@v7.0.1
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@v10.3.3
      - name: Create venv
        run: |
          uv venv .venv
          echo "VIRTUAL_ENV=.venv" >> $GITHUB_ENV
          echo "$PWD/.venv/bin" >> $GITHUB_PATH
          uv pip install pip --upgrade
      - name: Build sdist
        uses: PyO3/maturin-action@v1
        with:
          working-directory: rust/kcl-python-bindings
          command: sdist
          args: --out dist
      - name: Upload sdist
        uses: actions/upload-artifact@v7
        with:
          name: wheels-sdist
          path: rust/kcl-python-bindings/dist
  release:
    name: Release
    runs-on: namespace-profile-ubuntu-8-cores;overrides.cache-tag=modeling-app-general-v2
    permissions:
      contents: write
    if: startsWith(github.ref, 'refs/tags/')
    needs: [linux, windows, macos, sdist]
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: actions/download-artifact@v8
        with:
          path: rust/kcl-python-bindings
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@v10.3.3
      - name: do uv things
        run: |
          cd rust/kcl-python-bindings
          uv venv .venv
          echo "VIRTUAL_ENV=.venv" >> $GITHUB_ENV
          echo "$PWD/.venv/bin" >> $GITHUB_PATH
          uv pip install pip --upgrade
      - name: Verify release artifacts
        working-directory: rust/kcl-python-bindings
        run: |
          python - <<'PY'
          from pathlib import Path
          import tomllib

          with Path("Cargo.toml").open("rb") as manifest:
              version = tomllib.load(manifest)["package"]["version"]

          distribution = f"zoo_kcl-{version}"
          expected = (
              ("CPython 3.11 Linux x86_64", f"wheels-linux-x86_64/{distribution}-cp311-cp311-manylinux*_x86_64.whl"),
              ("CPython 3.12 Linux x86_64", f"wheels-linux-x86_64/{distribution}-cp312-cp312-manylinux*_x86_64.whl"),
              ("CPython 3.13 Linux x86_64", f"wheels-linux-x86_64/{distribution}-cp313-cp313-manylinux*_x86_64.whl"),
              ("CPython 3.14 Linux x86_64", f"wheels-linux-x86_64/{distribution}-cp314-cp314-manylinux*_x86_64.whl"),
              ("CPython 3.11 Linux aarch64", f"wheels-linux-aarch64/{distribution}-cp311-cp311-manylinux*_aarch64.whl"),
              ("CPython 3.12 Linux aarch64", f"wheels-linux-aarch64/{distribution}-cp312-cp312-manylinux*_aarch64.whl"),
              ("CPython 3.13 Linux aarch64", f"wheels-linux-aarch64/{distribution}-cp313-cp313-manylinux*_aarch64.whl"),
              ("CPython 3.14 Linux aarch64", f"wheels-linux-aarch64/{distribution}-cp314-cp314-manylinux*_aarch64.whl"),
              ("CPython 3.11 Windows x86_64", f"wheels-windows-x64/{distribution}-cp311-cp311-win_amd64.whl"),
              ("CPython 3.12 Windows x86_64", f"wheels-windows-x64/{distribution}-cp312-cp312-win_amd64.whl"),
              ("CPython 3.13 Windows x86_64", f"wheels-windows-x64/{distribution}-cp313-cp313-win_amd64.whl"),
              ("CPython 3.14 Windows x86_64", f"wheels-windows-x64/{distribution}-cp314-cp314-win_amd64.whl"),
              ("CPython 3.11 macOS arm64", f"wheels-macos-aarch64/{distribution}-cp311-cp311-macosx_*_arm64.whl"),
              ("CPython 3.12 macOS arm64", f"wheels-macos-aarch64/{distribution}-cp312-cp312-macosx_*_arm64.whl"),
              ("CPython 3.13 macOS arm64", f"wheels-macos-aarch64/{distribution}-cp313-cp313-macosx_*_arm64.whl"),
              ("CPython 3.14 macOS arm64", f"wheels-macos-aarch64/{distribution}-cp314-cp314-macosx_*_arm64.whl"),
              ("source distribution", f"wheels-sdist/{distribution}.tar.gz"),
          )

          failures = []
          for label, pattern in expected:
              matches = sorted(Path(".").glob(pattern))
              if len(matches) != 1:
                  failures.append(f"{label}: expected one match for {pattern}, found {matches}")
                  continue
              print(f"{label}: {matches[0]}")

          if failures:
              raise SystemExit(
                  "Required release artifact verification failed:\n"
                  + "\n".join(f"- {failure}" for failure in failures)
              )
          PY
      - name: Publish to PyPI
        working-directory: rust/kcl-python-bindings
        env:
          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
        run: uv publish wheels-*/*