python.yml

name: Python

on:
  pull_request:
    branches-ignore: [gh-pages]
    paths:
      - ".github/workflows/python.yml"
      - "python/**"
      - "!python/README.md"
      - 'c/Make*'
      - 'c/*.mk'
      - 'c/**/*.[ch]p?p?'
  push:
    branches: [main, 'v[0-9]+*' ]
    tags-ignore: ["**"]
    paths:
      - ".github/workflows/python.yml"
      - "python/**"
      - "!python/README.md"
      - 'c/Make*'
      - 'c/*.mk'
      - 'c/**/*.[ch]p?p?'
  release:
    types:
      - published
  # Manual run
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  type-check:
    timeout-minutes: 10
    if: "! contains(github.event.head_commit.message, '[skip ci]')"
    name: Type check
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.10
        uses: actions/setup-python@v6
        with:
          python-version: '3.10'
          cache: 'pip'

      - name: Install tox
        run: python3 -m pip install tox

      - name: Run ty
        run: tox -e type
        working-directory: python

  run-tests:
    timeout-minutes: 15
    if: "! contains(github.event.head_commit.message, '[skip ci]')"
    name: Test ${{ matrix.os }} (${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}
    strategy:
      # When set to true, GitHub cancels all in-progress jobs if any matrix job fails.
      fail-fast: false
      matrix:
        os: [ ubuntu-latest ]
        # Do not test macos-15, windows-latest or ubuntu-latest+3.10 because it
        # is already done when building the wheels.
        python-version: ['3.11', '3.12']
        cc: [ gcc ]
        include:
          - os: macos-15-intel
            python-version: '3.10'
            cc: clang

    env:
      CC: ${{ matrix.cc }}

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'

      - name: Install dependencies
        run: |
          python3 -m pip install --upgrade pip
          python3 -m pip install --upgrade build
          python3 -m pip install tox tox-gh-actions

      - name: Check that the package builds outside tox
        run: python3 -m build
        working-directory: python

      - name: Run tox
        run: tox
        working-directory: python

  build-doc:
    name: Build documentation
    needs: [run-tests, type-check]
    if: "! contains(github.event.head_commit.message, '[skip ci]')"
    permissions:
      contents: write
    concurrency: # Recommended if you intend to make multiple deployments in quick succession.
      group: web-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
    timeout-minutes: 10
    strategy:
      matrix:
        python-version: ['3.12']
        os: [ubuntu-latest]
    runs-on:  ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6

      - name: Setup Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'

      - name: Ensure Pip and Build
        run: |
          python3 -m pip install --upgrade pip
          python3 -m pip install --upgrade build

      - name: Build the package
        run: python3 -m build
        working-directory: python

        # This is needed for publishing to PyPI and useful for debugging.
      - name: Publish artifacts 📦
        uses: actions/upload-artifact@v6
        with:
          name: moocore-wheels-sdist-${{ matrix.os }}-${{ matrix.python-version }}
          path: python/dist/*.tar.gz

      - name: Install the package and the doc build requirements
        run: python3 -m pip install .[docs]
        working-directory: python

      - name: Cache intersphinx inventories
        uses: actions/cache@v5
        with:
          path: python/doc/_build/doctrees/__intersphinx_cache__/
          key: intersphinx-${{ hashFiles('python/doc/source/conf.py') }}
          restore-keys: intersphinx-

      - name: Build the docs 🔧
        run: |
          make -C doc html
        working-directory: python

      - name: Deploy 🚀
        if: success() && runner.os == 'Linux' && github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: python/doc/_build/html/ # The folder the action should deploy.
          target-folder: python
          single-commit: true
          clean: true

      - name: Stage PR preview
        if: github.event_name == 'pull_request'
        run: |
          mkdir -p preview
          cp -r python/doc/_build/html preview/site
          echo "${{ github.event.pull_request.number }}" > preview/pr-number

      - name: Upload PR preview
        if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v6
        with:
          name: docs-preview-python
          path: preview/
          retention-days: 3

  coverage:
    timeout-minutes: 15
    needs: build-doc
    if: "! contains(github.event.head_commit.message, '[skip ci]')"
    name: Coverage ${{ matrix.os }} (${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest]
        python-version: ['3.10']

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python3 -m pip install --upgrade pip
          python3 -m pip install tox tox-gh-actions
        working-directory: python

      - name: Run coverage using tox
        run: tox -e cov
        working-directory: python

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v6
        with:
          fail_ci_if_error: true
          files: python/coverage.xml,python/c_coverage.xml
          verbose: true
          flags: python
          plugins: noop
          disable_search: true
          token: ${{secrets.CODECOV_TOKEN}}

  wheels:
    name: 🎡 Build wheels on ${{ matrix.os }}
    needs: coverage
    runs-on: ${{ matrix.os }}
    if: "! contains(github.event.head_commit.message, '[skip ci]')"
    strategy:
      fail-fast: false
      matrix:
        # https://github.com/scipy/scipy/blob/6b79a4dec1f9ca2db4e49c328d04d293880991c6/.github/workflows/wheels.yml#L78
        # https://github.com/numpy/numpy-release/blob/main/.github/workflows/wheels.yml
        # macos-15 is arm64, macos-15-intel is x86_64. We build separate wheels
        # because they are smaller and testing is faster than building
        # universal2 wheels.
        os: [ubuntu-22.04, ubuntu-22.04-arm, windows-2025, macos-15, macos-15-intel, windows-11-arm]

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python 3.11 for Windows ARM64
        if: ${{ matrix.os == 'windows-11-arm' }}
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'
          cache: 'pip'

        # FIXME: This step installs clang-cl but cibuildwheel does not use it.
      - name: Setup LLVM for Windows ARM64 (NOT WORKING/FIXME)
        if: false # ${{ matrix.os == 'windows-11-arm' }}
        uses: ./.github/windows_arm64_steps

        # The configuration of cibuildwheel can be found in pyproject.toml
      - name: Build wheels
        uses: pypa/cibuildwheel@v4.3.1
        with:
          package-dir: python
          output-dir: wheelhouse

      - name: List wheels
        run: ls wheelhouse/*.whl

      - uses: actions/upload-artifact@v6
        with:
          name: moocore-wheels-${{ matrix.os }}-${{ strategy.job-index }}
          path: wheelhouse/*.whl

  upload_pypi:
    name: Publish Python 🐍 distribution 📦 to PyPI
    needs: [wheels, build-doc]
    runs-on: ubuntu-latest
    environment:
      name: pypi
      url: https://pypi.org/p/moocore
    permissions:
      id-token: write
    if: ${{ github.event_name == 'release' && github.event.action == 'published' && startsWith(github.ref, 'refs/tags/v') }}
    # or, alternatively, upload to PyPI on every tag starting with 'v' (remove on: release above to use this)
    # if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
    steps:
      - uses: actions/download-artifact@v8
        with:
          # unpacks all moocore artifacts into dist/
          pattern: moocore-wheels-*
          path: dist
          merge-multiple: true

      - name: Display structure of downloaded files
        run: ls -R dist

      - uses: pypa/gh-action-pypi-publish@release/v1
        with:
          verbose: true
        # To test: repository-url: https://test.pypi.org/legacy/

  upload:
    name: Store wheels
    needs: wheels
    if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v6

      - uses: actions/download-artifact@v8
        with:
          path: wheelhouse
          pattern: moocore-wheels-*
          merge-multiple: true

      - name: List wheels
        run: ls -l wheelhouse/*.whl

      - name: Upload wheels
        if: success() && runner.os == 'Linux' && github.event_name == 'push'
        run: |
          git config --local user.email "actions@github.com"
          git config --local user.name "GitHub Actions"
          git checkout --orphan new-wheels
          git rm -rf .
          mv wheelhouse/*.whl .
          git add *.whl
          git commit --allow-empty -m "Store Python wheels from @ $GITHUB_SHA"
          git branch -D wheels
          git branch -m wheels
          git push --force origin wheels
        shell: bash {0}