python.yml

# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# SPDX-License-Identifier: Apache-2.0

name: Python checks

permissions:
  contents: read

on:
  # Stacked PRs target a feature branch, so Python checks also run when the base is not main.
  pull_request:

jobs:
  check-paths:
    runs-on: ubuntu-latest
    outputs:
      any_changed: ${{ steps.changed-files.outputs.any_changed }}
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
        with:
          files: |
            python/**
            spec/**
            .github/workflows/python.yml

  uv-lock-check:
    needs: check-paths
    if: needs.check-paths.outputs.any_changed == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          # Use the PR head ref to allow pushing back to the branch
          ref: ${{ github.head_ref }}
          # Use a token that can push to the branch (for release-please PRs)
          token: ${{ startsWith(github.head_ref, 'release-please--') && secrets.RELEASE_PLEASE_TOKEN || github.token }}

      - name: Install uv
        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
        with:
          enable-cache: true

      - name: Check if this is a release-please PR
        id: check-release-please
        run: |
          if [[ "${GITHUB_HEAD_REF}" == release-please--* ]]; then
            echo "is_release_please=true" >> $GITHUB_OUTPUT
          else
            echo "is_release_please=false" >> $GITHUB_OUTPUT
          fi

      - name: Update lockfiles for release-please PR
        if: steps.check-release-please.outputs.is_release_please == 'true'
        working-directory: python
        run: |
          echo "Updating uv.lock for release-please PR..."
          uv lock
          ../scripts/export_requirements

      - name: Commit lockfile updates
        if: steps.check-release-please.outputs.is_release_please == 'true'
        run: |
          # Use CLA-covered maintainer identity from MAINTAINERS.yaml
          git config user.name "$(yq '.ci.commit_author.name' MAINTAINERS.yaml)"
          git config user.email "$(yq '.ci.commit_author.email' MAINTAINERS.yaml)"
          if ! git diff --quiet python/uv.lock python/requirements.txt; then
            git add python/uv.lock python/requirements.txt
            git commit -m "chore: update Python lockfiles"
            git push
            echo "Lockfiles updated and pushed"
          else
            echo "No lockfile changes needed"
          fi

      - name: Check uv.lock is up to date
        working-directory: python
        run: |
          uv lock --check

      - name: Check requirements.txt is up to date
        run: |
          scripts/export_requirements
          git diff --exit-code python/requirements.txt

      - name: Run security scan
        run: scripts/run_python_security_checks

  python-checks:
    needs: check-paths
    if: needs.check-paths.outputs.any_changed == 'true'
    runs-on: ${{ matrix.os }}
    env:
      PATH: ${{ github.workspace }}/go/bin:${{ github.workspace }}/.local/share/pnpm:${{ github.workspace }}/.local/bin:/usr/local/bin:/usr/bin:/bin
    strategy:
      matrix:
        os:
          - ubuntu-latest      # x86_64
          - ubuntu-24.04-arm   # ARM64
        python-version:
          - "3.10"
          - "3.11"
          - "3.12"
          - "3.13"
          - "3.14"
        include:
          # PyPy runs on x86 only.
          - os: ubuntu-latest
            python-version: "pypy3.11"
      fail-fast: false

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false

      - name: Set up Go
        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
        with:
          go-version: stable

      # uv has no PyPy 3.11 download for linux x86_64, and PyPy 8.0 has no
      # pydantic-core wheels. Pin 7.3.23 (Python 3.11.15, pp73 ABI); uv finds
      # it on PATH.
      - name: Set up PyPy
        if: ${{ startsWith(matrix.python-version, 'pypy') }}
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: pypy3.11-v7.3.23

      - name: Install uv and setup Python version
        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}

      - name: Format check
        run: uv run --active --directory python ruff format --check --preview .

      - name: Lint with ruff
        run: uv run --active --directory python ruff check --select I .

      - name: Static type check (ty)
        run: uv run --active --directory python ty check

      - name: Static type check (pyrefly)
        run: uv run --active --directory python pyrefly check

      - name: Install Handlebars 4.7.9
        run: |
          npm install --prefix "${RUNNER_TEMP}/hbjs" handlebars@4.7.9
          echo "HANDLEBARS_JS=${RUNNER_TEMP}/hbjs/node_modules/handlebars" >> "$GITHUB_ENV"

      - name: Run Python tests for Python ${{ matrix.python-version }}
        working-directory: ./python
        run: |
          uv run --python ${{ matrix.python-version }} --active --isolated pytest -xvvs --log-level=DEBUG .

      - name: Build distributions
        run: ./scripts/build_dists

  python-checks-all:
    if: always()
    needs: [uv-lock-check, python-checks]
    runs-on: ubuntu-latest
    steps:
      - name: Check overall status
        run: |
          if [[ "${NEEDS_UV_LOCK_CHECK_RESULT}" == "failure" || "${NEEDS_PYTHON_CHECKS_RESULT}" == "failure" ]]; then
            echo "Python checks failed"
            exit 1
          fi
          echo "Python checks passed or were skipped"
          exit 0
        env:
          NEEDS_UV_LOCK_CHECK_RESULT: ${{ needs.uv-lock-check.result }}
          NEEDS_PYTHON_CHECKS_RESULT: ${{ needs.python-checks.result }}