Skip to content

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) -> None

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

id

id: str | None = None

text

text: str

url

url: str

accept

def accept(renderer: Any) -> str

Callout

A boxed note. tone: info | success | warning | danger.

__init__

def __init__(text: str, tone: str = 'info', title: str | None = None, id: str | None = None) -> None

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

id

id: str | None = None

text

text: str

title

title: str | None = None

tone

tone: str = 'info'

accept

def accept(renderer: Any) -> str

Cell

__init__

def __init__(children: tuple[Component, ...] = (), weight: int = 1, width: str | None = None, valign: VAlign = VAlign.TOP, id: str | None = None) -> None

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

children

children: tuple[Component, ...] = ()

id

id: str | None = None

valign

valign: VAlign = VAlign.TOP

weight

weight: int = 1

width

width: str | None = None

accept

def accept(renderer: Any) -> str

Columns

__init__

def __init__(n: int = 2, cells: tuple[Cell, ...] = (), gap: str = '20px', widths: tuple[str, ...] | None = None, id: str | None = None) -> None

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

cells

cells: tuple[Cell, ...] = ()

gap

gap: str = '20px'

id

id: str | None = None

n

n: int = 2

widths

widths: tuple[str, ...] | None = None

accept

def accept(renderer: Any) -> str

Component

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 | None

accept

def accept(renderer: Any) -> str

Divider

__init__

def __init__(thickness: str = '1px', color: str | None = None, margin: str = '16px', id: str | None = None) -> None

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

color

color: str | None = None

id

id: str | None = None

margin

margin: str = '16px'

thickness

thickness: str = '1px'

accept

def accept(renderer: Any) -> str

Figure

__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) -> None

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

caption

caption: str | None = None

data

data: pandas.DataFrame | None = None

fmt

fmt: PlotFormat = PlotFormat()

id

id: str | None = None

prebuilt

prebuilt: go.Figure | None = None

type

type: PlotType | None = None

accept

def accept(renderer: Any) -> str

Frontmatter

__init__

def __init__(fields: Mapping[str, Any] = dict(), id: str | None = None) -> None

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

fields

fields: Mapping[str, Any] = field(default_factory=dict)

id

id: str | None = None

accept

def accept(renderer: Any) -> str

Grid

__init__

def __init__(cells: tuple[Cell, ...] = (), cols: int = 2, gap: str = '20px', row_gap: str | None = None, id: str | None = None) -> None

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

cells

cells: tuple[Cell, ...] = ()

cols

cols: int = 2

gap

gap: str = '20px'

id

id: str | None = None

row_gap

row_gap: str | None = None

accept

def accept(renderer: Any) -> str

Heading

__init__

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

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

align

align: Align = Align.LEFT

fmt

fmt: TextFormat = TextFormat()

id

id: str | None = None

level

level: int = 2

text

text: str

accept

def accept(renderer: Any) -> str

Image

__init__

def __init__(src: Any, alt: str = '', width: str | None = None, fmt: ImageFormat = ImageFormat(), id: str | None = None) -> None

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

alt

alt: str = ''

fmt

fmt: ImageFormat = ImageFormat()

id

id: str | None = None

src

src: Any

width

width: str | None = None

accept

def accept(renderer: Any) -> str

Kpi

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) -> None

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

change

change: float | None = None

change_fmt

change_fmt: NumberFormat = NumberFormat.PERCENT

compare

compare: tuple[tuple[str, float], ...] = ()

decimals

decimals: int = 2

fmt

fmt: NumberFormat | None = None

label

label: str

note

note: str | None = None

signed

signed: bool = False

trend

trend: tuple[float, ...] = ()

value

value: Any

Kpis

A row of headline-number tiles.

__init__

def __init__(items: tuple[Kpi, ...] = (), id: str | None = None) -> None

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

id

id: str | None = None

items

items: tuple[Kpi, ...] = ()

accept

def accept(renderer: Any) -> str

RenderStyle

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) -> None

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

align

align: VAlign = VAlign.TOP

cells

cells: tuple[Cell, ...] = ()

gap

gap: str = '20px'

id

id: str | None = None

wrap

wrap: bool = True

accept

def accept(renderer: Any) -> str

Section

__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) -> None

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

children

children: tuple[Component, ...] = ()

collapsible

collapsible: bool = False

id

id: str | None = None

level

level: int = 2

render_figures

render_figures: bool = True

show

show: bool = True

title

title: str

accept

def accept(renderer: Any) -> str

Spacer

__init__

def __init__(size: SpacerSize | str = SpacerSize.MD, id: str | None = None) -> None

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

id

id: str | None = None

size

size: SpacerSize | str = SpacerSize.MD

accept

def accept(renderer: Any) -> str

Status

A small status tag (FILLED, REJECTED, LIVE). tone as for :class:Callout.

__init__

def __init__(text: str, tone: str = 'info', id: str | None = None) -> None

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

id

id: str | None = None

text

text: str

tone

tone: str = 'info'

accept

def accept(renderer: Any) -> str

Table

__init__

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

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

caption

caption: str | None = None

data

data: pandas.DataFrame

fmt

fmt: TableFormat = TableFormat()

id

id: str | None = None

accept

def accept(renderer: Any) -> str

Text

__init__

def __init__(content: str, role: TextRole = TextRole.BODY, fmt: TextFormat = TextFormat(), safe: bool = False, id: str | None = None) -> None

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

content

content: str

fmt

fmt: TextFormat = TextFormat()

id

id: str | None = None

role

role: TextRole = TextRole.BODY

safe

safe: bool = False

accept

def accept(renderer: Any) -> str

Functions

slug

def slug(text: str) -> str

Anchor slug: lowercase, non-alnum -> ’-’ (matches report_template_v2 anchors).