README.md

Copier Hatch

---

Opinionated Copier template for Python projects managed by Hatch.

This template was created for personal use, but I'd be smitten if others find it helpful (please smash that star button).

Usage

If all the requirements are met:

copier copy --trust "git@github.com:spacecoffin/copier-hatch.git" path/to/destination

If the Git & uv requirements are met but you don't want to install Copier as a uv tool:

uvx --python=3.11 --python-preference=managed --with=copier-templates-extensions \
    copier copy --trust "git@github.com:spacecoffin/copier-hatch.git" path/to/destination

Updating

To update an existing project based on this template, run:

copier update --trust

For more information on updating a project, see the official instructions.

Features

• Project setup and template update with Copier
• Centralized package, build, & tool configuration in pyproject.toml
• Packaging, dependency management, task runners, Python interpreter management, & test automation with Hatch
• Lock file support with hatch-pip-compile
• Extremely fast Python package installation & resolution with uv
• Style guide enforcement both locally & in CI with pre-commit
• Code formatting, linting, import sorting, automated Python syntax upgrades, & security auditing with Ruff
• Continuous integration with GitHub Actions
• Unit testing with pytest
• Code coverage measurement with Coverage.py
• Static type-checking with mypy & basedpyright
• src layout: Python package under src directory to avoid common errors

Setup

To use this template, you will need:

• Git >= 2.27
• uv >= 0.5.0
• Copier >= 9.4

Git

Check the installed version of Git with:

git --version

If the version is < 2.27, follow the official instructions to install Git version 2 or, alternatively, install with Homebrew:

brew install git

uv

To install uv, follow the official instructions or, alternatively, install with Homebrew:

brew install uv

Copier

Use uv to install Copier as a global tool, including Jinja extensions:

uv tool install copier --with=copier-templates-extensions

Testing

This template includes both an (incomplete) unit test suite and a minimal integration test suite that uses copier-template-tester to render the templates specified by the mock answers in ctt.toml.

Unit Tests

To run the pytest unit tests:

hatch run test:test

Integration Tests

To run the copier-template-tester-based integration tests:

hatch run test:ctt

Info: The location of the rendered output for each template is determined by the name of the section in ctt.toml defining its parameters; specifically by the relative path following output. e.g., [output.".ctt/defaults"] will render to .ctt/defaults.

The test output can be removed with

hatch run test:clean

Acknowledgements

This template stands on the shoulders of Claudio Jolowicz (cjolowicz)'s Hypermodern Python Cookiecutter, the many excellent Copier templates of Timothée Mazzucotelli (pawamoy), Bruno Alla (browniebroke)'s pypackage-template, & the built-in project template of Hatch itself.

I have done my best to document all borrowed code with the appropriate copyright notices and either the permission notices themselves or a reference to the license under which the original code is distributed. As this project was originally developed as a personal project (never to see the light of open source distribution), these notices were added post-hoc. If any discrepancies are found, please file an issue so I can give proper credit.