copier-python-template

A modern, streamlined Python project template with best practices, modern tooling, and production-ready features.

✨ Features

Core Features (Always Included)

• ✅ Package Management: uv for fast, reliable dependency management
• ✅ Tool Management: mise for Python version management
• ✅ Code Quality: Ruff for linting and formatting
• ✅ Type Checking: ty (10-60x faster) + mypy (comprehensive)
• ✅ Testing: pytest with coverage reporting
• ✅ Pre-commit: prek (Rust-based, faster than pre-commit)
• ✅ Documentation: MkDocs Material with code example testing
• ✅ CI/CD: GitHub Actions workflows
• ✅ Build System: Hatchling + hatch-vcs for git-based versioning
• ✅ Project Structure: Clean, modular layout (app/, config/, tests/, docs/, scripts/, notebooks/)

Optional Features (User-Selected)

Project Structure (Multi-select)

• HTTP/Web 🌐: FastAPI with routes/controllers/middleware + PostgreSQL + Docker Compose
• AI/ML 🤖: AI directories (agents, actions, evals, trainers)
• Data Processing 📊: Data directories (extractors, transformers, analyzers, visualizers)
• Hardware 🔌: Hardware integration directories (sensors, actuators, controllers, communicators)

Dependency Groups (Multi-select)

• web - FastAPI, uvicorn, httpx, gunicorn
• data - pandas, polars, duckdb, ibis, pandera, sqlmodel
• ml-pytorch - torch, lightning, torchmetrics (includes numpy, scikit-learn, scipy)
• ml-sklearn - sklearn + extensions (skops, skrub, sklego, yellowbrick, imbalanced-learn)
• eda - 4 AutoEDA tools (hiplot, ydata-profiling, sweetviz, dataprep)
• marimo 📓 - Modern reactive notebooks (alternative to Jupyter)
• config - OmegaConf + Hydra for advanced configuration
• ai-apis - OpenAI + Anthropic APIs

Additional Options

• Docker 🐳: Multi-stage Dockerfile + docker-compose.yaml with PostgreSQL
• DevContainer 🛠️: VS Code devcontainer with pre-configured environment
• CLI ⌨️: Typer-based command-line interface setup

🚀 Quick Start

Prerequisites

• Python 3.11+
• Copier 9.0+
• uv (installed automatically if missing)
• mise (optional, for tool version management)

Install Copier

# With pipx (recommended)
pipx install copier

# With uv
uv tool install copier

# With pip
pip install copier

Generate a New Project

copier copy --trust gh:markussagen/copier-python-template my-project
cd my-project
make setup

You'll be asked a series of questions to configure your project. Smart defaults are provided based on your answers.

📋 Template Questions

The template will ask you:

1. Project metadata: name, description
2. Author info: name, email, GitHub username (auto-detected from git)
3. Repository: provider, namespace, name (smart defaults)
4. Copyright: holder, license (40+ open source licenses available)
5. Python package: distribution name, import name, CLI name (pre-filled smartly)
6. Python version: minimum version (3.11 or 3.12)
7. Project structure (multi-select): HTTP, AI, Data Processing, Hardware
8. Dependency groups (multi-select): web, data, ml-pytorch, ml-sklearn, eda, marimo, config, ai-apis
9. Docker: Include Docker and docker-compose?
10. DevContainer: Include VS Code devcontainer?

🏗️ Generated Project Structure

my-project/
├── app/                    # Reusable application code
│   ├── core/              # Core functionality and configuration
│   ├── utils/             # Comprehensive utility functions
│   ├── cli/               # Command-line interface (if CLI enabled)
│   ├── http/              # HTTP API (if HTTP selected)
│   │   ├── controllers/   # Request handlers
│   │   ├── middleware/    # Middleware
│   │   └── routes/        # Route definitions
│   ├── ai/                # AI/ML code (if AI selected)
│   ├── data/              # Data processing (if Data selected)
│   ├── hardware/          # Hardware integration (if Hardware selected)
│   └── _private/          # Git-ignored private code (WIP)
├── config/                # Configuration and settings
│   └── settings.py        # Pydantic settings
├── data/                  # Git-ignored data storage
├── docs/                  # MkDocs documentation
├── notebooks/             # Notebooks for exploration
│   └── _private/          # Git-ignored notebook drafts
├── scripts/               # Executable scripts
│   └── _private/          # Git-ignored script drafts
├── tests/                 # Test suite
├── utils/                 # Shared utilities (logging, formatting, etc.)
├── .github/               # GitHub Actions workflows
├── .vscode/               # VS Code configuration
├── .zed/                  # Zed editor configuration
├── Dockerfile             # Multi-stage Docker build (if enabled)
├── compose.yaml           # Docker Compose with PostgreSQL (if HTTP+Docker enabled)
├── Makefile               # Command runner with help system
├── pyproject.toml         # Project metadata and tool configuration
├── .mise.toml             # Tool version management
├── .pre-commit-config.yaml # Pre-commit hooks (prek)
├── mkdocs.yml             # Documentation configuration
├── CLAUDE.md              # Instructions for Claude Code
├── README.md              # Project documentation
├── CONTRIBUTING.md        # Contributing guidelines
├── CHANGELOG.md           # Release notes
└── LICENSE                # License file

💻 Development Workflow

Generated projects include a comprehensive Makefile:

make help            # Show all available commands
make setup           # Setup project (install uv, create venv, install deps)
make lint            # Check code quality
make format          # Format code
make typecheck       # Run ty + mypy type checking
make test            # Run tests with coverage, docs examples, and spellcheck
make test-watch      # Run tests in watch mode
make run             # Start development server (if HTTP enabled)
make shell           # Start IPython shell
make marimo          # Start Marimo notebook server (if marimo enabled)
make docker-build    # Build Docker image (if Docker enabled)
make compose-up      # Start services with docker-compose (if Docker enabled)
make docs            # Serve documentation locally
make docs-test       # Test code examples in documentation
make hooks-install   # Install pre-commit hooks
make template-check  # Check for template updates (dry-run)
make template-update # Update project from template
make clean           # Remove cache files

🐳 Docker & PostgreSQL

When you enable HTTP + Docker, you get:

• Multi-stage Dockerfile optimized for production
• docker-compose.yaml with:
  • FastAPI application
  • PostgreSQL 16 database
  • Environment variable configuration
  • Health checks and dependencies
  • Data persistence with volumes
• SQLModel for type-safe database models (works with SQLite and PostgreSQL)

# Start services
make compose-up

# View logs
make compose-logs

# Stop services
make compose-down

📊 EDA Tools

When you select the eda dependency group, you get 4 core AutoEDA tools:

• hiplot - Interactive high-dimensional visualizations for ML experiment tracking
• ydata-profiling - Industry standard comprehensive profiling
• sweetviz - Beautiful comparative analysis (train vs test)
• dataprep - Fast EDA for large datasets (10-100x faster than ydata-profiling)

from utils.eda import quick_eda

# High-dimensional experiments (ML tuning)
exp = quick_eda(experiments_df, tool="hiplot")

# Comprehensive analysis (default)
report = quick_eda(df, tool="ydata")

# Comparative analysis
report = quick_eda(train_df, tool="sweetviz", target="price")

# Fast analysis for large data
report = quick_eda(large_df, tool="dataprep")

🔄 Template Updates

Copier makes it easy to keep your project up-to-date with the latest template improvements.

Automatic Setup

When you generate a project:

1. Git is initialized automatically (if not already a repo)
2. All files are committed with a descriptive message
3. Pre-commit hooks are installed (if prek is available)
4. Answers are saved in .copier-answers.yml for future updates

Checking for Updates

# Check if template has updates (dry-run)
make template-check

# Or use copier directly
copier update --pretend

Updating Your Project

# Update from latest template version
make template-update

# Or specify a version
copier update --vcs-ref=v1.0.0

Automated Update Checks

Generated projects include a GitHub Actions workflow that:

• Runs weekly to check for template updates
• Creates a PR automatically when updates are available
• Handles conflicts and provides clear instructions

🚢 Releasing a New Version

To create a release of the template:

1. Commit Your Changes

First, ensure all your changes are committed using Conventional Commits:

# Feature
git commit -m "feat: add new optional feature"

# Bug fix
git commit -m "fix: correct template generation issue"

# Documentation
git commit -m "docs: update readme with examples"

# Breaking change
git commit -m "feat!: change copier field names"

2. Update the Changelog

Generate the changelog from your git commit history:

make changelog

This creates/updates changelog.md with all commits since the last release, formatted by type (Features, Bug Fixes, Documentation, etc.).

3. Review and Commit Changelog

# Review the generated changelog
cat changelog.md

# Commit it
git add changelog.md
git commit -m "docs: update changelog for version X.Y.Z"

4. Create and Push Tag

# Create annotated tag (use semantic versioning)
git tag -a v0.2.0 -m "Release v0.2.0"

# Push commits and tags
git push && git push --tags

5. GitHub Release (Automatic)

The .github/workflows/release.yml workflow will automatically:

• Trigger when you push a tag starting with v
• Generate release notes from the changelog
• Create a GitHub Release with the notes attached

Version Numbering

Follow Semantic Versioning:

• Major (v1.0.0 → v2.0.0): Breaking changes (incompatible API changes)
• Minor (v1.0.0 → v1.1.0): New features (backward compatible)
• Patch (v1.0.0 → v1.0.1): Bug fixes (backward compatible)

Example Full Release Flow

# 1. Make changes and commit (you've already done this)
git add -A
git commit -m "feat: add mktestdocs testing for documentation"

# 2. Generate changelog
make changelog

# 3. Review and commit changelog
git add changelog.md
git commit -m "docs: update changelog for v0.2.0"

# 4. Tag and push
git tag -a v0.2.0 -m "Release v0.2.0"
git push && git push --tags

# 5. GitHub Actions creates the release automatically!

🎯 Key Differences from copier-uv

