ci.yml

name: CI

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  push:
    branches: [main]

# Superseded runs are cancelled: force-pushing to a PR branch should not leave the previous
# run burning minutes on a result nobody will read.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  test:
    name: Unit tests (Python ${{ matrix.python-version }})
    runs-on: ubuntu-latest
    strategy:
      # Report every failing interpreter, not just the first.
      fail-fast: false
      matrix:
        # requires-python is ">=3.10"; test the whole range that claim covers.
        python-version: ["3.10", "3.11", "3.12", "3.13"]

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # setuptools-scm derives the version from tags, so it needs full history.
          # Without this the build fails or produces a 0.1.dev1 placeholder.
          fetch-depth: 0

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
          cache-dependency-path: pyproject.toml

      - name: Install package and dependencies
        # The [analysis] extra is required, not optional, for a meaningful test run: the
        # query-conversion tests skip themselves when pandas/numpy are absent, so a run
        # without it would pass while silently testing nothing.
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[analysis,dev]"

      - name: Run unit tests
        # Integration tests need a live MLDP ecosystem on localhost:50051-50053 and are
        # deselected by marker.  They self-skip without a backend, but deselecting them
        # outright means a missing backend can never be mistaken for a passing run.
        run: pytest tests/unit -v -m "not integration"

  quality:
    name: Lint, type-check, and docs
    runs-on: ubuntu-latest
    # These checks are interpreter-independent, so they run once rather than on all four
    # matrix legs -- no added signal, 4x the runtime.
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: pyproject.toml

      - name: Install package and dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[analysis,dev]"

      - name: Ruff lint
        run: ruff check --output-format=github .

      - name: Ruff format check
        run: ruff format --check .

      - name: Type check
        # Config under [tool.mypy] in pyproject.toml.  The generated gRPC package is excluded
        # until it ships typed stubs (osprey-dcs/dp-grpc#158); everything hand-written is checked.
        run: mypy src/

      - name: Check cookbook snippets
        # Type-checks every Python example in doc/cookbook against this package, so a recipe
        # referencing a renamed attribute or method fails here rather than in a user's hands.
        run: python .dev/tools/check-cookbook-snippets.py

      - name: Check release notes
        # Each doc/release-notes/rel-X.Y.Z.md is published verbatim as its release body, so it
        # must carry a verification section whose signing identity names its own tag.  Checked
        # here so a mistake fails the notes PR, not the tag push.  doc/release-notes/NEXT.md, the
        # version-less draft renamed at the cut, is checked the other way round: it must carry none
        # of those tag-bearing parts, since any it has guesses a version not yet decided.
        run: python .dev/tools/check-release-notes.py

  build:
    name: Build distributions
    runs-on: ubuntu-latest
    # Catches packaging breakage (bad metadata, missing files, an sdist that will not build)
    # at PR time rather than at tag time, when the tag is already public.
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      - name: Build wheel and sdist
        run: |
          python -m pip install --upgrade pip build twine
          python -m build

      - name: Verify distribution metadata
        run: twine check --strict dist/*

      - name: Verify the wheel installs and imports cleanly
        # A wheel that builds but does not import is a release-day surprise; a fresh venv
        # with no dev dependencies present is the honest test of that.
        run: |
          python -m venv /tmp/wheel-check
          /tmp/wheel-check/bin/pip install dist/*.whl
          /tmp/wheel-check/bin/python -c "
          from dp_python_lib.client import MldpClient, QueryParams
          from importlib.metadata import version
          print('installed version:', version('dp-python-lib'))
          "

      - name: Upload distributions
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: dist-${{ github.sha }}
          path: dist/
          retention-days: 7