ci.yml

# Continuous integration after changes land on main.
#
# Jobs: lint (seconds), the test matrix, free-threaded Python with the stress suite, mypy,
# a packaging check, live Redis, PostgreSQL and SQL Server backends, a framework version
# matrix and a benchmark/soak gate.
#
# python-wrap is pure Python with no dependencies, so the matrix is wide rather than
# deep: every interpreter the classifiers name, on all three operating systems. Time and
# threading behave differently on Windows (coarser clocks) and macOS (spawn, not fork),
# and a decorator library that schedules, throttles and times things is exactly where
# that shows up.
name: CI

on:
  push:
    branches: [main]

# A force-push should not leave the previous run burning minutes on a dead commit.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

env:
  FORCE_COLOR: "1"

jobs:
  lint:
    name: ruff
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: "3.13"

      - run: uv sync --group dev --frozen

      - name: ruff check
        run: uv run --no-sync ruff check src tests scripts/check_installed.py

      - name: ruff format
        run: uv run --no-sync ruff format --check --diff src tests scripts/check_installed.py

  test:
    name: py${{ matrix.python-version }} · ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      # One red cell should not hide the other fourteen.
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: ${{ matrix.python-version }}

      - run: uv sync --group dev --frozen

      - name: pytest
        run: uv run --no-sync pytest --cov --cov-report=term-missing --cov-report=xml

      # One coverage report is enough; it is the same code on every cell. Keeping it as an
      # artifact (rather than a third-party upload) needs no token and cannot fail the
      # build for a reason unrelated to the code.
      - name: Upload the coverage report
        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
        with:
          name: coverage
          path: coverage.xml
          if-no-files-found: warn

  free-threaded:
    # CPython 3.14t with the GIL off, plus the thread-safety stress suite, which only
    # runs when PW_STRESS=1. This is where real data races show up.
    name: py3.14t (free-threaded) · ubuntu-latest
    runs-on: ubuntu-latest
    env:
      PYTHON_GIL: "0"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: "3.14t"

      - run: uv sync --group dev --frozen

      - name: The GIL must really be off
        run: uv run --no-sync python -c "import sys; assert not sys._is_gil_enabled()"

      - name: pytest
        run: uv run --no-sync pytest -q

      - name: Thread-safety stress suite
        run: uv run --no-sync pytest -q tests/stress
        env:
          PW_STRESS: "1"

  typecheck:
    name: mypy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: "3.13"

      - run: uv sync --group dev --frozen

      # Strict mode, configured in pyproject.toml; `files` already points at src/.
      - name: mypy
        run: uv run --no-sync mypy

  build:
    name: build & wheel contents
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: "3.13"

      - name: Build the sdist and wheel
        run: uv build

      - name: twine check
        run: uvx twine check --strict dist/*

      # The package ships `py.typed` so that type checkers use its annotations. A wheel
      # that drops it still imports and still passes twine, and silently turns every
      # downstream user's types into `Any`.
      - name: The wheel ships py.typed
        run: |
          python3 -m zipfile -l dist/*.whl | tee wheel-listing.txt
          grep -q 'python_wrap/py.typed' wheel-listing.txt

      # Install the built wheel, not the source tree, into an empty venv and run from a
      # scratch directory so `src/` cannot stand in for anything the wheel left out.
      - name: Install the wheel into a clean environment
        run: |
          uv venv "$RUNNER_TEMP/smoke" --python 3.13
          uv pip install --python "$RUNNER_TEMP/smoke" dist/*.whl
          version=$(sed -nE 's/^__version__ *= *"([^"]+)".*/\1/p' src/python_wrap/__init__.py)
          "$RUNNER_TEMP/smoke/bin/python" -I scripts/check_installed.py "$version"

      - name: The source distribution includes its test fixtures
        run: |
          mkdir "$RUNNER_TEMP/sdist"
          tar -xzf dist/*.tar.gz -C "$RUNNER_TEMP/sdist" --strip-components=1
          cd "$RUNNER_TEMP/sdist"
          uv sync --group dev
          uv run --no-sync pytest tests/test_examples.py tests/test_benchmarks_smoke.py

      - name: Upload the distributions
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
        with:
          name: dist
          path: dist/
          if-no-files-found: error

  backend-integration:
    name: Redis coordination and fork regressions
    runs-on: ubuntu-latest
    env:
      PW_REQUIRE_REDIS: "1"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          python-version: "3.13"
      - name: Install the real Redis server
        run: sudo apt-get update && sudo apt-get install -y redis-server
      - run: uv sync --group dev --frozen
      - name: Validate atomic backend scripts against Redis
        run: uv run --no-sync pytest tests/test_redis_backends.py tests/test_fork_safety.py

  framework-integration:
    # Oldest supported and newest releases of each framework, so an adapter that only
    # works on one end of the range shows up here.
    name: Frameworks (${{ matrix.versions.name }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        versions:
          - name: oldest
            python: "3.10"
            pins: >-
              --with 'flask==3.0.*' --with 'fastapi==0.115.*' --with 'httpx==0.27.*'
              --with 'django==4.2.*' --with 'celery==5.3.*' --with 'requests==2.31.*'
          - name: latest
            python: "3.13"
            pins: >-
              --with 'flask>=3' --with 'fastapi>=0.115' --with 'httpx>=0.27,<1'
              --with 'django>=5' --with 'celery>=5.4' --with 'requests>=2.32'
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          python-version: ${{ matrix.versions.python }}
      - run: uv sync --group dev --frozen
      - name: Exercise real framework request/task lifecycles and HTTP clients
        run: >-
          uv run --frozen ${{ matrix.versions.pins }}
          pytest tests/test_integrations.py tests/test_http.py tests/test_web.py
          tests/test_celery_helpers.py

  sql-backends:
    # PgAdvisoryLock, SqlAppLock and the transient-error predicates against real servers.
    name: PostgreSQL and SQL Server backends
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_PASSWORD: pw
          POSTGRES_DB: pw
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U postgres" --health-interval 5s
          --health-timeout 5s --health-retries 20
      mssql:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: "Y"
          MSSQL_SA_PASSWORD: "CiOnly-Passw0rd"
        ports: ["1433:1433"]
    env:
      PW_REQUIRE_SQL: "1"
      # Throwaway credentials of the service containers above; not secrets.
      PW_POSTGRES_URL: postgresql+psycopg://postgres:pw@127.0.0.1:5432/pw
      PW_MSSQL_URL: mssql+pymssql://sa:CiOnly-Passw0rd@127.0.0.1:1433/master
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          python-version: "3.13"
      - run: uv sync --group dev --frozen
      - name: Wait for SQL Server to accept logins
        run: |
          for i in $(seq 1 60); do
            uv run --frozen --with pymssql python -c "import pymssql; pymssql.connect('127.0.0.1', 'sa', 'CiOnly-Passw0rd', 'master', port=1433).close()" && exit 0
            sleep 2
          done
          exit 1
      - name: Live SQL backend tests
        run: >-
          uv run --frozen --with 'sqlalchemy>=2' --with 'psycopg[binary]>=3.1'
          --with 'pymssql>=2.3' pytest tests/test_sql_backends_live.py tests/test_transient_predicates.py

  benchmarks:
    # Coarse overhead regression gate next to the specialist libraries, plus a short soak.
    # Shared runners are noisy, so the ratio is generous; investigate, do not tune it down.
    name: Benchmarks vs tenacity/cachetools and soak
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          python-version: "3.13"
      - run: uv sync --group dev --frozen
      - name: Compare with tenacity, backoff and cachetools
        run: >-
          uv run --frozen --with tenacity --with backoff --with cachetools
          python benchmarks/compare.py --max-ratio 5
      - name: Soak a policy against a flaky dependency
        run: uv run --no-sync python benchmarks/soak.py --duration 30 --threads 16