Skip to content

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

Terminal window
uv add "common-reports[gmail]" # email through the Gmail API (Google Workspace)
uv add "common-reports[builders,gmail]" # + tables, charts and chart images
ExtraAddsNeeded for
(none)pydantic, structlog, common-coreSMTP email, alert-style documents (text, callouts, buttons)
gmailgoogle-api-python-client, google-authEMAIL_BACKEND=gmail. Without it every Gmail send fails.
builderspandas, plotly, kaleidotables, 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

NeedUseGuide
Send an email, pick the provider by environmentEmailClient.from_env("EMAIL")Email delivery
Build a report or an alert emailHtmlBuilder → DocumentDocuments
Branded modern look, interactive page, brand switchEmailRenderer(style="modern"), BrandStyles 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 mailboxEmailClient.search, reply, drafts, labelsEmail 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.