Reports
common-reports does two jobs:
- It builds report documents: headline numbers, tables, finance charts and layouts. Each document renders as an email, a standalone interactive page or a Ghost post.
- It sends email through one client, whichever provider is configured.
The container owns the content of its reports; this package owns how they look and how they are delivered.
Installation
uv add "common-reports[gmail]" # email through the Gmail API (Google Workspace)uv add "common-reports[builders,gmail]" # + tables, charts and chart images| Extra | Adds | Needed for |
|---|---|---|
| (none) | pydantic, structlog, common-core | SMTP email, alert-style documents (text, callouts, buttons) |
gmail | google-api-python-client, google-auth | EMAIL_BACKEND=gmail. Without it every Gmail send fails. |
builders | pandas, plotly, kaleido | tables, charts, chart images |
import common_reports never loads pandas, Plotly or the Google client and never touches
the network.
Quick start
from common_reports import EmailClient, EmailRenderer, HtmlBuilder
email = ( HtmlBuilder("Portfolio Report") .frontmatter(title="Portfolio Report", date="30 Sep 2026") .callout("All orders **filled**.", tone="success", title="Run complete") .section("Positions") .table(positions_df) .build() .render(EmailRenderer(style="modern")))
result = EmailClient.from_env("EMAIL").send( to=["partner@example.com"], subject="Portfolio Report · 30 Sep 2026", html=email.html, attachments=email.attachments, # the crest and chart images travel as inline parts)if not result.success: raise RuntimeError(f"{result.provider}: {result.error_type}: {result.error}")Choose the entry point
| Need | Use | Guide |
|---|---|---|
| Send an email, pick the provider by environment | EmailClient.from_env("EMAIL") | Email delivery |
| Build a report or an alert email | HtmlBuilder → Document | Documents |
| Branded modern look, interactive page, brand switch | EmailRenderer(style="modern"), Brand | Styles and brands |
| Performance, attribution, risk charts | .plot(df, type=PlotType...) | Charts |
| Worked patterns (alert, daily report, report file) | — | Recipes |
| Read, search or reply in a mailbox | EmailClient.search, reply, drafts, labels | Email delivery |
Compatibility
EmailRenderer() with no arguments (style="classic") and every existing send call
produce the same bytes as release 0.1.4–0.1.6. Parity tests pin this. The modern look,
the new components and the finance charts are all opt-in.