Python App Template

A Cookiecutter template for building CLI-first Python applications with uv, Typer, Pydantic, and strict typing.

Features

• CLI-first architecture with Typer
• Local-first config (XDG paths) with env override
• uv for fast dependency management and reproducible installs
• Ruff for linting/formatting
• MyPy with strict typing
• Pytest with coverage support
• Invoke tasks for common operations
• py.typed marker for typed packages
• Example command wired from core commands/ into CLI

Quick Start

1. Install cookiecutter:

   pipx install cookiecutter
   

2. Generate a new project:

   cruft create https://gitlab.com/roxautomation/templates/python-app-template
   

   Or locally:

   cookiecutter /path/to/python-app-template
   

3. The template will prompt for project details and automatically:

   • Initialize git repository
   • Set up uv environment
   • Run initial linting and formatting
   • Execute tests to verify setup

Template Variables

Variable	Description	Example
project_name	Human-readable project name	"My CLI App"
project_slug	Repository/directory name	"my-cli-app"
package_name	Python package name	"my_cli_app"
description	Short project description	"A modern CLI tool"
author_name	Author's full name	"Your Name"
author_email	Author's email	"your.email@example.com"
version	Initial version	"0.1.0"
python_version	Minimum Python version	"3.12"

Generated Project Structure

your-project/
├── README.md
├── pyproject.toml
├── tasks.py
├── src/
│   └── your_package/
│       ├── __init__.py
│       ├── py.typed
│       ├── cli/
│       │   ├── __init__.py
│       │   ├── app.py
│       │   ├── common.py
│       │   ├── config.py
│       │   └── hello.py
│       ├── config/
│       │   ├── __init__.py
│       │   ├── paths.py
│       │   └── settings.py
│       ├── commands/
│       │   ├── __init__.py
│       │   └── hello.py
│       ├── models/
│       │   └── __init__.py
│       └── utils/
│           ├── __init__.py
│           └── logging.py
├── tests/
│   ├── conftest.py
│   ├── test_public.py
│   └── test_internals.py
└── examples/
    └── config_init.sh

Development Workflow

Setup

uv sync --group dev

Code Quality

uv run ruff check src tests
uv run ruff format src tests
uv run mypy src
uv run invoke lint

Testing

uv run pytest
uv run invoke test

Template Development

To modify this template:

1. Edit files in {{cookiecutter.project_slug}}/
2. Update variables in cookiecutter.json
3. Modify the post-generation hook in hooks/post_gen_project.py
4. Test changes:

   cookiecutter . --output-dir /tmp
   

Requirements

• Python 3.12+
• uv (automatically installed during generation)
• git (for version control)

License

MIT License - see LICENSE file for details.