Recipes
An alert email
Build the alert with the builder directly; there is no alert template. Each application knows its own facts: what failed, where to look, what to do. The Schwab gateway and the Dagster run-failure sensor both follow this shape.
from common_reports import EmailClient, EmailRenderer, HtmlBuilder
def send_run_failed(job: str, run_id: str, error: str, started: str) -> bool: b = HtmlBuilder(f"{job} failed") b.frontmatter(title=f"Run failed: {job}", date=started) b.status("Failed", tone="danger") b.text(f"Job: {job}\nRun: `{run_id}`\nStarted: {started}", fmt="kv") b.callout(error[:1500], tone="danger", title="Error") b.button("Open the run in Dagster", f"https://dagster.tail005531.ts.net/runs/{run_id}") b.caption("Links work on the tailnet only.") email = b.build().render(EmailRenderer(style="modern", preheader=f"{job} failed"))
result = EmailClient.from_env("EMAIL").send( ["ops@example.com"], f"[NC ALERT] {job} failed", html=email.html, attachments=email.attachments, ) return result.successGuidelines:
- Order. Put the status first, then the facts as
kvlines, then the error in adangercallout, then one button for the next action. - Error length. Cap the error text; a stack trace can run to many kilobytes.
- Imports. An alert needs only the base install plus
gmail; nobuildersextra. - Delivery. Return or log
result.success. An alert that failed to send must not look sent.
A daily report with an interactive page attached
from pathlib import Path
from common_reports import EmailClient, EmailRenderer, HtmlBuilderfrom common_reports.contracts.builders import Kpi, NumberFormat, PlotFormat, PlotType, Transformfrom common_reports.contracts.emails import Attachment
def daily_report(nav, pnl, positions, returns, day: str) -> bool: b = HtmlBuilder("Daily Report") b.frontmatter(title="Daily Report", date=day, preheader=f"P&L {pnl:+,.0f}") b.kpis( Kpi("NAV", nav, fmt=NumberFormat.DOLLAR), Kpi("Day P&L", pnl, fmt=NumberFormat.DOLLAR), Kpi("Positions", len(positions), fmt=NumberFormat.INT), ) b.section("Performance") b.plot( returns, type=PlotType.CUMULATIVE, fmt=PlotFormat(strat_cols=("Genesis",), bench_cols=("SPY",), transform=Transform.CUM), ) b.section("Positions") b.table(positions) b.disclaimer() doc = b.build()
page = doc.to_html(style="modern", date=day).save(Path(f"out/report-{day}.html")) email = doc.to_email(style="modern") result = EmailClient.from_env("EMAIL").send( ["partners@example.com"], f"Daily Report · {day}", html=email.html, attachments=[*email.attachments, Attachment.from_path(page)], ) return result.successThe email shows the “Interactive report attached” box because a file is attached.
Reuse one layout across runs
Build the frame once with {placeholders}, then fill it per run. Placeholders fill text,
headings, captions, callouts, status tags, buttons and KPI labels; frontmatter is not
filled, so pass per-run titles to the renderer instead.
frame = ( HtmlBuilder("Rebalance") .heading("Rebalance {date}") .status("{state}", tone="success") .text("{orders} orders sent to {broker}.") .build())doc = frame.fill(date="30 Sep 2026", state="Filled", orders=12, broker="IBKR")assert not doc.unfilledTest without sending
Rendering needs no network, so a unit test can assert on the HTML:
doc = HtmlBuilder("t").button("Open the run in Dagster", "https://dagster.example/runs/1").build()email = doc.render(EmailRenderer(style="modern"))assert "Open the run in Dagster" in email.htmlassert email.manifest["gmail_clip_risk"] is FalseTo test the send path, patch EmailClient.from_env to return a fake whose send
returns SendResult(success=True) or SendResult(success=False, error="..."). Cover
both outcomes.