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) -> NoneFields and properties declared here; inherited members belong to the bases above.
name
Read-only property.
name: strnode_count
Read-only property.
node_count: intbuild
def build(*, default_style: RenderStyle = RenderStyle.SECTION) -> Documentbutton
def button(text: str, url: str) -> HtmlBuilderA link drawn as a button; url must be http(s) or mailto.
callout
def callout(text: str, *, tone: str = 'info', title: str | None = None) -> HtmlBuilderA boxed note; tone is info | success | warning | danger.
caption
def caption(text: str, *, fmt: TextFormat | None = None) -> HtmlBuildercolumns
def columns(n: int, *cells: Any, gap: str = '20px', widths: list[str] | None = None) -> HtmlBuilderdisclaimer
def disclaimer(text: str | None = None) -> HtmlBuilderdivider
def divider(*, thickness: str = '1px', color: str | None = None, margin: str = '16px') -> HtmlBuilderend_section
def end_section() -> HtmlBuilderfigure
def figure(fig: Any, *, fmt: PlotFormat | None = None, caption: str | None = None) -> HtmlBuilderfrontmatter
def frontmatter(**fields: Any) -> HtmlBuildergrid
def grid(*cells: Any, cols: int = 2, gap: str = '20px', row_gap: str | None = None) -> HtmlBuilderheading
def heading(text: str, *, level: int = 2, id: str | None = None, align: Align = Align.LEFT, fmt: TextFormat | None = None) -> HtmlBuilderimage
def image(src: Any, *, alt: str = '', width: str | None = None, fmt: ImageFormat | None = None) -> HtmlBuilderkpis
def kpis(*items: Kpi | tuple[str, Any]) -> HtmlBuilderA 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) -> HtmlBuilderraw_html
def raw_html(html: str) -> HtmlBuilderEmit 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) -> HtmlBuildersection
def section(title: str, *, id: str | None = None, collapsible: bool = False, show: bool = True, level: int = 2, render_figures: bool = True) -> HtmlBuilderspacer
def spacer(size: SpacerSize | str = SpacerSize.MD) -> HtmlBuilderstatus
def status(text: str, *, tone: str = 'info') -> HtmlBuilderA 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) -> HtmlBuildertext
def text(content: Any, *, fmt: TextFormat | str = 'prose', role: TextRole = TextRole.BODY) -> HtmlBuilderFunctions
col
def col(fn: Callable[[HtmlBuilder], Any], *, weight: int = 1, width: str | None = None, valign: VAlign = VAlign.TOP) -> CellBuild 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.'