Cookiecutter PyPixi package

Template for Python packages using Pixi.

Features

This project template includes the following features to ensure best practices:

• Overall project configuration: pyproject.toml for PEP-621-compliant project configuration, packaging with uv_build, and task/environment management with pixi.
• Tests:
  • pixi environments and tasks for testing against multiple Python versions in GitHub Actions.
  • coverage reporting with codecov integration.
• Documentation: generated with sphinx, using MyST for Markdown support, auto API generation from docstrings and hosting on readthedocs with the pydata-sphinx-theme through a Pixi-managed docs environment.
• Code quality: set up with pre-commit to run checks and tests before each commit, including, among others:
  • ruff for Python code linting and formatting
  • codespell to check for common misspellings
  • pyupgrade to automate upgrade syntax for newer Python versions
• Continuous integration and delivery with GitHub Actions, with jobs to run tests, publishing to test PyPI and releasing to PyPI and GitHub on new tags.
• Conventional commits and semantic versioning with commitizen to enforce conventional commits (with pre-commit hooks), version bumping using and automated change log generation.

Usage

First time setup

Generate a new project using cookiecutter:

cookiecutter gh:martibosch/cookiecutter-pypixi-package

and fill in the prompts. Then, navigate to the generated directory and follow the instructions below:

• Install pixi and create the local development environment with pixi install -e dev.
• Commit the generated pixi.lock file after the first successful resolve, and update/commit it again whenever dependencies change.
• Initialize a git repository (e.g., git init) and install the pre-commit hooks by running pixi run -e dev pre-commit install and pixi run -e dev pre-commit install --hook-type commit-msg.
• Register the project in codecov and readthedocs.
• If the repository is public, enable pre-commit.ci to automatically run pre-commit checks on GitHub and autoupdate the pre-commit hook versions.
• Create accounts (or use existing accounts) and set up pending publishers for the github repository for PyPI and test PyPI. Enter "release.yml" in the "Workflow name" field and respectively "pypi" and "testpypi" in the "Environment name" field.

You can then start developing your package with pixi run -e test test and pixi run -e doc build-doc.

If you want stricter CI after committing pixi.lock, you can set frozen: true in the generated GitHub Actions workflows so CI fails when the lockfile is missing or out of date.

Submit a recipe to conda-forge

If you want your package to be available from conda-forge, you can generate a recipe for it using grayskull and then submit it by following the instructions in the conda-forge documentation.

Acknowledgements

• This template borrows several ideas from zillionare/python-project-wizard.