caxton.core.formatting

Backend-neutral presentation vocabulary. Formatting is stored separately from value semantics: the renderer chooses the physical representation and reports a capability diagnostic when it cannot preserve the intent.

Styles

Classes:

• Style –

  Backend-independent cell presentation with constructor shorthands.

• StyleSheet –

  Immutable mapping of reusable style names to styles.

• FontStyle –

  Backend-independent font presentation.

• FillStyle –

  Solid cell fill.

• Borders –

  Cell border sides.

• BorderLine –

  One side of a backend-independent cell border.

• BorderLineStyle –
• CellAlignment –

  Horizontal, vertical, and wrapping alignment intent.

• Alignment –

  Horizontal alignment expressed without backend terminology.

• VerticalAlignment –

Attributes:

• StyleInput (TypeAlias) –

StyleInput module-attribute

StyleInput: TypeAlias = Style | str

Style dataclass

Style(*, font: FontStyle | None = None, fill: FillStyle | str | None = None, border: Borders | None = None, alignment: CellAlignment | None = None, display_format: DisplayFormat | None = None, font_color: str | None = None, align: AlignmentInput | None = None, border_top: BorderLineInput | None = None, border_right: BorderLineInput | None = None, border_bottom: BorderLineInput | None = None, border_left: BorderLineInput | None = None)

Backend-independent cell presentation with constructor shorthands.

Methods:

• merged_over –

  Return this style layered over base.

merged_over

merged_over(base: Style | None) -> Style

Return this style layered over base.

StyleSheet dataclass

StyleSheet(styles: Mapping[str, Style])

Bases: Mapping[str, Style]

Immutable mapping of reusable style names to styles.

FontStyle dataclass

FontStyle(name: str | None = None, size: float | None = None, bold: bool | None = None, italic: bool | None = None, underline: bool | None = None, color: str | None = None)

Backend-independent font presentation.

FillStyle dataclass

FillStyle(color: str)

Solid cell fill.

Borders dataclass

Borders(top: BorderLine | None = None, right: BorderLine | None = None, bottom: BorderLine | None = None, left: BorderLine | None = None)

Cell border sides.

BorderLine dataclass

BorderLine(style: BorderLineStyle, color: str | None = None)

One side of a backend-independent cell border.

BorderLineStyle

Bases: StrEnum

CellAlignment dataclass

CellAlignment(horizontal: Alignment | None = None, vertical: VerticalAlignment | None = None, wrap_text: bool | None = None)

Horizontal, vertical, and wrapping alignment intent.

Alignment

Bases: StrEnum

Horizontal alignment expressed without backend terminology.

VerticalAlignment

Bases: StrEnum

Column sizing

Classes:

• AutoWidth –

  Backend-neutral bounds for a content-derived column width.

AutoWidth dataclass

AutoWidth(minimum: float = 1, maximum: float = 80)

Backend-neutral bounds for a content-derived column width.

Themes

Classes:

• DocumentTheme –

  Document defaults, inherited in default → table/column → role order.

DocumentTheme dataclass

DocumentTheme(default: Style = Style(), header: Style = Style(font=FontStyle(bold=True)), total: Style = Style(font=FontStyle(bold=True)))

Document defaults, inherited in default → table/column → role order.

Display formats

Classes:

• DecimalFormat –

  Display preferences for decimal values.

• MoneyFormat –

  Display preferences for monetary values.

• PercentageFormat –

  Percentage display preferences.

• DateFormat –

  Semantic date display variant.

• TimeFormat –

  Semantic time display variant.

• CustomFormat –

  Named semantic format with an XLSX-compatible fallback pattern.

Functions:

• decimal_format –
• money_format –
• percentage_format –
• date_format –
• time_format –
• custom_format –

Attributes:

• DisplayFormat –

DisplayFormat module-attribute

DisplayFormat = DecimalFormat | MoneyFormat | DateFormat | TimeFormat | PercentageFormat | CustomFormat

DecimalFormat dataclass

DecimalFormat(places: int = 2, grouping: bool = False)

Display preferences for decimal values.

MoneyFormat dataclass

MoneyFormat(currency: str | None = None, places: int = 2, grouping: bool = True)

Display preferences for monetary values.

Currency belongs to the value rather than its presentation. A Money column declares it through money(currency=...). The currency field here overrides that value; None keeps the column's currency.

PercentageFormat dataclass

PercentageFormat(places: int = 2, grouping: bool = False)

Percentage display preferences.

DateFormat dataclass

DateFormat(variant: Literal['iso', 'short', 'long'] = 'iso')

Semantic date display variant.

TimeFormat dataclass

TimeFormat(seconds: bool = True, clock: Literal[12, 24] = 24)

Semantic time display variant.

CustomFormat dataclass

CustomFormat(name: str, pattern: str)

Named semantic format with an XLSX-compatible fallback pattern.

decimal_format

decimal_format(*, places: int = 2, grouping: bool = False) -> DecimalFormat

money_format

money_format(*, currency: str | None = None, places: int = 2, grouping: bool = True) -> MoneyFormat

percentage_format

percentage_format(*, places: int = 2, grouping: bool = False) -> PercentageFormat

date_format

date_format(*, variant: Literal['iso', 'short', 'long'] = 'iso') -> DateFormat

time_format

time_format(*, seconds: bool = True, clock: Literal[12, 24] = 24) -> TimeFormat

custom_format

custom_format(name: str, pattern: str) -> CustomFormat