python.yml

name: Python CI/CD

on:
  push:
    branches:
      - main
    paths:
      - 'python/**'
      - '.github/workflows/python.yml'
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'python/**'
      - '.github/workflows/python.yml'
  workflow_dispatch:
    inputs:
      bump_type:
        description: 'Version bump type'
        required: true
        type: choice
        options:
          - patch
          - minor
          - major
      description:
        description: 'Release description (optional)'
        required: false
        type: string

# Least privilege by default (best practice #10 / template parity): individual
# release jobs raise this to `contents: write` where they need it.
permissions:
  contents: read

jobs:
  # REQUIRED CI CHECKS - All must pass before release
  # These jobs ensure code quality and tests pass before any release

  # === CHANGE DETECTION ===
  # Template parity: the JavaScript and Rust pipelines gated their expensive
  # jobs on what actually changed, while Python and C# ran everything for a
  # documentation-only pull request. The workflow-level `paths:` filter only
  # decides whether this workflow runs at all; this job decides which jobs
  # inside it are worth running.
  detect-changes:
    timeout-minutes: 10
    # Read-only check: a newer run supersedes this one.
    concurrency:
      group: check-${{ github.workflow }}-${{ github.ref }}-detect-changes
      cancel-in-progress: true
    name: Detect Changes
    runs-on: ubuntu-latest
    if: github.event_name != 'workflow_dispatch'
    outputs:
      py-changed: ${{ steps.changes.outputs.py-changed }}
      toml-changed: ${{ steps.changes.outputs.toml-changed }}
      docs-changed: ${{ steps.changes.outputs.docs-changed }}
      workflow-changed: ${{ steps.changes.outputs.workflow-changed }}
      any-code-changed: ${{ steps.changes.outputs.any-code-changed }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.13'

      - name: Detect changes
        id: changes
        working-directory: ./python
        env:
          GITHUB_EVENT_NAME: ${{ github.event_name }}
          GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: python scripts/detect_code_changes.py

  # Linting and formatting
  lint:
    timeout-minutes: 15
    # Read-only check: a newer run supersedes this one.
    concurrency:
      group: check-${{ github.workflow }}-${{ github.ref }}-lint
      cancel-in-progress: true
    name: Lint and Format Check
    runs-on: ubuntu-latest
    needs: [detect-changes]
    # `!cancelled()` is required because detect-changes is skipped on
    # workflow_dispatch; it still propagates a real workflow cancellation.
    if: >-
      ${{
      !cancelled() && (
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      needs.detect-changes.outputs.py-changed == 'true' ||
      needs.detect-changes.outputs.toml-changed == 'true' ||
      needs.detect-changes.outputs.docs-changed == 'true' ||
      needs.detect-changes.outputs.workflow-changed == 'true'
      )
      }}
    steps:
      - uses: actions/checkout@v7
        with:
          # Full history: the merge simulation below needs the base branch.
          fetch-depth: 0

      # Best practice #7: the `refs/pull/N/merge` preview goes stale as soon as
      # the base branch moves, so checks would validate code that is not what
      # will actually land. Merge the latest base branch first.
      - name: Simulate fresh merge with base branch (PR only)
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        # Explicit shell: some of these jobs run on Windows runners, where
        # the default shell is PowerShell.
        shell: bash
        run: bash scripts/simulate-fresh-merge.sh

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.13'

      - name: Install dependencies
        working-directory: ./python
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"

      - name: Run Ruff linting
        working-directory: ./python
        run: ruff check src tests scripts

      - name: Check Ruff formatting
        working-directory: ./python
        run: ruff format --check src tests scripts

      - name: Run mypy
        working-directory: ./python
        run: mypy src

      - name: Check file size limit
        working-directory: ./python
        run: python scripts/check_file_size.py

  # Test matrix: Python on multiple OS.
  # Until issue #41 this job ran on ubuntu-latest only, while the JavaScript,
  # Rust and C# suites all ran on three operating systems; a Windows-only
  # failure (line endings, path separators, locale-dependent encoding) would
  # have reached PyPI unnoticed.
  test:
    timeout-minutes: 30
    # Read-only check: a newer run supersedes this one.
    concurrency:
      group: check-${{ github.workflow }}-${{ github.ref }}-test-${{ matrix.os }}
      cancel-in-progress: true
    name: Test (Python 3.13 on ${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    needs: [detect-changes]
    # `!cancelled()` is required because detect-changes is skipped on
    # workflow_dispatch; it still propagates a real workflow cancellation.
    if: >-
      ${{
      !cancelled() && (
      github.event_name == 'push' ||
      github.event_name == 'workflow_dispatch' ||
      needs.detect-changes.outputs.py-changed == 'true' ||
      needs.detect-changes.outputs.toml-changed == 'true' ||
      needs.detect-changes.outputs.docs-changed == 'true' ||
      needs.detect-changes.outputs.workflow-changed == 'true'
      )
      }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - uses: actions/checkout@v7
        with:
          # Full history: the merge simulation below needs the base branch.
          fetch-depth: 0

      # Best practice #7: the `refs/pull/N/merge` preview goes stale as soon as
      # the base branch moves, so checks would validate code that is not what
      # will actually land. Merge the latest base branch first.
      - name: Simulate fresh merge with base branch (PR only)
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        # Explicit shell: some of these jobs run on Windows runners, where
        # the default shell is PowerShell.
        shell: bash
        run: bash scripts/simulate-fresh-merge.sh

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.13'

      - name: Install dependencies
        working-directory: ./python
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"

      - name: Run tests
        working-directory: ./python
        run: pytest tests/ -v --cov=src --cov-report=xml --cov-report=term

      # One upload per commit: the matrix legs produce identical coverage for a
      # pure-Python package, and uploading all three only adds Codecov noise.
      - name: Upload coverage to Codecov
        if: matrix.os == 'ubuntu-latest'
        uses: codecov/codecov-action@v7
        with:
          files: ./python/coverage.xml
          fail_ci_if_error: false
          token: ${{ secrets.CODECOV_TOKEN }}

  # Build package - only runs if lint and test pass
  build:
    timeout-minutes: 20
    # Read-only check: a newer run supersedes this one.
    concurrency:
      group: check-${{ github.workflow }}-${{ github.ref }}-build
      cancel-in-progress: true
    name: Build Package
    runs-on: ubuntu-latest
    needs: [lint, test]
    # Skipped together with lint and test when nothing relevant changed.
    if: >-
      ${{
      !cancelled() &&
      needs.lint.result == 'success' &&
      needs.test.result == 'success'
      }}
    steps:
      - uses: actions/checkout@v7
        with:
          # Full history: the merge simulation below needs the base branch.
          fetch-depth: 0

      # Best practice #7: the `refs/pull/N/merge` preview goes stale as soon as
      # the base branch moves, so checks would validate code that is not what
      # will actually land. Merge the latest base branch first.
      - name: Simulate fresh merge with base branch (PR only)
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        # Explicit shell: some of these jobs run on Windows runners, where
        # the default shell is PowerShell.
        shell: bash
        run: bash scripts/simulate-fresh-merge.sh

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.13'

      - name: Install build dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine

      - name: Build package
        working-directory: ./python
        run: python -m build

      - name: Check package
        working-directory: ./python
        run: twine check dist/*

      - name: Upload artifacts
        uses: actions/upload-artifact@v7
        with:
          name: dist
          path: python/dist/

  # Check for changelog fragments in PRs (similar to changesets check)
  changelog:
    timeout-minutes: 10
    # Read-only check: a newer run supersedes this one.
    concurrency:
      group: check-${{ github.workflow }}-${{ github.ref }}-changelog
      cancel-in-progress: true
    name: Changelog Fragment Check
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      # Best practice #7: the `refs/pull/N/merge` preview goes stale as soon as
      # the base branch moves, so checks would validate code that is not what
      # will actually land. Merge the latest base branch first.
      - name: Simulate fresh merge with base branch (PR only)
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        # Explicit shell: some of these jobs run on Windows runners, where
        # the default shell is PowerShell.
        shell: bash
        run: bash scripts/simulate-fresh-merge.sh

      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.13"

      - name: Check for changelog fragments
        working-directory: ./python
        env:
          GITHUB_BASE_REF: ${{ github.base_ref }}
          # Passed through the environment: a branch name is attacker-controlled
          # and must never be interpolated straight into a shell script.
          HEAD_REF: ${{ github.head_ref }}
        run: python scripts/validate_changeset.py

  # RELEASE JOBS - Only run after all CI checks pass

  # Automatic release on push to main (if version changed)
  auto-release:
    timeout-minutes: 45
    # Writer: every job in the repository that pushes commits, tags or
    # packages shares this group, so releases queue instead of racing, and a
    # started release is never cancelled mid-publish.
    concurrency:
      group: main-writer-${{ github.repository }}
      cancel-in-progress: false
      queue: max
    name: Auto Release
    needs: [lint, test, build]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.13'

      - name: Setup Node.js
        # The post-publish registry readback is a shared Node helper, so the
        # release jobs need Node even though the package itself is Python.
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine

      - name: Check if version changed
        id: version_check
        working-directory: ./python
        run: |
          # Get current version from pyproject.toml
          CURRENT_VERSION=$(grep -Po '(?<=^version = ")[^"]*' pyproject.toml)
          PACKAGE_NAME=$(grep -Po '(?<=^name = ")[^"]*' pyproject.toml | head -1)
          echo "current_version=$CURRENT_VERSION" >> "$GITHUB_OUTPUT"
          echo "package_name=$PACKAGE_NAME" >> "$GITHUB_OUTPUT"

          # Decide based on the registry, not on the local git tag. PyPI returns 200 for an
          # existing version's JSON metadata and 404 otherwise. See
          # docs/case-studies/issue-25/README.md for why the tag is not a reliable proxy.
          STATUS=$(curl -sS -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${PACKAGE_NAME}/${CURRENT_VERSION}/json")
          echo "PyPI HTTP status for ${PACKAGE_NAME}@${CURRENT_VERSION}: ${STATUS}"
          if [ "$STATUS" = "200" ]; then
            echo "Version ${PACKAGE_NAME}@${CURRENT_VERSION} already on PyPI, skipping publish"
            echo "should_release=false" >> "$GITHUB_OUTPUT"
          else
            echo "Version ${PACKAGE_NAME}@${CURRENT_VERSION} is NOT on PyPI, will publish"
            echo "should_release=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Download artifacts
        if: steps.version_check.outputs.should_release == 'true'
        uses: actions/download-artifact@v8
        with:
          name: dist
          path: python/dist/

      - name: PyPI publish preflight
        # Issue #41: the 0.2.0 release died inside the publish action with
        # `invalid-publisher: valid token, but no corresponding publisher`,
        # which names none of the values an operator has to enter on PyPI and
        # does not say the missing piece lives outside this repository. This
        # step prints the four claims and the registration steps up front.
        # It reports without gating: a correctly registered *pending* publisher
        # is indistinguishable from none at all until the first upload lands.
        if: steps.version_check.outputs.should_release == 'true'
        working-directory: ./python
        env:
          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
          # Switch to '1' to dump the resolved OIDC claims; quiet by default.
          PYPI_PREFLIGHT_VERBOSE: '0'
        run: |
          python scripts/pypi_publish_preflight.py \
            --package "${{ steps.version_check.outputs.package_name }}"

      - name: Publish to PyPI
        id: pypi_publish
        if: steps.version_check.outputs.should_release == 'true'
        # Uses PyPI's OIDC Trusted Publisher flow (id-token: write below). If you see "Trusted
        # Publisher … not configured" in the logs, configure it for this repo + workflow on PyPI.
        # See docs/case-studies/issue-25/README.md for the broader context.
        # A PYPI_API_TOKEN secret, when present, takes over so a first release
        # can happen before trusted publishing is registered; without the
        # secret the `password` input is empty and OIDC is used as before.
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          packages-dir: python/dist/
          password: ${{ secrets.PYPI_API_TOKEN }}
          verbose: true
          skip-existing: true

      - name: Explain a failed publish
        # Turns the raw OIDC exchange error into the runbook. Without this the
        # only guidance in the log is a list of claims and a 'not found'.
        if: failure() && steps.pypi_publish.outcome == 'failure'
        working-directory: ./python
        env:
          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
          PYPI_PREFLIGHT_VERBOSE: '1'
        run: |
          python scripts/pypi_publish_preflight.py \
            --package "${{ steps.version_check.outputs.package_name }}"

      - name: Verify package on PyPI
        # Issue #41: this readback allowed twenty-five seconds, the same class
        # of too-short budget that turned a successful NuGet publish into a red
        # run. It now uses the shared, per-registry-tuned readback.
        if: steps.version_check.outputs.should_release == 'true' && steps.pypi_publish.outcome == 'success'
        env:
          REGISTRY_WAIT_VERBOSE: '0'
        run: |
          node scripts/wait-for-registry.mjs --registry pypi \
            --name "${{ steps.version_check.outputs.package_name }}" \
            --version "${{ steps.version_check.outputs.current_version }}"

      - name: Create GitHub Release
        if: steps.version_check.outputs.should_release == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        working-directory: ./python
        run: |
          python scripts/create_github_release.py \
            --version "${{ steps.version_check.outputs.current_version }}" \
            --repository "${{ github.repository }}" \
            --tag-prefix "python_v" \
            --language "Python"

  # Manual release via workflow_dispatch - only after CI passes
  manual-release:
    timeout-minutes: 45
    # Writer: every job in the repository that pushes commits, tags or
    # packages shares this group, so releases queue instead of racing, and a
    # started release is never cancelled mid-publish.
    concurrency:
      group: main-writer-${{ github.repository }}
      cancel-in-progress: false
      queue: max
    name: Manual Release
    needs: [lint, test, build]
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Python
        uses: actions/setup-python@v7
        with:
          python-version: '3.13'

      - name: Install dependencies
        working-directory: ./python
        run: |
          python -m pip install --upgrade pip
          pip install build twine "scriv[toml]"

      - name: Setup Node.js
        # The post-publish registry readback is a shared Node helper.
        uses: actions/setup-node@v7
        with:
          node-version: '22'

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Collect changelog fragments
        working-directory: ./python
        run: |
          # Check if there are any fragments to collect
          FRAGMENTS=$(find changelog.d -name "*.md" ! -name "README.md" ! -name "*.j2" 2>/dev/null | wc -l)
          if [ "$FRAGMENTS" -gt 0 ]; then
            echo "Found $FRAGMENTS changelog fragment(s), collecting..."
            scriv collect --version "${{ github.event.inputs.bump_type }}"
          else
            echo "No changelog fragments found, skipping collection"
          fi

      - name: Version and commit
        id: version
        working-directory: ./python
        run: |
          python scripts/version_and_commit.py \
            --bump-type "${{ github.event.inputs.bump_type }}" \
            --description "${{ github.event.inputs.description }}"

      - name: Build package
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        working-directory: ./python
        run: python -m build

      - name: Check package
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        working-directory: ./python
        run: twine check dist/*

      - name: Read package name from pyproject.toml
        id: pkg
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        working-directory: ./python
        run: |
          PACKAGE_NAME=$(grep -Po '(?<=^name = ")[^"]*' pyproject.toml | head -1)
          echo "package_name=$PACKAGE_NAME" >> "$GITHUB_OUTPUT"

      - name: PyPI publish preflight
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        working-directory: ./python
        env:
          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
          PYPI_PREFLIGHT_VERBOSE: '0'
        run: |
          python scripts/pypi_publish_preflight.py \
            --package "${{ steps.pkg.outputs.package_name }}"

      - name: Publish to PyPI
        id: pypi_publish
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        # See note above: relies on PyPI Trusted Publisher; see docs/case-studies/issue-25/README.md.
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          packages-dir: python/dist/
          password: ${{ secrets.PYPI_API_TOKEN }}
          verbose: true
          skip-existing: true

      - name: Explain a failed publish
        if: failure() && steps.pypi_publish.outcome == 'failure'
        working-directory: ./python
        env:
          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
          PYPI_PREFLIGHT_VERBOSE: '1'
        run: |
          python scripts/pypi_publish_preflight.py \
            --package "${{ steps.pkg.outputs.package_name }}"

      - name: Verify package on PyPI
        if: (steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true') && steps.pypi_publish.outcome == 'success'
        env:
          REGISTRY_WAIT_VERBOSE: '0'
        run: |
          node scripts/wait-for-registry.mjs --registry pypi \
            --name "${{ steps.pkg.outputs.package_name }}" \
            --version "${{ steps.version.outputs.new_version }}"

      - name: Create GitHub Release
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        working-directory: ./python
        run: |
          python scripts/create_github_release.py \
            --version "${{ steps.version.outputs.new_version }}" \
            --repository "${{ github.repository }}" \
            --tag-prefix "python_v" \
            --language "Python"