Skip to content

common_reports.builders.tables

Table model — the ONE table engine, resolved to values before any HTML.

build_table_model applies the full :class:TableFormat (index handling, membership / per-column number formats, colour rules, totals) and returns a :class:TableModel of formatted, NOT-yet-escaped cells. Each renderer style emits its own markup from the same model, so every style formats a number the same way.

infer is the one optional seam: a callable (column, series) -> NumberFormat | None consulted only for cells nothing explicit claimed (no per-column format, no label-set membership, the stock FLOAT default). Explicit formats always win; without infer the model is exactly the 0.1.x engine.

Classes

TableCell

One resolved cell. text is formatted but NOT escaped (the emitter escapes per TableModel.escape).

__init__

def __init__(text: str, raw: Any = None, column: str = '', num_fmt: NumberFormat | None = None, index: bool = False, align: Align | None = None, bold: bool = False, background: str | None = None, total: bool = False, forced: bool = False) -> None

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

align

align: Align | None = None

background

background: str | None = None

bold

bold: bool = False

column

column: str = ''

forced

forced: bool = False

index

index: bool = False

num_fmt

num_fmt: NumberFormat | None = None

raw

raw: Any = None

text

text: str

total

total: bool = False

TableModel

A table resolved to cells: header labels (renamed, not escaped), body rows (row-total cells and the totals row included, in order).

__init__

def __init__(header: tuple[str, ...], rows: tuple[tuple[TableCell, ...], ...], columns: tuple[Any, ...], index_columns: int, default_index: bool, unnamed_index: bool, escape: bool, table_id: str | None, total_row: bool, total_col: bool) -> None

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

columns

columns: tuple[Any, ...]

default_index

default_index: bool

escape

escape: bool
header: tuple[str, ...]

index_columns

index_columns: int

rows

rows: tuple[tuple[TableCell, ...], ...]

table_id

table_id: str | None

total_col

total_col: bool

total_row

total_row: bool

unnamed_index

unnamed_index: bool

Functions

build_table_model

def build_table_model(table: Table, *, infer: Infer | None = None) -> TableModel

Resolve a :class:Table against its :class:TableFormat into cells.

infer_from_name

def infer_from_name(column: str, series: Any) -> NumberFormat | None

Guess a column’s format from its name: weights/returns -> PERCENT, P&L/value/price -> DOLLAR, quantities -> INT; None when unsure.

A percent guess is withheld when the numbers are already scaled (|value| > 10, i.e. 1,000%+) or the column is not numeric.

signed_column

def signed_column(column: str) -> bool

True when a column’s sign carries meaning (P&L, returns, changes).

Types and values

Infer

Infer = Callable[[str, Any], NumberFormat | None]