GitHub - privatedumbo/python-template: My python projects template. Trying to keep it lean.

Python Copier Template

A Copier template for modern Python projects. Batteries included with UV, Ruff, Mypy, Pytest, and more.

✨ Features

Development Tools

📦 UV - Ultra-fast Python package manager
🚀 Poe the Poet - Modern task runner
💅 Ruff - Lightning-fast linter and formatter
🔍 Mypy - Static type checker
🧪 Pytest - Testing framework with coverage

Always Included

🛫 Pre-commit hooks - Automated code quality checks
🤖 AGENTS.md - Best practices for AI-assisted development

Optional

🐳 Docker - Multi-stage builds optimized for Python/UV
🔄 GitHub Actions - CI/CD pipeline

🚀 Quick Start

Prerequisites

Python 3.13+
Copier (pipx install copier or uv tool install copier)

Generate a New Project

# From GitHub (recommended)
copier copy gh:privatedumbo/python-template my-awesome-project

# From a local clone
copier copy /path/to/python-template my-awesome-project

Interactive Prompts

Copier will ask you a series of questions to customize your project:

Question	Description	Default
`project_slug`	Project/package name (lowercase, underscores)	-
`description`	Short project description	"A Python project"
`author_name`	Author's full name	-
`author_email`	Author's email	-
`github_username`	GitHub username/organization	-
`python_version`	Minimum Python version	3.14
`license`	Project license	MIT
`include_docker`	Include Docker support	Yes
`include_github_actions`	Include GitHub Actions CI/CD	Yes

Example

$ copier copy gh:privatedumbo/python-template my-project

🐍 Python Project Generator
═══════════════════════════════════════════════════════

This template creates a modern Python project with:
• UV for fast dependency management
• Ruff for linting and formatting
• Mypy for type checking
• Pytest for testing
• Pre-commit hooks

Let's configure your new project!

🎤 Project name (lowercase, underscores allowed).
   my_awesome_project
🎤 A short description of your project (one line).
   A truly awesome Python project
🎤 Your full name.
   John Doe
🎤 Your email address.
   john@example.com
🎤 GitHub username or organization name.
   johndoe
🎤 Minimum Python version for your project.
   3.14 (stable, recommended)
🎤 Open source license for your project.
   MIT (permissive, simple)
🎤 Include Docker support?
   Yes
🎤 Include GitHub Actions CI/CD?
   Yes
    create  .copier-answers.yml
    create  AGENTS.md
    create  .gitignore
    create  .pre-commit-config.yaml
    create  .python-version
    create  Dockerfile
    create  LICENSE
    create  README.md
    create  my_awesome_project/__init__.py
    create  my_awesome_project/main.py
    create  pyproject.toml
    create  scripts/app.toml
    create  tests/__init__.py
    create  tests/test_core.py
    create  .github/workflows/ci.yaml
    create  .github/actions/validation/action.yaml

🔄 Updating Your Project

When this template is updated, you can pull in the changes:

cd my-awesome-project
copier update

Copier will intelligently merge template updates with your local changes.

🧪 Template Development

Prerequisites

# Clone the repository
git clone https://github.com/privatedumbo/python-template.git
cd python-template

# Install dependencies
uv sync --all-extras

Running Tests

# Run all tests
uv run poe test

# Run full validation (format, lint, check, test)
uv run poe flct

Manual Testing

Generate a project to a temporary directory:

This creates a test project at /tmp/test-project.

📁 Template Structure

python-template/
├── copier.yaml              # Copier configuration & questions
├── template/                # Template source files
│   ├── {{project_slug}}/    # Package directory (templated name)
│   │   ├── __init__.py
│   │   └── main.py.jinja
│   ├── tests/
│   │   ├── __init__.py
│   │   └── test_core.py.jinja
│   ├── scripts/
│   │   └── app.toml.jinja
│   ├── .github/             # GitHub Actions (conditional)
│   ├── AGENTS.md.jinja      # AI agent instructions (always included)
│   ├── pyproject.toml.jinja
│   ├── README.md.jinja
│   ├── Dockerfile.jinja     # Docker support (conditional)
│   └── ...
├── tests/                   # Template tests
│   └── test_template.py
└── pyproject.toml           # Template project config

📝 License

This template is licensed under the MIT License.

🙏 Acknowledgments

Copier - The awesome template engine
UV - Ultra-fast Python package manager
Ruff - Lightning-fast linter