Skip to content

common_reports.builders.builder

HtmlBuilder — the fluent builder. One add-call per component, fully inline options (.plot(data, type=..., fmt=...)); each call returns self (chainable); .build() freezes the accumulated nodes into an immutable Document.

The builder is a transient mutable accumulator; the OUTPUT (Document) is frozen — that is where the immutability law binds. Sections use an open-section cursor (.section … .end_section; auto-closes on the next .section or .build); layout containers (.row/.columns/.grid) use col(...) sub-builders.

Source/spec: COMMON-HTML-BUILDER-API.md §1 + the source-verified build-spec §3.5.

Classes

HtmlBuilder

Accumulates frozen component nodes; .build() -> immutable Document.

__init__

def __init__(name: str, *, theme: Theme = DEFAULT_THEME) -> None

Fields and properties declared here; inherited members belong to the bases above.

name

Read-only property.

name: str

node_count

Read-only property.

node_count: int

build

def build(*, default_style: RenderStyle = RenderStyle.SECTION) -> Document

button

def button(text: str, url: str) -> HtmlBuilder

A link drawn as a button; url must be http(s) or mailto.

callout

def callout(text: str, *, tone: str = 'info', title: str | None = None) -> HtmlBuilder

A boxed note; tone is info | success | warning | danger.

caption

def caption(text: str, *, fmt: TextFormat | None = None) -> HtmlBuilder

columns

def columns(n: int, *cells: Any, gap: str = '20px', widths: list[str] | None = None) -> HtmlBuilder

disclaimer

def disclaimer(text: str | None = None) -> HtmlBuilder

divider

def divider(*, thickness: str = '1px', color: str | None = None, margin: str = '16px') -> HtmlBuilder

end_section

def end_section() -> HtmlBuilder

figure

def figure(fig: Any, *, fmt: PlotFormat | None = None, caption: str | None = None) -> HtmlBuilder

frontmatter

def frontmatter(**fields: Any) -> HtmlBuilder

grid

def grid(*cells: Any, cols: int = 2, gap: str = '20px', row_gap: str | None = None) -> HtmlBuilder

heading

def heading(text: str, *, level: int = 2, id: str | None = None, align: Align = Align.LEFT, fmt: TextFormat | None = None) -> HtmlBuilder

image

def image(src: Any, *, alt: str = '', width: str | None = None, fmt: ImageFormat | None = None) -> HtmlBuilder

kpis

def kpis(*items: Kpi | tuple[str, Any]) -> HtmlBuilder

A row of headline-number tiles: Kpi(...) or (label, value) pairs.

plot

def plot(data: pandas.DataFrame, *, type: PlotType, fmt: PlotFormat | None = None, caption: str | None = None, id: str | None = None) -> HtmlBuilder

raw_html

def raw_html(html: str) -> HtmlBuilder

Emit trusted HTML verbatim (RAW role — never escaped). The caller owns sanitization. For untrusted/caller text use .text(), which escapes.

row

def row(*cells: Any, gap: str = '20px', align: VAlign = VAlign.TOP, wrap: bool = True) -> HtmlBuilder

section

def section(title: str, *, id: str | None = None, collapsible: bool = False, show: bool = True, level: int = 2, render_figures: bool = True) -> HtmlBuilder

spacer

def spacer(size: SpacerSize | str = SpacerSize.MD) -> HtmlBuilder

status

def status(text: str, *, tone: str = 'info') -> HtmlBuilder

A small status tag (FILLED, REJECTED, LIVE); tones as for callout.

table

def table(data: pandas.DataFrame, *, fmt: TableFormat | None = None, caption: str | None = None, id: str | None = None) -> HtmlBuilder

text

def text(content: Any, *, fmt: TextFormat | str = 'prose', role: TextRole = TextRole.BODY) -> HtmlBuilder

Functions

col

def col(fn: Callable[[HtmlBuilder], Any], *, weight: int = 1, width: str | None = None, valign: VAlign = VAlign.TOP) -> Cell

Build a layout Cell from a thunk that receives a fresh sub-builder.

Types and values

DEFAULT_DISCLAIMER

DEFAULT_DISCLAIMER = 'Past performance is not indicative of future results. This material is for informational purposes only and does not constitute investment advice or an offer to buy or sell any security.'