briefing

Build beautiful, self-contained HTML reports from Python analysis.

Why briefing exists

Two libraries shaped how I thought about sharing data science work:

• datapane — the cleanest Python-native report builder I had ever used. Block-based, self-contained HTML output, dead-simple API. It was decommissioned in 2023 and the SaaS shut down shortly after.
• Facets (PAIR / Google) — specifically Facets Dive, a brilliant interactive dot explorer that let you slice any dataset visually with zero configuration. The project went largely unmaintained and quietly disappeared from most data science workflows.

I never found a substitute that matched either of them, let alone both at once. briefing is my attempt to fill that gap: a datapane-style block and layout system with a Facets Dive-class explorer built in, fully offline, no cloud account required.

Building briefing also serves a second purpose: it is a real-world, non-trivial Python project used to benchmark coding agents such as Claude Code. Designing a library from original source code — with concept ofblock hierarchy, rendering pipeline, theming, interactive components — gives a coding agent enough surface area to show where it genuinely helps and where it still struggles.

import briefing as bf

report = bf.Briefing(
    bf.Text("# Sales Analysis — Q1 2024"),
    bf.Group(
        bf.BigNumber("Revenue", "$4.2M", change="-12%", is_upward_change=False),
        bf.BigNumber("Active Users", "142K", change="+3%", is_upward_change=True),
        columns=2,
    ),
    bf.Select(
        bf.Plot(fig, label="Trend"),
        bf.DataTable(df, label="Raw Data"),
        bf.lab.DataProfile(df, label="Profile"),
    ),
    bf.lab.DataDive(df),
)

bf.save(report, "q1_analysis.html")

Features

• Self-contained HTML — zero CDN, works offline forever
• Zero visualisation dependencies in the core — the report grammar renders with only Jinja2 + markdown-it-py. Charts are opt-in (see below).
• Bring-your-own-figure Plot — hand it a Plotly, Altair, Matplotlib or Bokeh figure; briefing imports that library only when you pass its figure.
• Interactive tables — sortable, searchable DataTable with client-side pagination
• briefing.lab — richer custom visualisations (DataProfile column stats, DataDive Facets-style dot explorer), all hand-rolled SVG + vanilla JS, no CDN
• Themes — five built-in presets plus full CSS token control
• Pandas 2.x first-class support; PySpark via .toPandas()

Installation

pip install briefing                # core grammar + HTML renderer, no viz deps

Plot never imports a plotting library unless you actually pass it a figure from that library, so the extras only need to be installed for the backends you use.

Quick start

import pandas as pd
import briefing as bf

df = pd.read_csv("sales.csv")

bf.save(
    bf.Briefing(
        bf.Text("# My Report"),
        bf.DataTable(df),
    ),
    path="report.html",
    open=True,          # opens in browser immediately
)

To get an HTML string instead of writing a file (useful in Jupyter):

from IPython.display import HTML, display

display(HTML(bf.stringify(bf.Briefing(bf.Text("# Hello")))))

API

bf.save

bf.save(
    blocks,                  # Briefing, list, or a single block
    path,                    # destination file — e.g. "report.html"
    *,
    open=False,              # open in default browser after saving
    name="Report",           # browser tab title and report header
    formatting=None,         # Formatting instance — controls theme
)

bf.stringify

html: str = bf.stringify(
    blocks,
    *,
    name="Report",
    formatting=None,
)

Block reference

Text blocks

bf.Text — Markdown

bf.Text("# Heading\n\nSome **bold** and *italic* text.")

# From a .md file
bf.Text(file="notes.md")

Supports headings, bold, italics, inline code, blockquotes, tables, and lists.

bf.Code — Syntax-highlighted code

bf.Code("SELECT * FROM orders LIMIT 10", language="sql")
bf.Code(
    "import briefing as bf\nfl.save(bf.Briefing(bf.Text('# Hi')), 'out.html')",
    language="python",
    caption="Minimal report",
)

bf.Formula — LaTeX equation

bf.Formula(r"\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i", caption="Sample mean")

Rendered via MathJax (inlined in the report — no CDN needed).

bf.HTML — Raw HTML fragment

bf.HTML("<p style='color:#4F46E5'>Custom <strong>HTML</strong>.</p>")

