Skip to content

Commit b1e58b1

Browse files
0xr3x0xr3x
authored
feat: initial boilerplate with marimo, polars, and altair
Our last python template was trying to do too many things. This is a much simpler template intended for research notebook explorations
2 parents b6de7b1 + f01fa29 commit b1e58b1

File tree

11 files changed

+1728
-2
lines changed

11 files changed

+1728
-2
lines changed

‎.env.example‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Environment Configuration
2+
# Copy this file to .env and fill in your values
3+
4+
# Example: API keys for data sources
5+
# API_KEY=your_api_key_here
6+
7+
# Example: Database connection
8+
# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
9+
10+
# Example: Data paths
11+
# DATA_PATH=/path/to/your/data

‎.github/workflows/ci.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, dev]
6+
pull_request:
7+
branches: [main, dev]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
# Commit message linting (conventional commits)
15+
commitlint:
16+
name: Commit Lint
17+
runs-on: ubuntu-latest
18+
if: github.event_name == 'pull_request'
19+
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
with:
24+
fetch-depth: 0
25+
26+
- name: Install uv
27+
uses: astral-sh/setup-uv@v4
28+
with:
29+
version: "latest"
30+
31+
- name: Set up Python
32+
run: uv python install 3.12
33+
34+
- name: Install dependencies
35+
run: uv sync
36+
37+
- name: Check commit messages
38+
run: |
39+
# Check all commits in the PR
40+
uv run cz check --rev-range origin/${{ github.base_ref }}..HEAD
41+
42+
# Code quality checks
43+
lint:
44+
name: Lint & Format
45+
runs-on: ubuntu-latest
46+
47+
steps:
48+
- name: Checkout
49+
uses: actions/checkout@v4
50+
51+
- name: Install uv
52+
uses: astral-sh/setup-uv@v4
53+
with:
54+
version: "latest"
55+
56+
- name: Set up Python
57+
run: uv python install 3.12
58+
59+
- name: Install dependencies
60+
run: uv sync
61+
62+
- name: Check formatting
63+
run: uv run ruff format --check .
64+
65+
- name: Run linter
66+
run: uv run ruff check .

