A modern Python project template powered by Copier with TDD-Guard integration.
Note: This is a fork of mjun0812/python-copier-template with enhanced TDD workflow support and additional tooling.
- 🚀 Modern Python: Support for Python 3.10-3.13
- 📦 uv Package Manager: Fast and reliable package management with uv
- ⚡ just Command Runner: Clean, modern task runner with intuitive syntax
- 🐳 Docker Support: Complete Docker development environment
- 📦 Devcontainer Support: VS Code devcontainer for consistent development
- ✨ AI Editor Support: AGENTS.md and CLAUDE.md included for AI-powered development
- 📝 Type Checking: Zuban type checker in mypy-compatible mode
- 🔍 Code Quality: Pre-configured Ruff for linting and formatting
- 🧪 Testing: pytest setup with coverage reporting and enhanced output (pytest-cov, pytest-sugar)
- 📊 Modern Logging: Loguru for intuitive, zero-config logging
- 🔧 Pre-commit Hooks: Automated code quality checks with prek (10x faster than traditional pre-commit)
- 🏷️ Dynamic Versioning: Automatic versioning from git tags (no manual version bumping!)
- 📝 Changelog Generation: Automated CHANGELOG.md from conventional commits
- 🏗️ CI Ready: GitHub Actions workflows included
uvx copier copy gh:tfriedel/python-copier-template your-project-nameFollow the interactive prompts to configure your project:
- Project name: Your project's name
- Python version: Choose from 3.10, 3.11, 3.12, or 3.13
- Package name: The name used for importing your package (e.g.,
import package_name) - Description: A short description of your project
- Author name: Your name
- Author email: Your email address
After generating your project:
cd your-project-name
# Quick setup (installs dependencies and pre-commit hooks)
just setup
# Or manually:
uv sync # Install dependencies
uv run prek install # Install pre-commit hooks
# Run tests
just test # or: uv run pytest
# Run formatting, linting, and type checking
just format # or: uv run ruff format .
just lint # or: uv run ruff check .
just typecheck # or: uv run zmypy
# Auto-fix linting issues
just lint-fix # or: uv run ruff check . --fix
# See all available commands
just --listThe template includes a complete Docker setup:
# create uv.lock file
uv sync
# use the provided scripts
./docker/build.sh
./docker/run.sh # or./docker/run.sh (Command)
# Build and run with Docker Compose
docker compose build
docker compose upOpen the project in VS Code and use the "Reopen in Container" command for a fully configured development environment. Devcontainer will automatically install uv, Claude Code, and pre-commit hooks.
cd your-project-name
uvx copier update -Ayour-project/
├── src/
│ └── your_project/ # Main package
├── tests/ # Test files
├── docker/ # Docker configuration
├── compose.yml # Docker Compose setup
├── pyproject.toml # Project configuration
└── README.md # Project documentation
just is a modern command runner designed specifically for developer tasks, not build systems. It offers:
- Cleaner, more intuitive syntax without Make's quirks (no tab sensitivity, better error messages)
- Written in Rust, aligning with the modern toolchain (prek, ruff, zuban, uv)
- Better cross-platform compatibility
- Developer-friendly features like recipe parameters and clear command listing
Zuban is a high-performance type checker written in Rust that's 20-200× faster than mypy while maintaining compatibility. The template uses it in mypy-compatible mode for familiar behavior and error messages.