python-package.yml

name: Build, Test & Coverage

# Trigger the workflow on push or pull request events for the main branch
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build-and-test:
    name: Test (Python ${{ matrix.python-version }})
    runs-on: ubuntu-latest

    # Test against multiple Python versions to ensure compatibility
    strategy:
      fail-fast: false  # If one version fails, let others finish (useful for debugging)
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12"]

    steps:
    # 1. Check out the repository code
    - uses: actions/checkout@v4

    # 2. Set up the Python environment based on the matrix
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
        cache: 'pip' # Cache pip to speed up subsequent runs

    # 3. Install the package and test dependencies
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        # Install test dependencies (flake8, pytest, etc.)
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
        # Install the package itself in editable mode
        pip install -e . 
        # Or if you have optional deps: pip install -e ".[dataframes]"

    # 4. Linting: Check for syntax errors and coding style violations
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zero treats all errors as warnings (except syntax errors)
        # We ignore E501 (line length) as modern screens are wide
        flake8 . --count --ignore=E501 --max-complexity=10 --statistics

    # 5. Testing: Run unit tests and generate coverage report
    - name: Test with pytest
      run: |
        # Generates an XML report required by Codecov
        pytest --cov=src/keyedstablehash --cov-report=term --cov-report=xml

    # 6. Upload Coverage: Send report to Codecov.io
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v5
      with:
        token: ${{ secrets.KEYEDSTABLEHASH_CODECOV_TOKEN }}