python.yml

name: Python

on:
  push:
    branches: [main]
    tags: ["*"]
  pull_request:
    branches: [main]

permissions:
  contents: read

env:
  PYTHONUNBUFFERED: 1

jobs:
  pre-commit:
    name: Rerun pre-commit checks
    runs-on: ubuntu-slim
    outputs:
      dist-base: ${{ steps.paths.outputs.dist }}
      docs-base: ${{ steps.paths.outputs.docs }}
    steps:
    - name: Check out repo
      uses: actions/checkout@v7
    - name: Set up Python
      uses: actions/setup-python@v7
      with:
        python-version: '3.15'
    - name: Install dependencies
      run: python -m pip install prek uv
    - name: Cache pre-commit environments
      uses: actions/cache@v6
      with:
        path: ~/.cache/prek
        key: prek|${{ env.pythonLocation }}|${{ hashFiles('.pre-commit-config.yaml') }}
    - name: Run pre-commit hooks
      run: prek run -a --show-diff-on-failure --color=always
    - name: Define artifact paths
      id: paths
      run: |
        suffix="$GITHUB_RUN_NUMBER-$(echo $GITHUB_SHA | cut -c-10)"
        echo "dist=openslide-python-dist-$suffix" >> $GITHUB_OUTPUT
        echo "docs=openslide-python-docs-$suffix" >> $GITHUB_OUTPUT

  tests:
    name: Tests
    needs: pre-commit
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest]
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.13t", "3.14", "3.14t", "3.15", "3.15t"]
        openslide: [system, wheel]
        include:
          - os: ubuntu-latest
            python-version: "3.15"
            openslide: system
            sdist: sdist
    steps:
    - name: Check out repo
      uses: actions/checkout@v7
    - name: Set up Python ${{ matrix.python-version }}
      if: matrix.upstream-python == null
      uses: actions/setup-python@v7
      with:
        python-version: ${{ matrix.python-version }}
    - name: Set up Python ${{ matrix.python-version }} (macOS fallback)
      if: matrix.upstream-python != null
      run: |
        pkgdir="${{ runner.temp }}/python"
        mkdir -p "$pkgdir/bin"
        pkg="$pkgdir/python.pkg"
        curl -Lfo "$pkg" \
            "https://www.python.org/ftp/python/${{ matrix.upstream-python }}/python-${{ matrix.upstream-python }}-macos11.pkg"
        sudo installer -pkg "$pkg" -target /
        for bin in python pip; do
            ln -s /usr/local/bin/${bin}3 $pkgdir/bin/${bin}
        done
        export PATH="$pkgdir/bin:$PATH"
        echo "PATH=$PATH" >> $GITHUB_ENV
        python -V
        pip -V
    - name: Install Python tools
      run: |
        python -m pip install --upgrade pip
        pip install auditwheel build jinja2 pytest
        if [ "${{ matrix.python-version }}" = 3.13t ]; then
            # newer versions drop 3.13t wheels
            pip install pillow==12.2.0
        fi
    - name: Install OpenSlide (system)
      if: matrix.openslide == 'system'
      run: |
        case "${{ matrix.os }}" in
        ubuntu-latest)
          echo OS_ARCH_TAG=linux-x86_64 >> $GITHUB_ENV
          sudo apt-get install libopenslide0
          ;;
        ubuntu-24.04-arm)
          echo OS_ARCH_TAG=linux-aarch64 >> $GITHUB_ENV
          sudo apt-get install libopenslide0
          ;;
        macos-latest)
          echo OS_ARCH_TAG=macos-arm64-x86_64 >> $GITHUB_ENV
          echo DYLD_LIBRARY_PATH=/opt/homebrew/lib >> $GITHUB_ENV
          brew install openslide
          ;;
        esac
    - name: Install OpenSlide (wheel)
      if: matrix.openslide == 'wheel'
      run: pip install openslide-bin
    - name: Build dist
      run: |
        if [ -z "${{ matrix.sdist }}" ]; then
            wheel_only=-w
        fi
        python -m build $wheel_only
        case "${{ matrix.os }}" in
        ubuntu-*)
            mkdir old
            mv dist/*.whl old/
            auditwheel repair --only-plat -w dist old/*whl
            ;;
        macos-*)
            if [ ! -e dist/*universal2* ]; then
                echo "Wheel is not universal:"
                ls dist
                exit 1
            fi
        esac
        if [ -z "$wheel_only" ]; then
            mkdir -p "artifacts/src/${{ needs.pre-commit.outputs.dist-base }}"
            mv dist/*.tar.gz "artifacts/src/${{ needs.pre-commit.outputs.dist-base }}"
        fi
        mkdir -p "artifacts/whl/${{ needs.pre-commit.outputs.dist-base }}"
        mv dist/* "artifacts/whl/${{ needs.pre-commit.outputs.dist-base }}"
        # from system builds, save version-specific wheels and oldest abi3 wheel
        python -c 'import sys, sysconfig
        if "${{ matrix.openslide }}" == "system" and (sys.version_info < (3, 12) or sysconfig.get_config_var("Py_GIL_DISABLED")):
            print("archive_wheel=1")' >> $GITHUB_ENV
    - name: Install
      run: pip install artifacts/whl/${{ needs.pre-commit.outputs.dist-base }}/*.whl
    - name: Run tests
      run: pytest -v
    - name: Tile slide
      run: python examples/deepzoom/deepzoom_tile.py --viewer -o tiled tests/fixtures/small.svs
    - name: Archive sdist
      if: matrix.sdist
      uses: actions/upload-artifact@v7
      with:
        name: ${{ needs.pre-commit.outputs.dist-base }}-source
        path: artifacts/src
        compression-level: 0
    - name: Archive wheel
      if: env.archive_wheel
      uses: actions/upload-artifact@v7
      with:
        name: ${{ needs.pre-commit.outputs.dist-base }}-${{ env.OS_ARCH_TAG }}-${{ matrix.python-version }}
        path: artifacts/whl
        compression-level: 0

  windows:
    name: Windows
    needs: pre-commit
    runs-on: windows-latest
    defaults:
      run:
        shell: bash
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.13t", "3.14", "3.14t", "3.15", "3.15t"]
        openslide: [zip, wheel]
    steps:
    - name: Check out repo
      uses: actions/checkout@v7
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v7
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install Python tools
      run: |
        python -m pip install --upgrade pip
        pip install build flask pytest
        if [ "${{ matrix.python-version }}" = 3.13t ]; then
            # newer versions drop 3.13t wheels
            pip install pillow==12.2.0
        fi
    - name: Install OpenSlide (zip)
      if: matrix.openslide == 'zip'
      env:
        GH_TOKEN: ${{ github.token }}
      run: |
        mkdir -p c:\\openslide
        cd c:\\openslide
        release=$(gh release list -R openslide/openslide-bin -L 1 \
            --json tagName --exclude-drafts --exclude-pre-releases | \
            jq -r .[0].tagName | \
            tr -d v)
        zipname="openslide-bin-${release}-windows-x64"
        gh release download -R openslide/openslide-bin "v${release}" \
            --pattern "${zipname}.zip"
        7z x ${zipname}.zip
        echo "OPENSLIDE_PATH=c:\\openslide\\${zipname}\\bin" >> $GITHUB_ENV
    - name: Install OpenSlide (wheel)
      if: matrix.openslide == 'wheel'
      run: pip install openslide-bin
    - name: Build wheel
      run: |
        python -m build -w
        mkdir -p "artifacts/whl/${{ needs.pre-commit.outputs.dist-base }}"
        mv dist/*.whl "artifacts/whl/${{ needs.pre-commit.outputs.dist-base }}"
        # from zip builds, save version-specific wheels and oldest abi3 wheel
        python -c 'import sys, sysconfig
        if "${{ matrix.openslide }}" == "zip" and (sys.version_info < (3, 12) or sysconfig.get_config_var("Py_GIL_DISABLED")):
            print("archive_wheel=1")' >> $GITHUB_ENV
    - name: Install
      run: pip install artifacts/whl/${{ needs.pre-commit.outputs.dist-base }}/*.whl
    - name: Run tests
      # Reads OPENSLIDE_PATH
      run: pytest -v
    - name: Test library loading in examples
      # Reads OPENSLIDE_PATH
      run: |
        python examples/deepzoom/deepzoom_multiserver.py -h >/dev/null
        python examples/deepzoom/deepzoom_server.py -h >/dev/null
        python examples/deepzoom/deepzoom_tile.py -h >/dev/null
    - name: Tile slide
      # Reads OPENSLIDE_PATH
      run: python examples/deepzoom/deepzoom_tile.py --viewer -o tiled tests/fixtures/small.svs
    - name: Archive wheel
      if: env.archive_wheel
      uses: actions/upload-artifact@v7
      with:
        name: ${{ needs.pre-commit.outputs.dist-base }}-windows-x64-${{ matrix.python-version }}
        path: artifacts/whl
        compression-level: 0

  setuptools:
    name: Setuptools install
    needs: pre-commit
    runs-on: ubuntu-latest
    container: ubuntu:22.04
    steps:
    - name: Install dependencies
      run: |
        apt-get update
        DEBIAN_FRONTEND=noninteractive apt-get install -y \
            git libopenslide0 python3-jinja2 python3-pil python3-pip
        pip install pytest
    - name: Check out repo
      uses: actions/checkout@v7
    - name: Install OpenSlide Python
      run: python3 setup.py install
    - name: Run tests
      run: pytest -v
    - name: Tile slide
      run: python3 examples/deepzoom/deepzoom_tile.py --viewer -o tiled tests/fixtures/small.svs

  docs:
    name: Docs
    needs: pre-commit
    runs-on: ubuntu-slim
    steps:
    - name: Check out repo
      uses: actions/checkout@v7
    - name: Set up Python
      uses: actions/setup-python@v7
      with:
        python-version: '3.15'
    - name: Install Python tools
      run: |
        python -m pip install --upgrade pip
        pip install sphinx
    - name: Build
      run: sphinx-build -d doctrees doc artifact/${{ needs.pre-commit.outputs.docs-base }}
    - name: Archive
      uses: actions/upload-artifact@v7
      with:
        name: ${{ needs.pre-commit.outputs.docs-base }}
        path: artifact

  release:
    name: Release
    if: github.ref_type == 'tag'
    environment:
      name: pypi
      url: https://pypi.org/p/openslide-python
    needs: [pre-commit, tests, windows]
    runs-on: ubuntu-latest
    concurrency: release-${{ github.ref }}
    permissions:
      contents: write
      id-token: write
    steps:
    - name: Download artifacts
      uses: actions/download-artifact@v8
      with:
        pattern: "${{ needs.pre-commit.outputs.dist-base }}-*"
        merge-multiple: true
    - name: Release to PyPI
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        packages-dir: ${{ needs.pre-commit.outputs.dist-base }}
        repository-url: ${{ vars.PYPI_URL }}
    - name: Release to GitHub
      env:
        GITHUB_TOKEN: ${{ github.token }}
      run: |
        version=$(echo "${{ github.ref_name }}" | sed "s/^v//")
        # recompress tarball with xz
        gunzip -k "${{ needs.pre-commit.outputs.dist-base }}/openslide_python-${version}.tar.gz"
        tar xf "${{ needs.pre-commit.outputs.dist-base }}/openslide_python-${version}.tar"
        xz -9 "${{ needs.pre-commit.outputs.dist-base }}/openslide_python-${version}.tar"
        # extract changelog
        awk -e '/^## / && ok {exit}' \
            -e '/^## / {ok=1; next}' \
            -e 'ok {print}' \
            "openslide_python-$version/CHANGELOG.md" > changes
        # create release; upload artifacts but not *.publish.attestation
        # files created by gh-action-pypi-publish
        gh release create --latest --verify-tag \
            --repo "${{ github.repository }}" \
            --title "OpenSlide Python $version" \
            --notes-file changes \
            "${{ github.ref_name }}" \
            "${{ needs.pre-commit.outputs.dist-base }}/"*.{tar.gz,tar.xz,whl}