Feature	copier-uv	copier-python-template
Project Layout	src/	app/ (modular)
Command Runner	duty (Python)	Makefile
Build Backend	PDM	Hatchling + hatch-vcs
Type Checker	mypy only	ty + mypy
Ruff Config	config/ruff.toml	pyproject.toml
Tool Manager	None	mise
Pre-commit	pre-commit	prek (Rust-based)
Docker	Not included	Multi-stage build + PostgreSQL
DevContainer	Not included	VS Code devcontainer
Structure	Minimal	Modular with options
Optional Features	Limited	Extensive (HTTP, AI, data, hardware)
Dependency Groups	Many	8 focused groups
Utilities	Basic	Comprehensive (30+ utility modules)
Database	None	SQLModel + PostgreSQL/SQLite
EDA Tools	None	4 core AutoEDA tools

📚 Documentation

Generated projects include comprehensive documentation:

• CLAUDE.md: Instructions for Claude Code with project-specific guidance
• README.md: Project overview and quick start
• CONTRIBUTING.md: Development guidelines
• docs/: MkDocs documentation with:
  • Installation guide
  • Usage examples
  • API reference (auto-generated from docstrings)
  • Dependency groups documentation
  • Contributing guide
  • Changelog

All code examples in documentation are automatically tested with mktestdocs!

🛠️ Editor Support

VS Code

Pre-configured settings for:

• Python with Pylance
• Ruff formatting and linting
• ty + mypy type checking
• pytest integration
• Launch configurations for debugging
• Recommended extensions

Zed

Configuration for:

• Python LSP integration
• Ruff formatting
• Type checking
• Terminal environment

Other Editors

The project works with any editor. Use:

• uv run to execute Python scripts
• Ruff via Language Server Protocol
• Standard Python LSP for completions

🧪 Testing the Template

The template includes comprehensive CI/CD testing to ensure generated projects work correctly.

GitHub Actions

The template repository includes workflows to:

• Test template generation with various configurations
• Validate generated projects (lint, typecheck, test)
• Test Docker builds (if enabled)
• Verify all Makefile commands work
• Test on multiple Python versions (3.11, 3.12)
• Test on multiple OS (Ubuntu, macOS, Windows)

Manual Testing

# Generate a test project with all features
copier copy --trust copier-python-template test-project

cd test-project
make setup
make lint
make format
make typecheck
make test

🤝 Contributing to the Template

Contributions are welcome! To modify the template:

1. Clone the repository
2. Make changes to template files in project/
3. Update copier.yml for new questions
4. Test with copier copy --trust . test-project
5. Submit a pull request

See CLAUDE.md for detailed template development instructions.

📖 Background

Why This Project Structure?

The project structure separates:

• Code to Run (scripts/, notebooks/): Executable scripts and notebooks
• Code to Reuse (app/): Reusable functions, classes, and modules

This separation scales from small projects to large applications with clear organization.

Why ty + mypy?

The template uses both type checkers for complementary benefits:

ty - Astral's new type checker (released Jan 2026):

• 10-60x faster than mypy/Pyright
• Written in Rust for speed
• Designed for language server use (instant feedback in editors)
• Perfect for rapid development and CI checks

mypy - Industry standard:

• Comprehensive type checking with strict mode
• Plugin support for Pydantic, Django, SQLAlchemy, and more
• Catches edge cases that ty might miss
• Mature ecosystem and extensive documentation

Using both gives you speed (ty) and thoroughness (mypy). Run make typecheck to check with both!

Why uv?

uv by Astral:

• 10-100x faster than pip
• Replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv
• Lockfile for reproducible installs
• Drop-in replacement (no learning curve)
• PEP 735 dependency groups support

Why prek?

prek is a Rust-based pre-commit tool:

• Faster than Python-based pre-commit
• No Python dependency conflicts
• Drop-in replacement (uses same .pre-commit-config.yaml)
• Easy installation via uv: uv tool install prek
• Automatic installation when running make setup

Why Marimo?

Marimo is a modern alternative to Jupyter notebooks:

• Reactive: Cells auto-run when dependencies change (no stale outputs)
• Git-friendly: Notebooks are pure Python .py files
• Production-ready: Export as apps, scripts, or traditional notebooks
• Interactive: Built-in SQL cells, dataframe viewer, AI integration
• Better DX: No hidden state, deterministic execution, easy to debug

Perfect for data science workflows that need to be version-controlled and production-ready!

🔗 Links

Template & Tools

• Copier Documentation
• copier-uv (base template)
• uv Documentation
• mise

Code Quality

• Ruff Documentation
• ty Type Checker
• mypy Documentation
• prek

Frameworks & Libraries

• FastAPI
• Marimo - Modern reactive notebooks
• SQLModel - SQL databases with Python type hints
• ydata-profiling - AutoEDA profiling

📄 License

This template is licensed under the MIT License.

🙏 Credits

• Based on copier-uv by Timothée Mazzucotelli
• Built with tools from Astral: uv, Ruff, and ty
• Inspired by modern Python best practices and tooling

---

Start your next Python project the right way! ⚡