python-cli-template/README.md

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_build backend and lockfile-first reproducibility
• Ruff for linting/formatting
• MyPy strict mode
• 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. Post-generation hook runs uv lock to create uv.lock.

4. Bootstrap the generated project:

   uv sync --frozen --group dev
   uv run invoke lint
   uv run invoke test
   

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 is fixed to 3.12+ by template policy.

Generated Project Structure

your-project/
├── README.md
├── pyproject.toml
├── tasks.py
├── uv.lock
├── 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_cli.py
│   ├── test_internals.py
│   └── test_public.py
└── examples/
    └── config_init.sh

Development Workflow

Setup

uv sync --frozen --group dev

Code Quality

uv run ruff check src tests
uv run ruff format --check 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:

   ./test.sh
   

Requirements

• Python 3.12+
• uv
• cruft or cookiecutter
• git (optional, for your project workflow)

License

MIT License - see LICENSE file for details.