python-ci.yml

# Reusable workflow to run the python CI, which covers
# Optional notificiation to notehub (requires secrets NOTEHUB_SESSION_TOKEN, NOTEHUB_DEVICE_ID and NOTEHUB_PRODUCT_UID)
# Python installation and dependencies
# Linting (flake8 and docstyle)
# Testing and coverage with pytest
# Optionally publish coverage to coveralls (requires secrets.GITHUB_TOKEN)

on:
    workflow_call:
        secrets:
            NOTEHUB_SESSION_TOKEN:
            NOTEHUB_PRODUCT_UID:
            NOTECARD_DEVICE_ID:
        inputs:
            coveralls:
                type: boolean
                required: false
                default: false
            notehub_notify:
                type: boolean
                required: false
                default: false

permissions:
    contents: read

jobs:
    build:
      runs-on: ubuntu-24.04
      timeout-minutes: 15
      strategy:
        matrix:
          python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']

      steps:
      - name: Send building notification
        if: ${{ inputs.notehub_notify }}
        run: |
          curl --request POST \
          --url 'https://api.notefile.net/?product=${{ secrets.NOTEHUB_PRODUCT_UID }}&device=${{ secrets.NOTECARD_DEVICE_ID }}' \
          --header 'Content-Type: application/json' \
          --header 'X-Session-Token: ${{ secrets.NOTEHUB_SESSION_TOKEN }}' \
          --data '{"req":"note.add","file":"build_results.qi","body":{"result":"building"}}'
      - uses: actions/checkout@v7
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pipenv'
      - name: Install pipenv
        run: |
          python -m pip install --upgrade pip
          pip install pipenv
      - name: Install dependencies
        run: |
          pipenv install --dev --python "$(which python)"
      - name: Lint with flake8
        run: |
          pipenv run make flake8
      - name: Lint Docs with Pydocstyle
        run: |
          pipenv run make docstyle
      - name: Send running tests notification
        if: ${{ inputs.notehub_notify }}
        run: |
          curl --request POST \
          --url 'https://api.notefile.net/?product=${{ secrets.NOTEHUB_PRODUCT_UID }}&device=${{ secrets.NOTECARD_DEVICE_ID }}' \
          --header 'Content-Type: application/json' \
          --header 'X-Session-Token: ${{ secrets.NOTEHUB_SESSION_TOKEN }}' \
          --data '{"req":"note.add","file":"build_results.qi","body":{"result":"running_tests"}}'

      - name: Test with pytest
        run: |
          pipenv run coverage run -m pytest
      # One leg only. `coveralls --service=github` derives its job id from
      # GITHUB_RUN_ID, which is identical across the matrix, so five legs submit
      # as the same job for the same commit and Coveralls 422s all but one --
      # intermittently failing the build (PR #185). Coverage is the same on every
      # version, so publishing from one is no loss.
      - name: Publish to Coveralls
        env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        if: ${{ inputs.coveralls && matrix.python-version == '3.12' }}
        run: |
          pipenv run coveralls --service=github

      - name: Check if the job has succeeded
        if: ${{ success() && inputs.notehub_notify }}
        run: |
          curl --request POST \
          --url 'https://api.notefile.net/?product=${{ secrets.NOTEHUB_PRODUCT_UID }}&device=${{ secrets.NOTECARD_DEVICE_ID }}' \
          --header 'Content-Type: application/json' \
          --header 'X-Session-Token: ${{ secrets.NOTEHUB_SESSION_TOKEN }}' \
          --data '{"req":"note.add","file":"build_results.qi","body":{"result":"success"}}'
      - name: Check if the job has failed
        if: ${{ failure() && inputs.notehub_notify }}
        run: |
          curl --request POST \
          --url 'https://api.notefile.net/?product=${{ secrets.NOTEHUB_PRODUCT_UID }}&device=${{ secrets.NOTECARD_DEVICE_ID }}' \
          --header 'Content-Type: application/json' \
          --header 'X-Session-Token: ${{ secrets.NOTEHUB_SESSION_TOKEN }}' \
          --data '{"req":"note.add","file":"build_results.qi","body":{"result":"tests_failed"}}'

    # Branch protection requires `build / ci-gate` instead of the five
    # `build / build (3.xx)` contexts, which are matched by name and would go
    # stale whenever the matrix changes. `if: always()` is required -- a skipped
    # check reports as successful.
    ci-gate:
      needs: build
      if: always()
      runs-on: ubuntu-24.04
      timeout-minutes: 5
      permissions: {}
      steps:
      - name: Require the full matrix to have succeeded
        run: |
          echo "build result: ${{ needs.build.result }}"
          [ "${{ needs.build.result }}" = "success" ] || exit 1