caxton.core.models¶
Immutable semantic nodes. These store intent only — never coordinates, resolved layout, execution state or backend-native objects.
Document and worksheets¶
Classes:
-
SpreadsheetDocument–Backend-independent spreadsheet document intent.
-
Worksheet–Immutable sequence of spreadsheet blocks.
-
DocumentKind–
Attributes:
module-attribute
¶
dataclass
¶
SpreadsheetDocument(worksheets: Sequence[Worksheet], metadata: DocumentMetadata = dict(), styles: StyleSheet = (lambda: StyleSheet({}))(), theme: DocumentTheme = DocumentTheme(), template: TemplateSpecification | None = None)
Backend-independent spreadsheet document intent.
dataclass
¶
Worksheet(name: str, blocks: Sequence[SpreadsheetBlock], freeze: Freeze | None = None)
Immutable sequence of spreadsheet blocks.
Attributes:
-
tables(Sequence[SpreadsheetTable]) –Every table block of this worksheet, including nested ones.
property
¶
tables: Sequence[SpreadsheetTable]
Every table block of this worksheet, including nested ones.
Bases: StrEnum
Tables¶
Classes:
-
SpreadsheetTable–Spreadsheet placement of semantic table data.
-
TableData–Shared semantic schema and its lazy row source.
-
Column–Immutable semantic column specification.
-
Grouping–Grouping intent attached to one semantic table column.
-
GroupOrder–Stable ordering policy for values at one grouping level.
-
Total–Aggregate placed in one semantic column of a totals footer.
-
Totals–One totals/footer row.
-
AggregateFunction– -
ConditionalRule–Formula-based conditional cell style for a table data range.
Functions:
-
when–Declare a conditional style applied to a table data range.
dataclass
¶
SpreadsheetTable(data: TableData, name: str | None = None, anchor: str | None = None, style: StyleInput | None = None, header_style: StyleInput | None = None, footer: Totals | None = None, rules: Sequence[ConditionalRule] = (), autofilter: bool = False, freeze_header: bool = False, auto_width: AutoWidth | bool | None = None, into: TemplateRef | TemplateRepeat | None = None)
Spreadsheet placement of semantic table data.
freeze_header keeps the header row of this table visible; worksheet
level freezing stays in Worksheet.freeze. auto_width applies to
every column that declares no explicit width, while a column's own
auto_width always wins.
dataclass
¶
TableData(source: DataSource[Any], columns: Sequence[Column])
Shared semantic schema and its lazy row source.
dataclass
¶
Column(*, semantic_type: SemanticType, id: str | None = None, source: ColumnSourceInput = None, excel_formula: FormulaInput | None = None, title: str | None = None, alignment: Alignment | str | None = None, width_hint: float | None = None, display_format: DisplayFormat | None = None, style: StyleInput | None = None, auto_width: AutoWidth | bool | None = None, grouping: Grouping | None = None)
Immutable semantic column specification.
A column defines its value either through a Python source evaluated
before rendering or through an excel_formula retained in the artifact.
Exactly one is required. Width may use an explicit width_hint or an
auto_width policy, but not both.
Construct and normalize one final semantic column.
Exactly one of source and excel_formula is required.
width_hint and auto_width are likewise mutually exclusive.
String sources provide the default semantic ID; every other source
shape and every Excel formula requires an explicit id.
Raises:
-
CaxtonTypeError–If a value has an invalid runtime type.
-
CaxtonValueError–If declared values violate a column invariant.
Methods:
-
titled–Return a column with a different display title.
-
align–Return a column with a horizontal alignment hint.
-
width–Return a column with fixed or content-derived width intent.
-
format–Return a column with a backend-independent display format.
-
formula–Return a column whose cells retain an Excel formula in the artifact.
-
styled–Return a column with an inline or reusable style reference.
-
grouped–Return a column that defines one hierarchical grouping level.
Attributes:
-
display_title(str) –Explicit title, or the semantic id when no title was set.
property
¶
display_title: str
Explicit title, or the semantic id when no title was set.
titled(value: str) -> Self
Return a column with a different display title.
Returns:
-
Self–A column carrying the new display title.
Return a column with a horizontal alignment hint.
An unsupported alignment name is rejected the same way the constructor rejects it.
Returns:
-
Self–A column carrying the new alignment.
Return a column with fixed or content-derived width intent.
Returns:
-
Self–A column carrying the new width intent.
format(value: DisplayFormat) -> Self
Return a column with a backend-independent display format.
Returns:
-
Self–A column carrying the new display format.
Raises:
-
CaxtonTypeError–If the value is not a display format.
formula(value: FormulaInput) -> Self
Return a column whose cells retain an Excel formula in the artifact.
The Python source is replaced because a column carries either a source or a formula.
Returns:
-
Self–A formula-backed column.
styled(value: StyleInput) -> Self
Return a column with an inline or reusable style reference.
Returns:
-
Self–A column carrying the new style reference.
grouped(*, merge: bool = False, order: GroupOrder | str = FIRST_SEEN) -> Self
Return a column that defines one hierarchical grouping level.
Sorted groups keep None last in both ascending and descending
order.
Returns:
-
Self–A column carrying immutable grouping intent.
dataclass
¶
Grouping(merge: bool = False, order: GroupOrder | str = FIRST_SEEN)
Grouping intent attached to one semantic table column.
Bases: StrEnum
Stable ordering policy for values at one grouping level.
dataclass
¶
Total(column: str, function: AggregateFunction | str = SUM)
Aggregate placed in one semantic column of a totals footer.
Every aggregate, including COUNT, names the column it is placed in and
aggregates that column's values.
dataclass
¶
Totals(label: str = 'Total', items: Sequence[Total] = (), label_column: str | None = None, style: StyleInput | None = None)
One totals/footer row.
label_column selects where the label is written; when it is None
the first column without an aggregate is used.
Bases: StrEnum
dataclass
¶
ConditionalRule(condition: Formula, style: StyleInput)
Formula-based conditional cell style for a table data range.
when(condition: FormulaInput, *, style: StyleInput) -> ConditionalRule
Declare a conditional style applied to a table data range.
Returns:
-
ConditionalRule–An immutable conditional rule.
Other blocks¶
Classes:
-
Matrix–Declarative pivot-like spreadsheet block over one row source.
-
Title–One line of heading text occupying a single worksheet row.
-
Spacer–Empty layout gap measured in whole rows and columns.
-
Image–Picture placed by declared pixel size instead of engine coordinates.
-
Chart–Chart whose data is bound to columns of one named table.
-
ChartKind–Closed set of chart shapes supported by the spreadsheet family.
-
Stack–Minimal flow container placing nested blocks one after another.
-
BlockDirection–Direction in which a flow container advances its layout cursor.
-
Freeze–Number of leading worksheet rows and columns kept visible.
dataclass
¶
Matrix(source: DataSource[Any], row_dimensions: Sequence[Column], column_dimensions: Sequence[Column], value: Column, anchor: str | None = None, style: StyleInput | None = None, header_style: StyleInput | None = None)
Declarative pivot-like spreadsheet block over one row source.
dataclass
¶
Title(text: str, level: int = 1, span: int = 1, style: StyleInput | None = None, anchor: str | None = None)
One line of heading text occupying a single worksheet row.
dataclass
¶
Empty layout gap measured in whole rows and columns.
dataclass
¶
Image(source: str | bytes, width: int = DEFAULT_OBJECT_WIDTH, height: int = DEFAULT_OBJECT_HEIGHT, name: str | None = None, description: str | None = None, anchor: str | None = None)
Picture placed by declared pixel size instead of engine coordinates.
String sources are resolved during rendering; byte sources are retained directly as immutable content.
dataclass
¶
Chart(source: TableReference, *, x: str, y: str | Sequence[str], kind: ChartKind | str = COLUMN, title: str | None = None, width: int = DEFAULT_OBJECT_WIDTH, height: int = DEFAULT_OBJECT_HEIGHT, name: str | None = None, anchor: str | None = None)
Chart whose data is bound to columns of one named table.
Bases: StrEnum
Closed set of chart shapes supported by the spreadsheet family.
dataclass
¶
Stack(items: Sequence[SpreadsheetBlock], direction: BlockDirection | str = VERTICAL, gap: int = 0, anchor: str | None = None)
Minimal flow container placing nested blocks one after another.
Bases: StrEnum
Direction in which a flow container advances its layout cursor.
Python expressions¶
Classes:
-
Expression–Base for immutable, backend-independent row expressions.
-
FieldRef–Exact top-level row field read through the data source.
-
PathRef–Explicit nested row path.
-
ColumnRef–Value of another semantic column of the same table.
-
LiteralExpression–Constant operand of a row expression.
-
BinaryExpression– -
TransformExpression–Python value transformation evaluated once for each source row.
-
AggregateExpr–Aggregate computed from one or more expression value sequences.
-
BinaryOperator– -
CallableSource–Explicit source evaluated against the original row object.
Functions:
-
field–Read one exact top-level field of the raw data row.
-
path–Traverse a nested row structure segment by segment.
-
ref–Read the evaluated value of another semantic column.
-
literal–Create a constant Python row expression.
Attributes:
-
AggregateCallable(TypeAlias) – -
ColumnSource(TypeAlias) – -
ColumnSourceInput(TypeAlias) – -
RowCallable(TypeAlias) – -
TransformCallable(TypeAlias) –
module-attribute
¶
ColumnSourceInput: TypeAlias = str | ColumnSource | RowCallable | None
Bases: BinaryOperatorMixin['BinaryExpression']
Base for immutable, backend-independent row expressions.
Methods:
-
agg–Aggregate this expression and any additional inputs in one scope.
-
transform–Apply a Python function to this expression for every source row.
agg(function: AggregateCallable, *expressions: Expression, where: Expression | None = None, default: object = _MISSING_AGGREGATE_DEFAULT) -> AggregateExpr
Aggregate this expression and any additional inputs in one scope.
The callable receives one value sequence per input expression, in
declaration order. Caxton does not remove None or otherwise
normalize those sequences before invoking it.
Returns:
-
AggregateExpr–An immutable, backend-independent aggregation expression.
transform(function: TransformCallable) -> TransformExpression
Apply a Python function to this expression for every source row.
Returns:
-
TransformExpression–Immutable value-transform intent retaining this expression as input.
dataclass
¶
BinaryExpression(operator: BinaryOperator, left: Expression, right: Expression)
Bases: Expression
dataclass
¶
TransformExpression(function: TransformCallable, expression: Expression)
dataclass
¶
AggregateExpr(function: AggregateCallable, expressions: Sequence[Expression], where: Expression | None = None, default: object = _MISSING_AGGREGATE_DEFAULT)
Bases: Expression
Aggregate computed from one or more expression value sequences.
function receives one sequence for every item in expressions.
default uses an internal sentinel so an explicit None remains
distinguishable from an omitted empty-scope result.
Attributes:
-
has_default(bool) –Whether an explicit result was declared for an empty scope.
Bases: StrEnum
dataclass
¶
CallableSource(function: RowCallable)
Explicit source evaluated against the original row object.
Read the evaluated value of another semantic column.
Returns:
-
ColumnRef–A semantic column reference.
literal(value: _LiteralInput) -> LiteralExpression
Create a constant Python row expression.
Returns:
-
LiteralExpression–An immutable literal expression containing a normalized cell value.
Spreadsheet formulas¶
Classes:
-
Formula–Base for immutable formulas evaluated by the spreadsheet artifact.
-
FormulaLiteral– -
FormulaBinary– -
FormulaOperator– -
CellReference–Semantic cell reference;
row_index=Nonemeans the current data row. -
RangeReference–Semantic data range for one named table column.
-
TableReference– -
SheetReference–
Functions:
Attributes:
-
FormulaInput(TypeAlias) – -
FormulaScalar(TypeAlias) –
module-attribute
¶
Bases: BinaryOperatorMixin['FormulaBinary']
Base for immutable formulas evaluated by the spreadsheet artifact.
dataclass
¶
FormulaBinary(operator: FormulaOperator, left: Formula, right: Formula)
Bases: Formula
Bases: StrEnum
dataclass
¶
CellReference(column_id: str, table_name: str | None = None, sheet_name: str | None = None, row_index: int | None = None, column_absolute: bool = False, row_absolute: bool = False)
Bases: Formula
Semantic cell reference; row_index=None means the current data row.
Methods:
-
absolute–Return a reference whose axes are absolute exactly as requested.
-
relative–Return a reference with both axes relative.
Return a reference whose axes are absolute exactly as requested.
Returns:
-
Self–A reference with
column_absolute/row_absoluteset to the -
Self–supplied flags, so
absolute(column=False)makes the column -
Self–relative instead of silently doing nothing.
Return a reference with both axes relative.
Returns:
-
Self–A reference with both axes relative. The per-axis flags are
-
deprecated(Self) –they invert their argument, so
relative(row=False) -
Self–makes the row absolute. Use :meth:
absoluteinstead.
dataclass
¶
RangeReference(table_name: str, column_id: str, sheet_name: str | None = None, column_absolute: bool = False, row_absolute: bool = False)
Bases: Formula
Semantic data range for one named table column.
Methods:
-
absolute–Return a range whose axes are absolute exactly as requested.
-
relative–Return a range with both axes relative.
Return a range whose axes are absolute exactly as requested.
Returns:
-
Self–A range with
column_absolute/row_absoluteset to the -
Self–supplied flags.
Return a range with both axes relative.
Returns:
-
Self–A range with both axes relative. The per-axis flags are deprecated:
-
Self–they invert their argument, so
relative(row=False)makes the -
Self–row absolute. Use :meth:
absoluteinstead.
absolute(reference: CellReference, *, column: bool = True, row: bool = True) -> CellReference
absolute(reference: RangeReference, *, column: bool = True, row: bool = True) -> RangeReference
absolute(reference: CellReference | RangeReference, *, column: bool = True, row: bool = True) -> CellReference | RangeReference
Set the absolute axes of a cell or range reference.
Returns:
-
CellReference | RangeReference–A reference whose axes match the supplied flags exactly.
Block traversal and defaults¶
Functions:
-
contains_aggregate–Return whether an expression tree contains aggregate intent.
-
iter_blocks–Walk blocks depth-first, yielding containers before their items.
-
iter_tables–Walk every table block, including tables nested in a
Stack.
Attributes:
contains_aggregate(expression: Expression) -> bool
Return whether an expression tree contains aggregate intent.
iter_blocks(blocks: Sequence[SpreadsheetBlock]) -> Iterator[SpreadsheetBlock]
Walk blocks depth-first, yielding containers before their items.
Yields:
-
SpreadsheetBlock–Every declared block, including blocks nested in a
Stack.
iter_tables(blocks: Sequence[SpreadsheetBlock]) -> Iterator[SpreadsheetTable]
Walk every table block, including tables nested in a Stack.
Yields:
-
SpreadsheetTable–Each declared spreadsheet table in declaration order.
Templates¶
Classes:
-
TemplateSpecification–Immutable, format-independent description of a template source.
-
TemplateRepeat–Generic intent to repeat the region identified by a logical reference.
-
TemplateContext–Read-only backend-independent facts discovered from a template.
-
TemplateCompilationResult–Generic renderer input for an inspected and compiled template.
-
ResolvedTemplateTarget–Marker implemented by generic or format-specific resolved targets.
-
Extension–Backend extension scoped by namespace and required capabilities.
Attributes:
dataclass
¶
Immutable, format-independent description of a template source.
A path is resolved when the template is inspected for rendering. Raw bytes are retained directly in the semantic model.
dataclass
¶
Generic intent to repeat the region identified by a logical reference.
dataclass
¶
Read-only backend-independent facts discovered from a template.
dataclass
¶
TemplateCompilationResult(document: IR_co, context: TemplateContext, targets: Sequence[ResolvedTemplateTarget] = (), extensions: Sequence[Extension] = ())