Python template (Notebooks)

Data exploration boilerplate using Marimo notebooks, Polars, and Altair.

Project Structure

python-notebook-boilerplate/
├── .github/
│   └── workflows/
│       └── ci.yml              # Format + lint checks
├── notebooks/
│   └── example.py              # Sample marimo notebook
├── src/
│   └── helpers/                # Shared utility functions
│       └── __init__.py
├── data/                       # Local data (gitignored)
│   └── .gitkeep
├── .env.example                # Environment template
├── .pre-commit-config.yaml     # Pre-commit hooks
├── pyproject.toml              # Dependencies + tool config
└── README.md

Quick Start

Prerequisites

• Python 3.12+
• uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Setup

# Clone the repo
git clone [email protected]:defi-wonderland/python-notebook-boilerplate
cd python-notebook-boilerplate

# Install dependencies
uv sync

# Setup environment variables
cp .env.example .env

# Install pre-commit hooks (including commit message linting)
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg

# Start exploring!
uv run marimo edit notebooks/example.py

Usage

Creating New Notebooks

# Create a new notebook
uv run marimo edit notebooks/alice.py

Editing Notebooks

Open a notebook in the interactive editor:

uv run marimo edit notebooks/example.py

Sharing as Web App

Serve a notebook as an interactive web application:

uv run marimo run notebooks/example.py

Others can interact with it in their browser without needing Python installed.

Export Options

# Export to static HTML
uv run marimo export html notebooks/example.py -o output.html

# Export to WASM (runs entirely in browser)
uv run marimo export html-wasm notebooks/example.py -o output/

Development

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Lint and auto-fix
uv run ruff check . --fix

# Run all pre-commit checks
uv run pre-commit run --all-files

Commits

This project uses Conventional Commits. Commit messages are validated locally via pre-commit hooks and in CI.

# Interactive commit (recommended)
uv run cz commit

# Or write manually following the format:
# <type>(<scope>): <subject>
#
# Examples:
#   feat: add new data loader
#   fix(charts): resolve axis scaling issue
#   docs: update README with examples

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Adding Dependencies

# Add a production dependency
uv add pandas

# Add a dev dependency
uv add --dev pytest

CI

This repo includes GitHub Actions CI that runs on every push and PR:

• Commit lint - Validates commit messages follow Conventional Commits (PRs only)
• Format check - Ensures code is formatted with Ruff
• Lint - Static analysis with Ruff