python-package.yml

# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions

name: Python package

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      name:
        description: 'Reason'
        required: false
        default: 'Just Cause'

permissions:
  contents: read

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.filter.outputs.python }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          persist-credentials: false
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d  # v4.0.1
        id: filter
        with:
          filters: |
            python:
              - '**/*.py'
              - 'requirements*.txt'
              - 'pyproject.toml'
              - 'viewer/**'
              - 'ingest/**'
              - 'pnpm-lock.yaml'
              - '.github/workflows/python-package.yml'

  build:
    needs: changes
    if: needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - lib: 'astropy'
            python-version: "3.14"
          - lib: 'papyri'
            python-version: "3.14"
          - lib: 'IPython'
            python-version: "3.14"
            flags: '--no-narrative'
          - lib: 'numpy'
            python-version: "3.14"
            flags: '--no-narrative --no-exec'
          - lib: 'scipy'
            python-version: "3.14"
            flags: '--no-narrative --no-exec --no-infer'

    steps:
    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
      with:
        persist-credentials: false
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install uv
      run: pip install uv
    - name: Install dependencies
      run: |
        uv pip install --system -r requirements-dev.txt
        uv pip install --system -e .
    - name: dependency tree
      run: |
        pipdeptree
    - name: dependency tree (reversed)
      run: |
        pipdeptree -r
    - name: Gen ${{matrix.lib}}
      run: |
        rm -rf ~/.papyri/data/*
        if [ "${{ matrix.lib }}" != "papyri" ]; then
          uv pip install --system "${{ matrix.lib }}"
        fi
        coverage run -a -m papyri gen examples/${{matrix.lib}}.toml ${{matrix.flags}}
        sleep 1 # time for coverage to write its stuff
        papyri pack
        tree ~/.papyri/data
    - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
      with:
        name: doc-bundles-${{matrix.lib}}
        path: ~/.papyri/data/*.papyri
    - name: Convert .coverage sql to xml for upload
      run: |
        coverage report
        coverage xml
        ls -la
    - name: "Upload coverage to Codecov"
      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2  # v6.0.0
      with:
        fail_ci_if_error: false
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: gen
        name: gen-${{ matrix.lib }}
        files: ./coverage.xml
  gen-ipython-main:
    # Extended gen test: clone IPython main into ~/dev/IPython so the default
    # docs_path in examples/IPython.toml (~/dev/IPython/docs/source) resolves,
    # then run `papyri gen` with narrative enabled against main-branch sources.
    # The `build` matrix above exercises the pip-installed release of IPython
    # without narrative; this job complements it.
    needs: changes
    if: needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.14"]
    steps:
    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
      with:
        persist-credentials: false
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install uv
      run: pip install uv
    - name: Install dependencies
      run: |
        uv pip install --system -r requirements-dev.txt
        uv pip install --system -e .
    - name: Clone IPython main
      run: |
        mkdir -p ~/dev
        git clone --depth=1 https://github.com/ipython/ipython.git ~/dev/IPython
    - name: Install IPython from main
      run: |
        uv pip install --system -e ~/dev/IPython
    - name: Gen IPython (main branch, with narrative)
      run: |
        coverage run -a -m papyri gen examples/IPython.toml
        sleep 1 # time for coverage to write its stuff
        papyri pack
        ls ~/.papyri/data
    - name: Verify narrative docs were collected
      run: |
        set -e
        # Pick the first IPython gen bundle via shell glob (shellcheck SC2012).
        shopt -s nullglob
        bundles=(~/.papyri/data/IPython_*/)
        if [ ${#bundles[@]} -eq 0 ]; then
          echo "no IPython_* bundle under ~/.papyri/data" >&2
          exit 1
        fi
        bundle="${bundles[0]}"
        echo "Bundle: $bundle"
        test -d "$bundle/docs" || { echo "docs/ missing"; exit 1; }
        test -f "$bundle/toc.json" || { echo "toc.json missing"; exit 1; }
        n=$(find "$bundle/docs" -type f | wc -l)
        echo "Narrative doc count: $n"
        test "$n" -gt 5 || { echo "expected >5 narrative docs, got $n"; exit 1; }
    - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
      with:
        name: doc-bundles-IPython-main
        path: ~/.papyri/data/*.papyri
    - name: Convert .coverage sql to xml for upload
      run: |
        coverage report
        coverage xml
    - name: "Upload coverage to Codecov"
      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2  # v6.0.0
      with:
        fail_ci_if_error: false
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: gen
        name: gen-IPython-main
        files: ./coverage.xml

  test:
    needs: changes
    if: needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.14"]
    steps:
    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
      with:
        persist-credentials: false
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install uv
      run: pip install uv
    - name: Install dependencies
      run: |
        uv pip install --system -r requirements-dev.txt
        uv pip install --system -e .
        uv pip install --system scipy dask
    - name: Test with pytest
      run: |
        pytest --cov=papyri --cov-append
    - name: Convert .coverage sql to xml for upload
      run: |
        coverage report
        coverage xml
    - name: "Upload coverage to Codecov"
      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2  # v6.0.0
      with:
        fail_ci_if_error: false
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: test
        name: pytest
        files: ./coverage.xml

  upload-verify:

    runs-on: ubuntu-latest
    needs: [changes, build]
    if: needs.changes.outputs.python == 'true' || github.event_name == 'workflow_dispatch'
    strategy:
      matrix:
        python-version: ["3.14"]
    steps:
    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
      with:
        persist-credentials: false
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install uv
      run: pip install uv
    - name: Install dependencies
      run: |
        uv pip install --system -r requirements-dev.txt
        uv pip install --system -e .
    - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093  # v6.0.8
      with:
        version: 10
    - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
      with:
        node-version: 22
        cache: pnpm
        cache-dependency-path: pnpm-lock.yaml
    - name: Install viewer deps and build
      run: |
        pnpm install --frozen-lockfile
        pnpm --filter papyri-viewer run build
    - name: Start viewer server
      run: |
        node viewer/dist/server/entry.mjs &
        for i in $(seq 1 30); do
          if curl -sf http://localhost:4321/api/bundles.json > /dev/null 2>&1; then
            echo "Viewer ready after ${i}s"
            break
          fi
          echo "Waiting for viewer... ($i)"
          sleep 1
        done
        curl -sf http://localhost:4321/api/bundles.json
    - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
      with:
        pattern: doc-bundles-*
        path: ~/.papyri/data/
        merge-multiple: true

    - name: Misc cli
      run: |
        coverage run -a -m papyri --help
        ls -al
    - name: Upload bundles to viewer
      run: |
        shopt -s nullglob
        artifacts=(~/.papyri/data/*.papyri)
        if [ ${#artifacts[@]} -gt 0 ]; then
          coverage run -a -m papyri upload "${artifacts[@]}"
        fi
    - name: Verify bundles via viewer API
      run: |
        response=$(curl -sf http://localhost:4321/api/bundles.json)
        echo "Bundles API response: $response"
        count=$(jq '.bundles | length' <<<"$response")
        if [ "$count" -lt 1 ]; then
          echo "Expected at least one ingested bundle, got $count" >&2
          exit 1
        fi
        jq -r '.bundles[] | "  ingested: \(.pkg) \(.version)"' <<<"$response"
        echo "Total bundles ingested: $count"
    - name: Post-upload ingest tests (TypeScript)
      run: |
        pnpm --filter papyri-ingest run test

    - name: Convert .coverage sql to xml for upload
      run: |
        coverage report
        coverage xml
        ls -la
    - name: "Upload coverage to Codecov"
      uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2  # v6.0.0
      with:
        fail_ci_if_error: false
        token: ${{ secrets.CODECOV_TOKEN }}
        flags: ingest
        name: upload-verify
        files: ./coverage.xml