Python App Template

A batteries-included template for building Python data apps with Streamlit (interactive local dashboards), static HTML + Plotly.js (GitHub Pages), and CLI tooling (Click + Rich).

Quick Start

make setup          # Install everything with uv
make streamlit      # Launch Streamlit dashboard → localhost:8501
make serve          # Serve static HTML dashboard → localhost:8000
make cli ARGS="--help"  # CLI tools

What's Included

Category	Stack
Dashboards	Streamlit (interactive), Plotly.js HTML (static/deployable)
Data	pandas, numpy, polars
HTTP	httpx (async-ready, retry, rate-limit backoff)
CLI	Click + Rich (tables, progress, color)
Validation	Pydantic
Database	SQLAlchemy
Serialization	orjson (fast JSON)
Config	python-dotenv + TOML
Quality	ruff (lint + format), mypy (types), pytest (tests)
Package mgmt	uv

Structure

app/
├── api/client.py         # HTTP client with retry + pagination
├── services/             # Business logic (data pipelines, etc.)
├── utils/
│   ├── io.py             # CSV/JSON save/load helpers
│   ├── logging.py        # Rich structured logging
│   └── timing.py         # @timed decorator + timer context manager
├── cli.py                # Click CLI entry point
├── config.py             # Settings from .env + config.toml
└── streamlit_app.py      # Streamlit dashboard
scripts/                  # Standalone pipeline scripts
dashboard/                # Static HTML + Plotly.js (deploy to GitHub Pages)
tests/                    # pytest tests
data/                     # Generated outputs (git-ignored)

Commands

make setup       # Install all deps with uv
make setup-ml    # Also install scikit-learn, xgboost, lightgbm
make streamlit   # Run Streamlit app (hot-reload enabled)
make serve       # Serve static dashboard
make cli ARGS="" # Run CLI (e.g. ARGS="pipeline -n 1000")
make script SCRIPT=example  # Run a script from scripts/
make lint        # Check with ruff
make format      # Auto-fix with ruff
make typecheck   # Run mypy
make test        # Run pytest
make test-cov    # Run pytest with coverage
make clean       # Remove .venv and caches
make help        # Show all targets

Using as a Template

1. Click "Use this template" on GitHub (or clone and remove .git)
2. Find-and-replace my-app with your project name in pyproject.toml
3. cp .env.example .env and add your keys
4. make setup and start building

Optional ML Setup

make setup-ml

Adds scikit-learn, xgboost, and lightgbm for machine learning workflows.