Rendered inside a sandboxed container — inline styles work, scripts are stripped.

bf.BigNumber — KPI metric

bf.BigNumber("Revenue", "$4.2M", change="-12%", is_upward_change=False)
bf.BigNumber("Accuracy", 0.924)   # no change indicator

If change is provided without is_upward_change a warning is issued and no arrow is shown.

bf.Alert — Callout box

bf.Alert("Pipeline completed successfully.", level=bf.AlertLevel.SUCCESS)
bf.Alert("Margin erosion in South region.", level="warning", title="Watch")
bf.Alert("Legacy source decommissioned.", level=bf.AlertLevel.ERROR, title="Breaking change")

bf.AlertLevel values: INFO, SUCCESS, WARNING, ERROR.

Layout blocks

bf.Group — Grid layout

Arranges child blocks in a responsive column grid.

bf.Group(plot_a, plot_b, columns=2)
bf.Group(a, b, c, columns=3, widths=[2, 1, 1])   # relative column widths

bf.Select — Tabbed or dropdown panel switcher

Shows one child block at a time. Each child's label becomes the tab title.

bf.Select(
    bf.Plot(fig, label="Chart"),
    bf.DataTable(df, label="Data"),
    bf.lab.DataProfile(df, label="Profile"),
    type=bf.SelectType.TABS,       # or bf.SelectType.DROPDOWN
)

Warns if fewer than 2 children are provided.

bf.Toggle — Collapsible section

Collapsed by default; click the label to expand.

bf.Toggle(
    bf.Text("Methodology notes — hidden by default."),
    bf.Code("SELECT * FROM sales\n", language="sql"),
    label="Query details",
)

bf.Page — Top-level page tab

Use at the root of Briefing to create multi-page reports. Pages are converted to a top-level tab bar during rendering.

bf.Briefing(
    bf.Page(summary_group, title="Summary"),
    bf.Page(detail_group, title="Detail"),
)

Nested Page blocks are not supported — use Select and Group instead.

bf.Briefing — Root document container

Top-level wrapper passed to save. Accepts any combination of blocks.

report = bf.Briefing(
    bf.Text("# My Report"),
    bf.Plot(fig),
    bf.DataTable(df),
)
bf.save(report, "report.html")

Asset blocks

bf.Plot — Chart / figure

Library-agnostic chart block. Auto-detects the figure type at render time:

bf.Plot(plotly_fig, caption="Revenue over time")
bf.Plot(altair_chart, label="Chart", responsive=True)
bf.Plot(mpl_fig, scale=1.5)

bf.Table — Static table (pandas Styler)

Best for formatted DataFrames where you want to preserve Styler rules.

bf.Table(df)
bf.Table(
    df.style
      .format({"revenue": "€ {:,.0f}"})
      .bar(subset=["revenue"], color="#c7d2fe")
      .set_caption("Top 20 by revenue"),
)

bf.DataTable — Interactive table

Sortable, searchable, paginated table. Handles large datasets gracefully.

bf.DataTable(df, caption="Full sales dataset")
bf.DataTable(df, max_rows=500)   # cap at 500 rows

Lab blocks — briefing.lab

bf.lab.DataProfile — Column statistics

Renders one card per column with dtype, missing %, and a mini-chart.

• Numeric — mean, std, min/quartiles/max + inline histogram
• Categorical — n_unique, top values + inline bar chart
• Datetime — date range + gap detection

No extra dependencies — mini-charts are pure SVG.

bf.lab.DataProfile(df)
bf.lab.DataProfile(df, missing_threshold=0.05)   # red highlight at >5% missing
bf.lab.DataProfile(df, max_categories=10)        # cap top-N bars for categoricals

bf.lab.DataDive — Interactive dot explorer

Each DataFrame row becomes a dot. Dropdowns let the viewer dynamically change which columns drive X, Y, colour, and facets — similar to Google Facets Dive.

bf.lab.DataDive(df)                                              # auto-selects axes
bf.lab.DataDive(df, x="revenue", y="margin_pct", color="region")
bf.lab.DataDive(df, x="region", y="channel", color="product", layout="tile")

Theming

Pass a Formatting instance to save to control the visual style.

Built-in presets

