Skip to content

caxton.core.types

Backend-independent semantic value types. The column factories in caxton.api attach one of these for you; construct them directly only when writing a custom renderer or a custom column.

The set is open: subclass SemanticType, declare name, set numeric when a totals row may aggregate it, and return its requested display format from default_format().

Classes:

Attributes:

BUILTIN_SEMANTIC_TYPES module-attribute 

BUILTIN_SEMANTIC_TYPES: Final[_SemanticTypeClasses] = (Boolean, Date, DateTime, Decimal, Duration, Integer, Link, Money, Percentage, Text, Time)

SemanticType dataclass 

SemanticType()

Backend-independent meaning of a document value.

The base class is abstract; every concrete type assigns its own name, which __init_subclass__ verifies at class-definition time instead of failing with an AttributeError at first use.

The set is open. A subclass declares how it behaves rather than relying on the renderer to recognize it by name:

  • name identifies the type in diagnostics and renderer capabilities;
  • numeric marks values a totals row may aggregate;
  • :meth:default_format returns the presentation the type asks for when a column declares no explicit display format.

A renderer that reports the semantic:extension capability renders each subclass through its declared display format. Adding a semantic type does not require a renderer change.

Methods:

  • default_format –

    Return the presentation this type asks for by default.

default_format 

default_format() -> DisplayFormat | None

Return the presentation this type asks for by default.

Returns:

  • DisplayFormat | None –

    A backend-independent display format, or None to leave the

  • DisplayFormat | None –

    choice to the renderer's own default for this type.

Text dataclass 

Text()

Bases: SemanticType

Integer dataclass 

Integer()

Bases: SemanticType

Decimal dataclass 

Decimal()

Bases: SemanticType

Money dataclass 

Money(currency: str | None = None)

Bases: SemanticType

Methods:

  • default_format –

    Return the money presentation carrying this value's currency.

default_format 

default_format() -> DisplayFormat

Return the money presentation carrying this value's currency.

Returns:

  • DisplayFormat –

    A money format with two places and digit grouping.

Percentage dataclass 

Percentage()

Bases: SemanticType

Ratio stored as a fraction: 0.15 means 15 percent.

Boolean dataclass 

Boolean()

Bases: SemanticType

Date dataclass 

Date()

Bases: SemanticType

Time dataclass 

Time()

Bases: SemanticType

DateTime dataclass 

DateTime()

Bases: SemanticType

Duration dataclass 

Duration()

Bases: SemanticType

Link()

Bases: SemanticType

Cell values

CellValue is the normalized value domain shared by semantic evaluation and spreadsheet IR rows. Individual renderers may reject values that their artifact format cannot represent; for example, XLSX output rejects binary cell values and timezone-aware date/time values.