common_reports.builders.formatting
Shared value engines for every renderer — number formatting and colour.
format_number— the ONE number formatter (replaces the two AlgoReportsprepare_tables/prepare_tablelambda trios). [G4] value = raw*scale BEFORE format; [G9] EXACT-string set membership, never substring; floats only unless a per-columnnum_fmtforces it.apply_color_rule/resolve_color— deterministic colour (replaces thenp.random+evalgenerators). [G20]
Pure stdlib + contracts: no plotting SDK, safe to import anywhere.
Functions
apply_color_rule
def apply_color_rule(rule: ColorRule, value: Any, *, vmin: float | None = None, vmax: float | None = None) -> str | NoneResolve a single cell’s background colour from a :class:ColorRule.
Returns a CSS colour string or None (no styling). vmin/vmax may be
supplied for SCALE rules whose own bounds are unset (computed column-wide).
format_kpi
def format_kpi(kpi: Kpi) -> tuple[str, str | None, int]A headline number’s display parts: (value, change, sign).
value uses kpi.fmt when given (a bare number gets thousands
separators); change is signed (+1.20%; percent changes always show two
decimals) and sign is -1 / 0 / +1 (0 when there is no change).
format_number
def format_number(value: Any, num_fmt: NumberFormat | None, decimals: int = 2, scale: float = 1.0, *, date_format: str = '%Y-%m-%d', forced: bool = False, null_display: str = '') -> strThe single number-formatting engine (replaces the two lambda trios).
[G4] value = raw * scale is applied BEFORE the format string.
[G9] membership is decided by the caller via EXACT-string set lookup; this
function only knows the resolved NumberFormat.
Source parity: numeric formats apply ONLY when value is a Python float —
ints / strings / dates pass through — UNLESS forced (a per-column
ColumnFormat.num_fmt was set), which formats regardless of dtype.
headline_sign
def headline_sign(kpi: Kpi) -> int-1 / 0 / +1 for a signed headline’s value; 0 when not signed or not a number.
resolve_color
def resolve_color(name: str, role: str, palette: Palette, used: frozenset[str] = frozenset()) -> strDeterministic colour for name in role (‘strategy’|‘benchmark’)
via the frozen :class:Palette wheel (replaces np.random + eval). [G20]