bf.save(blocks, "out.html", formatting=bf.Formatting.dark())
bf.save(blocks, "out.html", formatting=bf.Formatting.corporate())
bf.save(blocks, "out.html", formatting=bf.Formatting.minimal())
bf.save(blocks, "out.html", formatting=bf.Formatting.ocean())
bf.save(blocks, "out.html", formatting=bf.Formatting.warm())

Fine-tuning a preset

Every preset accepts keyword overrides:

formatting=bf.Formatting.dark(accent_color="#f43f5e")   # dark theme, rose accent
formatting=bf.Formatting.corporate(width=bf.Width.FULL) # full-width corporate

Building from scratch

formatting=bf.Formatting(
    accent_color="#0369a1",
    bg_color="#f8fafc",
    surface_color="#e2e8f0",
    border_color="#cbd5e1",
    text_color="#0f172a",
    muted_color="#64748b",
    radius="0.25rem",
    width=bf.Width.NARROW,
)

Formatting token reference

bf.Width values: NARROW (768 px), MEDIUM (1200 px), FULL (100%).

Recipes

KPI dashboard with tabbed detail

import briefing as bf

bf.save(
    bf.Briefing(
        bf.Text("# Sales Analysis — 2023"),

        bf.Group(
            bf.BigNumber("Total Revenue", "€ 1 260 000", change="+12.4%", is_upward_change=True),
            bf.BigNumber("Units Sold",    "12 640",      change="+3.1%",  is_upward_change=True),
            bf.BigNumber("Avg Margin",    "31.2 %",      change="-0.8%",  is_upward_change=False),
            bf.BigNumber("Return Rate",   "8.0 %",       change="+0.2%",  is_upward_change=False),
            columns=4,
        ),

        bf.Alert("South region margin dropped below 25% in December.",
                 level=bf.AlertLevel.WARNING, title="Action needed"),

        bf.Select(
            bf.Group(bf.DataTable(by_region, caption="Region summary"), columns=1, label="By Region"),
            bf.Group(bf.DataTable(monthly,   caption="Monthly aggregates"), columns=1, label="Monthly"),
            bf.Group(bf.DataTable(df,        caption="All transactions"), columns=1, label="Raw Data"),
        ),

        bf.Text("## Column Profile"),
        bf.lab.DataProfile(df),

        bf.Text("## Interactive Explorer"),
        bf.lab.DataDive(df, x="revenue", y="margin_pct", color="region"),

        bf.Toggle(
            bf.Text("**Refresh cadence**: nightly at 02:00 UTC."),
            bf.Code("SELECT * FROM sales WHERE date >= '2023-01-01'\n", language="sql"),
            label="Methodology & sources",
        ),
    ),
    path="sales_2023.html",
    name="Sales Analysis — 2023",
    formatting=bf.Formatting(accent_color="#0f766e"),
)

Multi-library charts in one report

import matplotlib; matplotlib.use("Agg")
import matplotlib.pyplot as plt
import plotly.express as px
import briefing as bf

fig_plotly = px.scatter(df, x="revenue", y="margin_pct", color="region")

fig_mpl, ax = plt.subplots()
ax.hist(df["revenue"].dropna(), bins=30)

bf.save(
    bf.Briefing(
        bf.Text("# Chart comparison"),
        bf.Group(
            bf.Plot(fig_plotly, caption="Interactive (Plotly)"),
            bf.Plot(fig_mpl,    caption="Static SVG (Matplotlib)"),
            columns=2,
        ),
    ),
    path="charts.html",
)

Hiding methodology behind a toggle

bf.Toggle(
    bf.Text("""
        **Data source**: internal data warehouse.
        **Contact**: analytics@example.com
    """),
    bf.Code("SELECT date, region, revenue FROM dw.sales\n", language="sql"),
    label="Methodology & sources",
)

Tile layout (Facets Dive style)

# Each (region × channel) cell is a group of packed dots coloured by product
bf.lab.DataDive(df, x="region", y="channel", color="product", layout="tile")

Jupyter inline display

from IPython.display import HTML, display

display(HTML(bf.stringify(
    bf.Briefing(bf.Text("# Quick look"), bf.lab.DataProfile(df)),
    name="Quick look",
)))

Running the demo

cd /path/to/html_reporting_python
python demo/generate.py

This writes nine self-contained HTML files to demo/: