python-package.yml

# Lint, type-check and test Picklock on every supported platform and Python.
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions

name: Python Package

on:
  # `push` restricted to `main` so feature branches only run via `pull_request`
  # — otherwise every push to a branch with an open PR runs the workflow twice.
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: '0 0 */7 * *'

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - name: Install lint deps
      run: |
        python -m pip install --upgrade pip
        pip install flake8
    - name: Lint
      run: flake8 picklock tests

  type-check:
    needs: lint
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - name: Install dev deps
      run: |
        python -m pip install --upgrade pip
        pip install -e ".[dev]"
    - name: Run mypy
      run: mypy picklock

  test:
    needs: lint
    # Picklock is a terminal program with three platform backends underneath it,
    # so the matrix is the whole point: the shell has to start and dispatch
    # identically on Windows (no readline), Linux and macOS.
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ['3.10', '3.11', '3.12', '3.13']
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install
      run: |
        python -m pip install --upgrade pip
        pip install -e ".[dev]"
    - name: Run tests
      # The whole suite, end-to-end tests included: those attach to the test
      # process itself, so they need no privileges and no second program, and
      # they skip themselves on a runner that refuses even that.
      #
      # --cov-fail-under is the real, in-repo coverage gate: deterministic and
      # independent of any external service. The suite measures ~89%; 80 is a
      # floor with room for per-platform variance (the three backends, and the
      # allocation commands that only exist on two of them).
      run: |
        pytest -q --cov=picklock --cov-report=term --cov-report=xml --cov-fail-under=80
    - name: Upload coverage to Codecov
      # Informational only — see codecov.yml — so a flaky upload never blocks
      # the merge; the hard gate is --cov-fail-under above. Runs even when the
      # tests fail so partial coverage stays visible.
      if: always()
      uses: codecov/codecov-action@v5
      with:
        files: ./coverage.xml
        flags: ${{ runner.os }}-py${{ matrix.python-version }}
        token: ${{ secrets.CODECOV_TOKEN }}
        fail_ci_if_error: false
    - name: Check the console script starts
      # The suite calls main() in-process; this proves the installed entry
      # point resolves and that a batch run exits cleanly. Both spellings of
      # the version are here: --version is answered by argparse before a shell
      # exists, 'version' by the shell's own dispatch, so one of them working
      # says nothing about the other.
      run: |
        picklock --version
        picklock -e "version"
        picklock -e "help scan"
        picklock ps:help
        picklock ps:list --limit 5

  # The docs import the package (conf.py generates the command reference from
  # the live registry), so a build here catches a broken page before Read the
  # Docs does — and catches a command whose help stops rendering.
  docs:
    needs: lint
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - name: Install docs deps
      run: |
        python -m pip install --upgrade pip
        pip install -r docs/requirements.txt
        pip install -e .
    - name: Build the docs
      run: sphinx-build -b html --fail-on-warning docs docs/_build/html

  build:
    needs: [type-check, test]
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - name: Build the distributions
      run: |
        python -m pip install --upgrade pip build twine
        python -m build
        twine check dist/*