PyHC Package Repo Template

Overview

This repository template created by the Python in Heliophysics Community (PyHC) provides a foundation for new Python projects wishing to become PyHC packages. It follows all PyHC standards and best practices, making it easy for developers to start new projects that will integrate well with the PyHC ecosystem.

How to Use This Template

1. Click the green "Use this template" button at the top of this GitHub repository
2. Select "Create a new repository"
3. Name your new public repo and complete the remaining fields
4. Update the pyproject.toml file with your package information
5. Rename the src/my_pyhc_package directory to match your package name
6. Start developing your awesome heliophysics package!

Code Style

All PyHC projects must follow the PEP 8 style recommendations. This template has been pre-configured to comply with them. Use static analysis tools to identify style deviations, e.g.:

• Flake8 (what this template was linted with)
• Pylint
• Ruff

Testing

Testing is essential for PyHC packages. This template includes a basic test setup compatible with pytest, although you may use your preferred testing framework.

Testing Guidelines:

• Write unit tests for individual components (functions, classes)
• Write integration tests that verify interactions between components
• Measure test coverage

As an example, to run tests with pytest:

# Run all tests
pytest tests/

# Run tests with coverage
pytest --cov=src tests/

Publishing Your Package

It is recommended that PyHC packages publish to both PyPI (pip) and conda.

Publishing to PyPI

This template includes a GitHub Actions workflow that automatically publishes your package to PyPI when you create a new release on GitHub.

1. Ensure your pyproject.toml is properly configured
2. Create a PyPI API token and add it to your repository secrets as PYPI_API_TOKEN
3. Create a new release on GitHub
4. The workflow will automatically build and publish your package

For more details, see the PyPI documentation.

Publishing to conda

To make your package available via conda:

1. Create a conda recipe (usually a meta.yaml file)
2. Submit your package to conda-forge

For detailed instructions, see the conda-forge documentation.

DOI Integration with Zenodo

To automatically mint DOIs for your releases:

1. Log in to Zenodo
2. Navigate to your GitHub account settings in Zenodo
3. Enable the repository you want to track
4. Create a new release on GitHub
5. Zenodo will automatically mint a DOI for your release

For more detailed instructions, see this guide.

Citation File

This template includes a CITATION.cff file that follows the Citation File Format specification. Update this file with your project's information to make it easy for others to cite your work.

For more information, see GitHub's documentation on citation files.

Documentation

This template includes a basic docs/ directory where you can build your documentation. It's recommended to use Read the Docs for hosting your project documentation, as doing so automatically grants your package inclusion in the PyHC Documentation Hub.

Alternative documentation systems for Python include:

• Sphinx
• MkDocs
• Jupyter Book

Note: many are compatible with Read the Docs.

Code of Conduct

This template includes a Code of Conduct based on the Contributor Covenant. Please review and modify CODE_OF_CONDUCT.md as needed for your project, but ensure it remains compatible with the Contributor Covenant.

License

This template includes a permissive license. PyHC recommends using permissive open-source licenses such as:

• BSD 3-Clause License
• MIT License
• Apache License 2.0

Copyleft licenses like GPL are not recommended for PyHC projects.

You may choose a different license for your project by updating the LICENSE file, but make sure to select an OSI-approved permissive license.

PyHC Environment Compatibility

The PyHC Environment is a Dockerized Python environment deployed via Binder that includes all published PyHC packages. When developing your package, we strongly request that you ensure compatibility with this environment.

Dependency Management:

Substantial prior community work was done to resolve dependency conflicts among PyHC packages to allow them to be imported and used in the same environment.

• Packages that follow PHEP 3 guidelines for dependency management are significantly less likely to introduce conflicts
• To check the allowed version ranges of dependencies, refer to the latest PyHC Environment dependency spreadsheet
• Note that when dependency conflicts arise, PyHC's Tech Lead will personally work with the affected packages to try to resolve them (inability to resolve will result in the temporary removal of the offending package from the environment)

PyHC Standards

For the complete set of PyHC standards that packages must follow, please refer to the PyHC Standards Document.

PyHC Submission

Did you make an awesome heliophysics package with this template? Submit it to be a PyHC package!