PyHC GitHub Actions

Reusable GitHub Actions for Python in Heliophysics Community (PyHC) package compliance checking.

Actions

1. PHEP 3 Compliance Checker

Validates package requirements against PHEP 3:

• Python versions supported for 36 months after release
• Core Scientific Python packages (numpy, scipy, matplotlib, pandas, scikit-image, networkx, scikit-learn, xarray, ipython, zarr) supported for 24 months after release
• New versions adopted within 6 months of release
• Warnings on max/exact constraints (e.g., numpy<2, scipy==1.10)

Violations in the base install fail the check. Violations found only in extras are reported as warnings.

Usage

name: PHEP 3 Compliance
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: heliophysicsPy/pyhc-actions/phep3-compliance@v1

Inputs

Input	Description	Default
project-file	Path to pyproject.toml	pyproject.toml
fail-on-warning	Treat warnings as errors	false
check-adoption	Check 6-month adoption rule	true
schedule-path	Path to schedule.json	(auto-download)
use-uv-fallback	Use uv metadata extraction for projects with non-PEP 621 metadata (including setup.py/setup.cfg)	true
ignore-errors-for	Comma-separated package names whose errors should be reported as warnings	""

Outputs

Output	Description
passed	Whether the check passed
errors	Number of errors found (not populated yet)
warnings	Number of warnings found (not populated yet)

Example Output

PHEP 3 Compliance Check
========================

ERRORS:
[ERROR] requires-python = ">=3.13" drops support for Python 3.12 too early
        Python 3.12 must still be supported per PHEP 3
        Suggested: Change to requires-python = ">=3.12"

[ERROR] numpy<2 does not support required version 2.0
        Version 2.0 must be supported within 6 months of release
        Suggested: Update upper bound to include 2.0

WARNINGS:
[WARN] numpy<2 has upper bound constraint
        Upper bounds should only be used when absolutely necessary
        Suggested: Consider removing <2 unless required

[WARN] scipy==1.10 has exact version constraint
        Exact constraints should only be used when absolutely necessary
        Suggested: Remove exact constraint and use >= instead

Summary: 2 error(s), 2 warning(s)
Status: FAILED

2. PyHC Environment Compatibility Checker

Detects dependency conflicts with the PyHC Environment.

Conflicts in the base install fail the check. Conflicts found only in extras are reported as warnings.

Uses uv for fast, accurate dependency resolution that catches transitive conflicts.

Usage

name: PyHC Compatibility
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: heliophysicsPy/pyhc-actions/pyhc-env-compat@v1

Inputs

Input	Description	Default
project-file	Path to pyproject.toml	pyproject.toml
pyhc-packages-url	URL to PyHC packages.txt	(official GitHub URL)
pyhc-constraints-url	URL to PyHC constraints.txt	(official GitHub URL)
extras	Extras selection: auto, none, or comma-separated list	auto

Outputs

Output	Description
compatible	Whether the package is compatible
conflicts	Number of conflicts found (only set on success)

Example Output

PyHC Environment Compatibility Check
=====================================

ERRORS:
[ERROR] Dependency conflict: numpy
        Your requirement: numpy<2.0
        PyHC Environment: numpy>=2.0,<2.3.0
        Incompatible version requirements
        Suggested: Support numpy>=2.0,<2.3.0

Summary: 1 error(s), 0 warning(s)
Status: FAILED

Using the Actions

Example Workflow

To use the actions, you can copy the YAML below and paste it into .github/workflows/pyhc-actions.yml. Tip: You may want to limit push/PR triggers to packaging file changes by adding a paths: filter (e.g. pyproject.toml, setup.py, and the workflow file itself).

name: PyHC Actions

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Run quarterly: Jan 1, Apr 1, Jul 1, Oct 1 at 3pm UTC (8am MST)
    - cron: 0 15 1 1,4,7,10 *
  workflow_dispatch:

jobs:
  phep3-compliance:
    name: PHEP 3 Compliance
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check PHEP 3 Compliance
        uses: heliophysicsPy/pyhc-actions/phep3-compliance@v1

  pyhc-env-compat:
    name: PyHC Environment Compatibility
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check PyHC Environment Compatibility
        uses: heliophysicsPy/pyhc-actions/pyhc-env-compat@v1

Local Usage

You can also run the checks locally:

# Install
pip install -e .

# Run PHEP 3 check
phep3-check pyproject.toml

# Run PHEP 3 check for projects with non-PEP 621 metadata (including setup.py/setup.cfg and Poetry)
phep3-check path/to/project

# Disable uv fallback
phep3-check --no-uv-fallback pyproject.toml

# Downgrade errors to warnings for specific packages
phep3-check --ignore-errors-for xarray pyproject.toml

# Run PyHC Environment compatibility check (requires uv)
pyhc-env-compat-check pyproject.toml

# Run PyHC Environment compatibility check with extras
pyhc-env-compat-check --extras auto pyproject.toml
pyhc-env-compat-check --extras none pyproject.toml
pyhc-env-compat-check --extras mth5,vires pyproject.toml

# Use local packages/constraints files or alternate URLs
pyhc-env-compat-check --packages ./packages.txt pyproject.toml
pyhc-env-compat-check --constraints ./constraints.txt pyproject.toml

# Only check that uv is installed
pyhc-env-compat-check --check-uv

# Generate fresh schedule.json
phep3-check --generate-schedule

Development

# Clone repository
git clone https://github.com/heliophysicsPy/pyhc-actions.git
cd pyhc-actions

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

Releases and Tagging

This repository follows the standard GitHub Actions versioning pattern with major version tags:

• Specific version tags (v1.0.0, v1.0.1, v1.1.0, etc.) - Immutable releases
• Major version tag (v1) - Floating tag that points to the latest v1.x.x release

For Maintainers: Creating a New Release

When releasing a new version:

# Create and push the specific version tag
git tag v1.0.1
git push origin v1.0.1

# Update the major version tag to point to the new release
git tag -f v1 v1.0.1
git push -f origin v1

# Create the GitHub release
gh release create v1.0.1 --title "v1.0.1" --notes "Release notes here"

Why Both Tags?

• Users reference @v1 in their workflows to automatically get the latest v1.x.x updates
• The floating v1 tag must be manually updated after each release
• Specific version tags (v1.0.0) remain immutable for reproducibility

Schedule Updates

The schedule.json file contains release dates for Python and core Scientific Python packages. It's automatically updated monthly via GitHub Actions cron job.

To manually update:

phep3-check --generate-schedule --schedule-output schedule.json

Core Scientific Python Packages

As defined by SPEC 0:

• numpy
• scipy
• matplotlib
• pandas
• scikit-image
• networkx
• scikit-learn
• xarray
• ipython
• zarr

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open issues or pull requests on GitHub.

Related

• PHEP 3 - PyHC Python & Upstream Package Support Policy
• SPEC 0 - Scientific Python Minimum Supported Versions
• PyHC Environment - Docker environment with all PyHC packages