publish.yml

name: Publish (PyPI)

# Publishes any tag starting with 'v' (e.g. v1.0, v0.5.1a0) to PyPI via OIDC
# trusted publishing. The publish job is gated on the full pytest matrix AND
# the strict Sphinx build passing on the tagged commit — we don't ship a
# release that fails CI or has broken docs.
on:
  push:
    tags:
      - v*

permissions: {}

jobs:
  # Re-run the full test matrix on the tagged commit. Yes, this is similar
  # to tests.yaml — but a release deserves an explicit, self-contained gate
  # rather than a `workflow_run` dependency on another workflow's run (which
  # would only work if tests.yaml was on the default branch at the time of
  # the tag, a footgun).
  tests:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    strategy:
      fail-fast: true
      matrix:
        python-version: [ "3.12", "3.13", "3.14" ]
    name: pytest (Python ${{ matrix.python-version }})
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Install uv
        uses: astral-sh/setup-uv@v6

      - name: Install Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}

      - name: Install dependencies
        run: uv sync --all-extras --python ${{ matrix.python-version }}

      - name: Run pytest
        run: |
          uv run --python ${{ matrix.python-version }} pytest -v -m "not network"

  # Strict Sphinx build — same gate `tests.yaml` runs on every dev push.
  # A release deserves the same docstring/signature drift check.
  docs:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Install uv
        uses: astral-sh/setup-uv@v6

      - name: Install Python 3.13
        run: uv python install 3.13

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Build Sphinx + Furo site (strict)
        run: uv run sphinx-build -W --keep-going -b html docs/source docs/build/sphinx

  publish:
    needs: [tests, docs]
    runs-on: ubuntu-latest
    environment:
      name: publish
    permissions:
      id-token: write   # OIDC trusted publishing
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Install uv
        uses: astral-sh/setup-uv@v6

      - name: Install Python 3.13
        run: uv python install 3.13

      - name: Build
        run: uv build

      - name: Publish to PyPI
        run: uv publish