🚀 UV Copier Template

A modern Copier template for scaffolding Python packages and applications with best practices built-in.

🎁 Features

• 📦 Modern Python packaging using UV for lightning-fast dependency management
• ⚡️ Streamlined task execution with poethepoet
• ✍️ Code formatting and linting with Ruff
• 🔍 Type checking with ty
• 🛡️ Quality gates with Pre-commit hooks
• 🏷️ Automated versioning following Conventional Commits with Commitizen
• 📋 Changelog generation compatible with Keep A Changelog
• 🔄 Continuous integration with GitHub Actions
• 🏗️ Template updates with Copier for easy maintenance

✨ Quick Start

Creating a New Python Project

1. Install UV globally:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Generate your project:

   # Create in a new directory
   uvx --with jinja2-time copier copy https://github.com/gotofritz/copier-python-template my-project/ --trust
   
   # Or create in current directory
   mkdir my-project && cd my-project
   uvx --with jinja2-time copier copy https://github.com/gotofritz/copier-python-template . --trust

   Note: --trust and --with jinja2-time are required because the template enables the jinja2-time Jinja extension, which puts the current year in the LICENSE.

3. Configure your project by answering the interactive prompts:

   Prompt	Default	Notes
   project_name		Letters, digits, - and _
   org_name	gotofritz	GitHub org or user
   package_name	derived from project_name	Python import name
   project_description	A Python package
   project_url	https://github.com/<org>/<project>
   author_name, author_email	gotofritz
   python_version	3.13	Minimum supported version
   with_conventional_commits	true	Adds Commitizen and the commit-msg hook
   cli	true	Adds a Click CLI entrypoint

4. Initialize Git and create remote repository:

   cd my-project
   git init
   
   # Using GitHub CLI (recommended)
   gh repo create my-org/my-project --private --source=. --push
   
   # Or follow GitHub's instructions to push an existing repository

5. Set up dependencies:

   uv sync
   git add uv.lock && git commit -m "feat: add dependency lock file"

Updating Your Project

Keep your project aligned with the latest template improvements:

uvx --with jinja2-time copier update --trust

If conflicts arise, resolve them by inspecting the generated .rej files.

🖥️ CLI Application Support

When you enable CLI support during project creation, the template generates a ready-to-use command-line interface:

• Automatic script installation named after your project (kebab-case)
• Sample commands to get you started
• Easy customization via pyproject.toml

Example usage:

❯ my-project --help
Usage: my-project [OPTIONS] COMMAND [ARGS]...

  Main entry point for the CLI.

Options:
  -v, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  simple-command  This is a simple command.
  subcommand      This contains sub-subcommands

🔧 Development and Customization

Testing Locally

To test modifications to this template:

uvx --with jinja2-time copier copy ./copier-python-template --trust --vcs-ref=HEAD my-test-project

Forking the Template

1. Fork this repository
2. Update all occurrences of gotofritz to your GitHub username
3. Customize the template to match your preferences
4. Use your forked version in the copy commands above

📚 What's Included

Your generated project comes with:

• Modern Python packaging with PEP 621 compliant pyproject.toml
• Development tools pre-configured and ready to use
• GitHub Actions CI (.github/workflows/ci.yml) running pre-commit and poe qa on every push and pull request to main
• Coverage badge: on pushes to main, CI publishes coverage.svg to a badges branch (created on the first run) and the README links to it
• Pre-commit hooks for file hygiene, TOML sorting and Ruff on commit, the full poe qa on push, and Commitizen on commit-msg when conventional commits are enabled
• MIT license: a LICENSE file with the current year and the author's name, referenced from pyproject.toml
• Documentation structure with a README and a docs/ folder (the changelog is generated by Commitizen on cz bump)
• Testing setup with pytest and coverage reporting (95% minimum in generated projects)

CI for this template

This repository has its own workflow and pre-commit config. Run the same checks locally with:

uv sync
uv run pre-commit run --all-files --hook-stage manual
uv run poe qa

---