publish-python.yml

# Build and publish the offbit-reflow Python SDK wheels.
#
# Triggers
# --------
# - Tag push matching `python-v*` (e.g. `python-v0.2.0`) → build every
#   wheel triple, run tests, then upload to PyPI.
# - Manual `workflow_dispatch` → build + test only (no publish).
#
# Publishing auth
# ---------------
# Uses an API token stored as the `PYPI_API_TOKEN` secret. After the
# first publish lands, flip this to PyPI trusted publishing (OIDC) by
# setting the `pypi` environment + `id-token: write` permission below
# and removing the MATURIN_PYPI_TOKEN env.

name: publish-python

on:
  push:
    tags:
      - 'python-v*'
  workflow_dispatch:

permissions:
  contents: read

jobs:
  linux:
    name: linux / ${{ matrix.platform.target }}
    runs-on: ${{ matrix.platform.runner }}
    strategy:
      fail-fast: false
      matrix:
        platform:
          - { runner: ubuntu-latest, target: x86_64 }
          - { runner: ubuntu-latest, target: aarch64 }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - name: Build wheels
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.platform.target }}
          # abi3-py39 yields one wheel per platform valid for Python >= 3.9.
          args: --release --out dist
          working-directory: sdk/python
          sccache: 'true'
          # Force manylinux_2_28 (gcc 12, glibc 2.28). The `auto` default
          # picks manylinux2014 whose aarch64 cross-toolchain predates
          # reliable <stdatomic.h> shipped from the cross-sysroot, which
          # quickjs requires. 2_28 is supported by every pip on Python
          # 3.9+ with a recent pip — good enough for our audience.
          manylinux: '2_28'
        env:
          PYO3_USE_ABI3_FORWARD_COMPATIBILITY: '1'
          # ring's pregenerated ARMv8 assembly requires __ARM_ARCH to
          # be defined. The cross-gcc doesn't pre-define it when invoked
          # through sccache, so we set it explicitly on the aarch64 leg.
          # `-march=armv8-a` would do it alone but `-D` is belt-and-braces.
          CFLAGS_aarch64_unknown_linux_gnu: '-march=armv8-a -D__ARM_ARCH=8'
      - uses: actions/upload-artifact@v4
        with:
          name: wheels-linux-${{ matrix.platform.target }}
          path: sdk/python/dist

  macos:
    name: macos / ${{ matrix.target }}
    runs-on: macos-14
    strategy:
      fail-fast: false
      matrix:
        target: [x86_64, aarch64]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - name: Build wheels
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.target }}
          # abi3-py39 yields one wheel per platform valid for Python >= 3.9.
          args: --release --out dist
          working-directory: sdk/python
          sccache: 'true'
        env:
          PYO3_USE_ABI3_FORWARD_COMPATIBILITY: '1'
      - uses: actions/upload-artifact@v4
        with:
          name: wheels-macos-${{ matrix.target }}
          path: sdk/python/dist

  windows:
    name: windows / ${{ matrix.target }}
    runs-on: windows-latest
    strategy:
      fail-fast: false
      matrix:
        target: [x64]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
          architecture: ${{ matrix.target }}
      - name: Build wheels
        uses: PyO3/maturin-action@v1
        with:
          target: ${{ matrix.target }}
          # abi3-py39 yields one wheel per platform valid for Python >= 3.9.
          args: --release --out dist
          working-directory: sdk/python
          sccache: 'true'
        env:
          PYO3_USE_ABI3_FORWARD_COMPATIBILITY: '1'
      - uses: actions/upload-artifact@v4
        with:
          name: wheels-windows-${{ matrix.target }}
          path: sdk/python/dist

  sdist:
    name: sdist
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build sdist
        uses: PyO3/maturin-action@v1
        with:
          command: sdist
          args: --out dist
          working-directory: sdk/python
      - uses: actions/upload-artifact@v4
        with:
          name: wheels-sdist
          path: sdk/python/dist

  # Smoke-test the built wheel in a clean venv on the current runner so a
  # broken wheel never reaches PyPI. Only tests the native wheel for each
  # host's architecture — cross-built aarch64 wheels are validated only
  # via `twine check`.
  test:
    name: test / ${{ matrix.os }}
    needs: [linux, macos, windows]
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-14, windows-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - name: Download wheels
        uses: actions/download-artifact@v4
        with:
          path: dist
          merge-multiple: true
      - name: Install wheel + run tests
        shell: bash
        run: |
          python -m pip install --upgrade pip pytest
          python -m pip install --find-links dist 'offbit-reflow'
          # Run from a tmpdir so pytest resolves `offbit_reflow` from
          # site-packages, not from the source directory (which only
          # carries the Python shim, not `_native.so`).
          cd "$RUNNER_TEMP"
          python -m pytest -q "$GITHUB_WORKSPACE/sdk/python/tests"

  publish:
    name: publish to PyPI
    runs-on: ubuntu-latest
    needs: [linux, macos, windows, sdist, test]
    if: startsWith(github.ref, 'refs/tags/python-v')
    # Once PyPI trusted publishing is configured for this repo, remove
    # the PYPI_API_TOKEN path and add:
    #   permissions: { id-token: write }
    #   environment: { name: pypi, url: https://pypi.org/p/offbit-reflow }
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: dist
          merge-multiple: true
      - name: Verify metadata
        run: |
          # twine >= 6.1 understands PEP 639's SPDX `license-expression`
          # field, which maturin emits from our `license = "MIT OR
          # Apache-2.0"` pyproject entry. Older twine flags it as
          # "unrecognized or malformed" and blocks the release.
          python -m pip install --upgrade pip 'twine>=6.1'
          python -m twine check dist/*
      - name: Publish to PyPI
        uses: PyO3/maturin-action@v1
        env:
          MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
        with:
          command: upload
          args: --non-interactive --skip-existing dist/*