‎.gitignore‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
23+
# Virtual environments
24+
.venv/
25+
venv/
26+
ENV/
27+
28+
# uv
29+
.uv/
30+
31+
# Environment variables
32+
.env
33+
.env.local
34+
.env.*.local
35+
36+
# Data files (keep the directory, ignore contents)
37+
data/*
38+
!data/.gitkeep
39+
40+
# IDE
41+
.idea/
42+
.vscode/
43+
*.swp
44+
*.swo
45+
*~
46+
47+
# OS
48+
.DS_Store
49+
Thumbs.db
50+
51+
# Jupyter (in case)
52+
.ipynb_checkpoints/
53+
54+
# Marimo outputs
55+
*.html
56+
output/
57+
58+
# Logs
59+
*.log
60+
61+
# Coverage
62+
.coverage
63+
htmlcov/
64+

‎.pre-commit-config.yaml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
repos:
2+
- repo: https://github.com/astral-sh/ruff-pre-commit
3+
rev: v0.8.0
4+
hooks:
5+
# Run the formatter
6+
- id: ruff-format
7+
# Run the linter
8+
- id: ruff
9+
args: [--fix, --exit-non-zero-on-fix]
10+
11+
- repo: https://github.com/pre-commit/pre-commit-hooks
12+
rev: v5.0.0
13+
hooks:
14+
- id: trailing-whitespace
15+
- id: end-of-file-fixer
16+
- id: check-yaml
17+
- id: check-added-large-files
18+
args: ["--maxkb=1000"]
19+
20+
# Commit message linting (conventional commits)
21+
- repo: https://github.com/commitizen-tools/commitizen
22+
rev: v4.1.0
23+
hooks:
24+
- id: commitizen
25+
stages: [commit-msg]
26+

‎LICENSE‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2026 Wonderland
3+
Copyright (c) 2025 Wonderland
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1919
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
2121
SOFTWARE.
22+

‎README.md‎

Lines changed: 169 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,169 @@
1-
# python-notebook-boilerplate
1+
# python-notebook-boilerplate
2+
3+
Made with ♥ by Wonderland (https://defi.sucks)
4+
5+
Data exploration boilerplate using Marimo notebooks, Polars, and Altair.
6+
7+
## Features
8+
9+
- **[Marimo](https://marimo.io/)** - Reactive Python notebooks as pure `.py` files
10+
- **[Polars](https://pola.rs/)** - Fast DataFrame library (Rust-powered)
11+
- **[Altair](https://altair-viz.github.io/)** - Declarative statistical visualization
12+
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
13+
- **Ruff** - Linting and formatting
14+
- **Pre-commit hooks** - Code quality checks
15+
- **[Commitizen](https://commitizen-tools.github.io/commitizen/)** - Conventional commits enforcement
16+
- **GitHub Actions CI** - Automated linting and commit validation
17+
18+
## Quick Start
19+
20+
### Prerequisites
21+
22+
- Python 3.12+
23+
- [uv](https://docs.astral.sh/uv/getting-started/installation/):
24+
25+
```bash
26+
curl -LsSf https://astral.sh/uv/install.sh | sh
27+
```
28+
29+
### Setup
30+
31+
```bash
32+
# Clone the repo
33+
git clone https://github.com/defi-wonderland/python-notebook-boilerplate.git
34+
cd python-notebook-boilerplate
35+
36+
# Install dependencies
37+
uv sync
38+
39+
# Setup environment variables
40+
cp .env.example .env
41+
42+
# Install pre-commit hooks (including commit message linting)
43+
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
44+
45+
# Start exploring!
46+
uv run marimo edit notebooks/example.py
47+
```
48+
49+
## Usage
50+
51+
### Editing Notebooks
52+
53+
Open a notebook in the interactive editor:
54+
55+
```bash
56+
uv run marimo edit notebooks/example.py
57+
```
58+
59+
### Sharing as Web App
60+
61+
Serve a notebook as an interactive web application:
62+
63+
```bash
64+
uv run marimo run notebooks/example.py
65+
```
66+
67+
Others can interact with it in their browser without needing Python installed.
68+
69+
### Export Options
70+
71+
```bash
72+
# Export to static HTML
73+
uv run marimo export html notebooks/example.py -o output.html
74+
75+
# Export to WASM (runs entirely in browser)
76+
uv run marimo export html-wasm notebooks/example.py -o output/
77+
```
78+
79+
## Project Structure
80+
81+
```
82+
python-notebook-boilerplate/
83+
├── .github/
84+
│ └── workflows/
85+
│ └── ci.yml # Format + lint checks
86+
├── notebooks/
87+
│ └── example.py # Sample marimo notebook
88+
├── src/
89+
│ └── helpers/ # Shared utility functions
90+
│ └── __init__.py
91+
├── data/ # Local data (gitignored)
92+
│ └── .gitkeep
93+
├── .env.example # Environment template
94+
├── .pre-commit-config.yaml # Pre-commit hooks
95+
├── pyproject.toml # Dependencies + tool config
96+
└── README.md
97+
```
98+
99+
## Development
100+
101+
### Code Quality
102+
103+
```bash
104+
# Format code
105+
uv run ruff format .
106+
107+
# Lint code
108+
uv run ruff check .
109+
110+
# Lint and auto-fix
111+
uv run ruff check . --fix
112+
113+
# Run all pre-commit checks
114+
uv run pre-commit run --all-files
115+
```
116+
117+
### Commits
118+
119+
This project uses [Conventional Commits](https://www.conventionalcommits.org/). Commit messages are validated locally via pre-commit hooks and in CI.
120+
121+
```bash
122+
# Interactive commit (recommended)
123+
uv run cz commit
124+
125+
# Or write manually following the format:
126+
# <type>(<scope>): <subject>
127+
#
128+
# Examples:
129+
# feat: add new data loader
130+
# fix(charts): resolve axis scaling issue
131+
# docs: update README with examples
132+
```
133+
134+
**Allowed types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
135+
136+
### Adding Dependencies
137+
138+
```bash
139+
# Add a production dependency
140+
uv add pandas
141+
142+
# Add a dev dependency
143+
uv add --dev pytest
144+
```
145+
146+
## CI
147+
148+
This repo includes GitHub Actions CI that runs on every push and PR:
149+
150+
- **Commit lint** - Validates commit messages follow Conventional Commits (PRs only)
151+
- **Format check** - Ensures code is formatted with Ruff
152+
- **Lint** - Static analysis with Ruff
153+
154+
## Creating New Notebooks
155+
156+
```bash
157+
# Create a new notebook
158+
uv run marimo edit notebooks/my-analysis.py
159+
```
160+
161+
Marimo notebooks are pure Python files, so they:
162+
- Work with git (no JSON merge conflicts)
163+
- Can be imported as modules
164+
- Can be run as scripts
165+
166+
## License
167+
168+
MIT - See [LICENSE](LICENSE)
169+

‎data/.gitkeep‎

Whitespace-only changes.

0 commit comments

Comments
 (0)