Skip to content

common_reports.builders.formatting

Shared value engines for every renderer — number formatting and colour.

  • format_number — the ONE number formatter (replaces the two AlgoReports prepare_tables / prepare_table lambda trios). [G4] value = raw*scale BEFORE format; [G9] EXACT-string set membership, never substring; floats only unless a per-column num_fmt forces it.
  • apply_color_rule / resolve_color — deterministic colour (replaces the np.random + eval generators). [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 | None

Resolve 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 = '') -> str

The 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()) -> str

Deterministic colour for name in role (‘strategy’|‘benchmark’) via the frozen :class:Palette wheel (replaces np.random + eval). [G20]