build-python.yml

name: Python Package

# This workflow tests, builds, and publishes the Vista SDK Python package
# - Tests: Run in parallel across Python 3.10, 3.11, 3.12, and 3.13
# - Build: Creates distributable packages (only runs if all tests pass)
# - Publish: Uploads to PyPI (only on push to the main branch)

on:
  push:
    branches: [main]
    paths: ["python/**", ".github/workflows/build-python.yml"]
  pull_request:
    branches: [main]
    paths: ["python/**", ".github/workflows/build-python.yml"]
  workflow_dispatch:

env:
  CI_BUILD: true
  BASE_VERSION: "0.3.1-preview"

jobs:
  test:
    name: Test (Python ${{ matrix.python-version }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
      fail-fast: false # Continue testing other versions even if one fails

    steps:
      # Get the source code from the repository
      - name: Checkout entire repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

      # Set up the specific Python version for this matrix job
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: ${{ matrix.python-version }}

      # Install uv package manager for fast dependency management
      - name: Install uv
        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4

      # Install all Python dependencies including dev dependencies
      - name: Install dependencies
        run: |
          cd python
          uv sync --dev

      # Copy shared resources into the Python package for runtime access
      - name: Copy resources folder into python/src/vista_sdk
        run: |
          # Remove existing resources directory if it exists
          rm -rf ./python/src/vista_sdk/resources
          # Copy resources directory
          cp -r ./resources ./python/src/vista_sdk/resources

      # Generate version-specific code based on available resources
      - name: Generate VisVersion script
        env:
          PYTHONPATH: ${{ github.workspace }}/python/src
        run: |
          cd python
          uv run python src/vista_sdk/source_generator/vis_versions_generator.py --resources_dir ../resources

      # Run the test suite for this Python version (excluding benchmarks and profiling)
      - name: Run tests
        env:
          PYTHONPATH: ${{ github.workspace }}/python/src
        run: |
          cd python
          uv run pytest tests --ignore=tests/benchmark --ignore=tests/profiling

  build:
    name: Build
    runs-on: ubuntu-latest
    needs: test

    steps:
      # Get the source code from the repository
      - name: Checkout entire repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          fetch-depth: 0 # Full history needed for revision count

      - name: Get revision number
        id: rev
        run: |
          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
          if [ -z "$LATEST_TAG" ]; then
            echo "count=$(git rev-list --count HEAD)" >> $GITHUB_OUTPUT
          else
            echo "count=$(git rev-list --count ${LATEST_TAG}..HEAD)" >> $GITHUB_OUTPUT
          fi
          echo "Revision: $(cat $GITHUB_OUTPUT)"

      # Set up Python 3.13 for building (latest supported version)
      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: "3.13"

      # Install uv package manager for fast dependency management
      - name: Install uv
        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4

      # Install Python dependencies (production only, no dev dependencies needed for building)
      - name: Install dependencies
        run: |
          cd python
          uv sync

      # Copy shared resources into the Python package for runtime access
      - name: Copy resources folder into python/src/vista_sdk
        run: |
          # Remove existing resources directory if it exists
          rm -rf ./python/src/vista_sdk/resources
          # Copy resources directory
          cp -r ./resources ./python/src/vista_sdk/resources

      # Generate version-specific code based on available resources
      - name: Generate VisVersion script
        env:
          PYTHONPATH: ${{ github.workspace }}/python/src
        run: |
          cd python
          uv run python src/vista_sdk/source_generator/vis_versions_generator.py --resources_dir ../resources

      # Set version using GitHub run number
      - name: Set package version
        env:
          REV: ${{ steps.rev.outputs.count }}
        run: |
          VERSION="${BASE_VERSION}-${REV}"
          echo "Setting version to: $VERSION"
          sed -i "s/__version__ = \".*\"/__version__ = \"$VERSION\"/" python/src/vista_sdk/__init__.py
          cat python/src/vista_sdk/__init__.py

      # Build the Python package (wheel and source distribution)
      - name: Build package
        run: |
          cd python
          uv build

      # Store build artifacts for the publish job. The name and path are exlusive to GitHub Actions
      - name: Upload build artifacts
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: python-package
          path: python/dist/
  publish:
    # This job runs on pushes to main or manual triggers, but not on pull requests.
    name: Publish
    runs-on: ubuntu-latest
    needs: [build]
    if: ${{ success() && !github.base_ref }}

    # OIDC permissions for trusted publishing to PyPI
    permissions:
      id-token: write

    steps:
      # Retrieve the built package from the build job
      - name: Download build artifacts
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
        with:
          name: python-package
          path: dist/

      # Publish to PyPI using OIDC trusted publishing (no token needed)
      - name: Publish package to PyPI
        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
        with:
          print-hash: true