template-uv-python-research-software

This is a copier template for building Python research software through the uv environment manager.

High-level overview

Projects generated from this template include:

• uv-managed environments and dependencies
• Testing and coverage defaults via pytest + coverage.py
• Pre-commit automation for formatting, linting, and type checks
• GitHub Actions workflows for linting, tests, docs, and release-related automation
• Starter package + CLI scaffold under src/
• Documentation scaffold under docs/
• Poe task entrypoints for common local workflows (including a full local pipeline task)

Template variants

This template can generate either of two project shapes:

• Pure Python: a standard src/-layout Python package built with setuptools, with optional notebook scaffolding for research workflows.
• Rust-bound Python: a Python package backed by a Rust workspace under crates/, using PyO3 and maturin to expose a native extension module for performance-sensitive routines.

Copier asks for this choice through the use_rust option. Choose the pure-Python variant when portability, simple packaging, and a smaller contributor toolchain matter most. Choose the Rust-bound variant when you expect core routines to benefit from a compiled implementation while keeping a Python API and CLI for users.

Included agent skills

Generated projects include agent guidance in .agents/skills/ with common skills for:

• Test-driven development
• Incremental implementation
• Code review and quality checks
• CI/CD and automation workflow alignment
• Debugging and error recovery
• Optional learning exercises for comprehension (learning-opportunities)

If you do not want to use local agent guidance in your project, remove AGENTS.md and the .agents/ directory.

Using this template

Follow these steps to use this template:

1. Install copier (e.g. pip install copier).
2. Reference this repository through the copier copy <source> <target> command. (e.g. uvx copier copy --vcs-ref=HEAD https://github.com/cu-dbmi/template-uv-python-research-software destination_path) If you still see stale content, clear Copier's cache (rm -rf ~/.cache/copier) and run the command again.
3. Follow the directions in your new repo's README.md and make sure to check each file for alignment with your project.
4. Enjoy!

Copier already excludes .git from rendered output, so copying this template into an existing repository keeps that repository's history in place instead of importing this template's history. Copier also does not automatically run git init for a fresh destination. That could be done with a post-copy task, but Copier treats tasks as an unsafe feature, so this template leaves repository initialization as an explicit user step.

What's included in the template

• Pre-configured pyproject.toml for Python project management
• Support for the uv environment manager
• Example source code and test structure
• Example docs structure with the option to publish to GitHub Pages
• Ready-to-use GitHub Actions CI workflow (including tests, docs, and deployment)
• Community health files like LICENSE, CODE_OF_CONDUCT, and CONTRIBUTING with boilerplate language
• Support for Jupyter notebook development alongside a local Python package
• .pre-commit-config.yaml which can help with pre-commit checks for your project
• Adds a CLI boilerplate to build from based on fire.
• Optional Rust bindings scaffold with Cargo workspace crates, PyO3 bindings, maturin builds, Rust-aware CI, and release publishing support.

Post-copy guidance

Please reference the README.md checklist for suggested next steps after copying the template. When using the Jupyter notebook work, consider using uv run jupyter lab (or similar) to run notebooks which are invoked from the context of the virtual environment of the project. This helps the notebook gain dependencies and access to the packaged work outside the notebooks directory.

Development

This project is a Copier template repository, designed to scaffold new projects using customizable templates. The templates leverage Jinja for flexible variable substitution and logic within template files.

To ensure the template remains functional and testable, pytest is used. Tests are provided to verify that the template can be rendered and instantiated correctly, helping to catch issues early in the development process.

For example, use the following to test the work:

uv run pytest