tests.yml

# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python

name: Python package

on:
  push:
    branches: ["master"]
  pull_request:
    branches: ["master"]

jobs:
  tests:
    name: "Run tests with Python ${{ matrix.python-version }}"
    runs-on: "ubuntu-latest"

    # The suite takes about a minute; the slowest leg (PyPy) about three.
    # Without a limit here a job that stops making progress -- a wedged
    # thread in one of the concurrency tests, say -- is only stopped by
    # the six-hour default, holding up the whole run and reporting
    # nothing useful when it finally dies.
    timeout-minutes: 20

    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: false
      matrix:
        python-version:
          - "pypy3.10"
          - "3.10"
          - "3.11"
          - "3.12"
          - "3.13"
          - "3.14"
          # Free-threaded (PEP 703) build.  Runs the same suite with the
          # GIL disabled; see docs/free-threading.md.
          - "3.14t"
        experimental: [ false ]
        include:
          # Python 3.15, which `allow-prereleases` below resolves to the
          # newest pre-release the runner image publishes -- 3.15.0rc1 at the
          # time of writing, and 3.15.0 itself once it ships in October 2026,
          # with no change needed here.
          #
          # Advisory (`experimental: true` -> `continue-on-error`) while 3.15
          # is a pre-release: the suite passes on 3.15.0rc1 today, but rc2 and
          # the final release are still to come, and a regression in CPython
          # itself -- or a test dependency that has no 3.15 wheels yet and
          # fails to build from source -- must not block merges on a version
          # nothing runs in production.  Move these two entries up into the
          # `python-version` list above (and delete them from `include`) to
          # make 3.15 a required check once 3.15.0 final is out.
          - python-version: "3.15"
            experimental: true
          - python-version: "3.15t"
            experimental: true

    steps:
      - uses: actions/checkout@v4
        with:
            fetch-depth: 0
      # setup-python must be >= v5.3: that is the first release that
      # understands the free-threaded "t" suffix.  On v4, "3.14t" is
      # looked up as a literal version against arch x64 rather than
      # x64-freethreaded, and the job fails with "The version '3.14t'
      # with architecture 'x64' was not found".
      - uses: "actions/setup-python@v5"
        with:
          python-version: "${{ matrix.python-version }}"
          # Required for the 3.15 rows: without it the version spec only
          # matches stable releases and the job fails with "Version 3.15 was
          # not found in the local cache".  It is safe to set for every row --
          # it widens `3.X` to `~3.X.0-0`, and a pre-release only wins when no
          # stable release satisfies the spec, so 3.10-3.14 still resolve to
          # their newest stable patch.
          allow-prereleases: true
          cache: "pip"
          cache-dependency-path: |
            requirements-docs.txt
            requirements-tests.txt
            requirements-typecheck.txt
            pyproject.toml

      - name: Install dependencies
        run: pip install -r requirements.txt

      # mypy is optional and refuses to run on PyPy.  Installing it here
      # is what makes tests/functional/test_typecheck.py run instead of
      # skip, so the type checks are exercised once per CPython version
      # rather than against a single interpreter.
      - name: Install type checker
        if: "!startsWith(matrix.python-version, 'pypy')"
        run: pip install -r requirements-typecheck.txt

      - name: Run linting checks
        run: scripts/lint.sh

      - name: Run tests
        run: scripts/tests.sh

      - name: Enforce coverage
        uses: codecov/codecov-action@v4
        with:
            token: ${{ secrets.CODECOV_TOKEN }}

  check:  # This job does nothing and is only used for the branch protection
    name: ✅ Ensure the required checks passing
    if: always()
    needs:
      - tests
    runs-on: ubuntu-latest
    steps:
    - name: Decide whether the needed jobs succeeded or failed
      uses: re-actors/alls-green@release/v1
      with:
        jobs: ${{ toJSON(needs) }}