common_reports.contracts.builders.components
Frozen component tree — the immutable nodes a builder accumulates and a renderer
interprets via the visitor pattern: each node’s accept dispatches to the
renderer’s visit_<type>.
Pure data + visitor dispatch only — components NEVER contain rendering logic and renderers NEVER mutate components. Source-verified against AlgoReports (report_template_v2 / email_report_template / sheet_utils section assembly).
Classes
Button
A link drawn as a button (http, https or mailto only).
__init__
def __init__(text: str, url: str, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
id
id: str | None = Nonetext
text: strurl
url: straccept
def accept(renderer: Any) -> strCallout
A boxed note. tone: info | success | warning | danger.
__init__
def __init__(text: str, tone: str = 'info', title: str | None = None, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
id
id: str | None = Nonetext
text: strtitle
title: str | None = Nonetone
tone: str = 'info'accept
def accept(renderer: Any) -> strCell
__init__
def __init__(children: tuple[Component, ...] = (), weight: int = 1, width: str | None = None, valign: VAlign = VAlign.TOP, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
children
children: tuple[Component, ...] = ()id
id: str | None = Nonevalign
valign: VAlign = VAlign.TOPweight
weight: int = 1width
width: str | None = Noneaccept
def accept(renderer: Any) -> strColumns
__init__
def __init__(n: int = 2, cells: tuple[Cell, ...] = (), gap: str = '20px', widths: tuple[str, ...] | None = None, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
cells
cells: tuple[Cell, ...] = ()gap
gap: str = '20px'id
id: str | None = Nonen
n: int = 2widths
widths: tuple[str, ...] | None = Noneaccept
def accept(renderer: Any) -> strComponent
Bases: Protocol
Structural base — every node carries an id and accepts a renderer.
id is read-only here: nodes are frozen value objects.
Fields and properties declared here; inherited members belong to the bases above.
id
Read-only property.
id: str | Noneaccept
def accept(renderer: Any) -> strDivider
__init__
def __init__(thickness: str = '1px', color: str | None = None, margin: str = '16px', id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
color
color: str | None = Noneid
id: str | None = Nonemargin
margin: str = '16px'thickness
thickness: str = '1px'accept
def accept(renderer: Any) -> strFigure
__init__
def __init__(data: pandas.DataFrame | None = None, type: PlotType | None = None, fmt: PlotFormat = PlotFormat(), prebuilt: go.Figure | None = None, caption: str | None = None, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
caption
caption: str | None = Nonedata
data: pandas.DataFrame | None = Nonefmt
fmt: PlotFormat = PlotFormat()id
id: str | None = Noneprebuilt
prebuilt: go.Figure | None = Nonetype
type: PlotType | None = Noneaccept
def accept(renderer: Any) -> strFrontmatter
__init__
def __init__(fields: Mapping[str, Any] = dict(), id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
fields
fields: Mapping[str, Any] = field(default_factory=dict)id
id: str | None = Noneaccept
def accept(renderer: Any) -> strGrid
__init__
def __init__(cells: tuple[Cell, ...] = (), cols: int = 2, gap: str = '20px', row_gap: str | None = None, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
cells
cells: tuple[Cell, ...] = ()cols
cols: int = 2gap
gap: str = '20px'id
id: str | None = Nonerow_gap
row_gap: str | None = Noneaccept
def accept(renderer: Any) -> strHeading
__init__
def __init__(text: str, level: int = 2, fmt: TextFormat = TextFormat(), align: Align = Align.LEFT, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
align
align: Align = Align.LEFTfmt
fmt: TextFormat = TextFormat()id
id: str | None = Nonelevel
level: int = 2text
text: straccept
def accept(renderer: Any) -> strImage
__init__
def __init__(src: Any, alt: str = '', width: str | None = None, fmt: ImageFormat = ImageFormat(), id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
alt
alt: str = ''fmt
fmt: ImageFormat = ImageFormat()id
id: str | None = Nonesrc
src: Anywidth
width: str | None = Noneaccept
def accept(renderer: Any) -> strKpi
One headline number: value (a number formatted by fmt, or text),
an optional signed change (formatted by change_fmt), any number of
compare lines — (label, signed value) pairs such as ("Nasdaq", 0.0081),
each drawn as a coloured arrow line — and a note. With signed=True the
headline is itself a change (a day’s return): drawn with its sign in the up/down
colour (the compare lines keep their arrows).
__init__
def __init__(label: str, value: Any, fmt: NumberFormat | None = None, change: float | None = None, change_fmt: NumberFormat = NumberFormat.PERCENT, note: str | None = None, decimals: int = 2, trend: tuple[float, ...] = (), compare: tuple[tuple[str, float], ...] = (), signed: bool = False) -> NoneFields and properties declared here; inherited members belong to the bases above.
change
change: float | None = Nonechange_fmt
change_fmt: NumberFormat = NumberFormat.PERCENTcompare
compare: tuple[tuple[str, float], ...] = ()decimals
decimals: int = 2fmt
fmt: NumberFormat | None = Nonelabel
label: strnote
note: str | None = Nonesigned
signed: bool = Falsetrend
trend: tuple[float, ...] = ()value
value: AnyKpis
A row of headline-number tiles.
__init__
def __init__(items: tuple[Kpi, ...] = (), id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
id
id: str | None = Noneitems
items: tuple[Kpi, ...] = ()accept
def accept(renderer: Any) -> strRenderStyle
Bases: Enum
Fields and properties declared here; inherited members belong to the bases above.
FRONTMATTER
FRONTMATTER = 'frontmatter'SECTION
SECTION = 'section'XML
XML = 'xml'Row
__init__
def __init__(cells: tuple[Cell, ...] = (), gap: str = '20px', align: VAlign = VAlign.TOP, wrap: bool = True, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
align
align: VAlign = VAlign.TOPcells
cells: tuple[Cell, ...] = ()gap
gap: str = '20px'id
id: str | None = Nonewrap
wrap: bool = Trueaccept
def accept(renderer: Any) -> strSection
__init__
def __init__(title: str, children: tuple[Component, ...] = (), level: int = 2, collapsible: bool = False, show: bool = True, render_figures: bool = True, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
children
children: tuple[Component, ...] = ()collapsible
collapsible: bool = Falseid
id: str | None = Nonelevel
level: int = 2render_figures
render_figures: bool = Trueshow
show: bool = Truetitle
title: straccept
def accept(renderer: Any) -> strSpacer
__init__
def __init__(size: SpacerSize | str = SpacerSize.MD, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
id
id: str | None = Nonesize
size: SpacerSize | str = SpacerSize.MDaccept
def accept(renderer: Any) -> strStatus
A small status tag (FILLED, REJECTED, LIVE). tone as for :class:Callout.
__init__
def __init__(text: str, tone: str = 'info', id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
id
id: str | None = Nonetext
text: strtone
tone: str = 'info'accept
def accept(renderer: Any) -> strTable
__init__
def __init__(data: pandas.DataFrame, fmt: TableFormat = TableFormat(), caption: str | None = None, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
caption
caption: str | None = Nonedata
data: pandas.DataFramefmt
fmt: TableFormat = TableFormat()id
id: str | None = Noneaccept
def accept(renderer: Any) -> strText
__init__
def __init__(content: str, role: TextRole = TextRole.BODY, fmt: TextFormat = TextFormat(), safe: bool = False, id: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
content
content: strfmt
fmt: TextFormat = TextFormat()id
id: str | None = Nonerole
role: TextRole = TextRole.BODYsafe
safe: bool = Falseaccept
def accept(renderer: Any) -> strFunctions
slug
def slug(text: str) -> strAnchor slug: lowercase, non-alnum -> ’-’ (matches report_template_v2 anchors).