Skip to content

caxton.core.ir

The versioned, read-only spreadsheet intermediate representation. A custom renderer receives a SpreadsheetIR and serializes the IR version it declared support for.

Mutable IR builders, compiler passes and execution plans are not part of this contract.

Modules:

  • base –
  • spreadsheet –

Classes:

DocumentIR

Bases: Protocol

Common read-only envelope implemented by every versioned family IR.

CellAddress dataclass 

CellAddress(row: int, column: int)

One-based backend-independent spreadsheet coordinate.

CellRange dataclass 

CellRange(start: CellAddress, end: CellAddress)

Inclusive rectangular region of one worksheet.

Methods:

  • intersects –

    Return whether two ranges share at least one cell.

Attributes:

  • rows (int) –

    Number of worksheet rows covered by this range.

  • columns (int) –

    Number of worksheet columns covered by this range.

rows property 

rows: int

Number of worksheet rows covered by this range.

columns property 

columns: int

Number of worksheet columns covered by this range.

intersects 

intersects(other: CellRange) -> bool

Return whether two ranges share at least one cell.

ResolvedCellReference dataclass 

ResolvedCellReference(column: int, row: int | None, sheet_name: str | None = None, column_absolute: bool = False, row_absolute: bool = False)

Bases: ResolvedFormula

Resolved column and optional row; row=None means current formula row.

ResolvedFormula

Base for backend-independent formulas with resolved semantic references.

The set of nodes is closed: :data:ResolvedFormulaNode enumerates it, so a renderer can match it exhaustively and a type checker reports a forgotten branch when the IR grows a node.

RowStream 

RowStream(rows: Iterable[SpreadsheetRowIR])

One-shot stream of resolved rows carried by a table.

The IR is read-only, but rows stay lazy: the stream may wrap a generator or a one-shot data source, so it is delivered exactly once. A second pass raises instead of silently yielding nothing, which is what a bare exhausted iterator would do.

Methods:

  • consume –

    Return the row iterator exactly once.

  • materialized –

    Materialize these rows and return a fresh, unconsumed stream.

Attributes:

  • consumed (bool) –

    Whether the stream has already been handed out.

  • row_count (int | None) –

    Number of rows when the underlying source knows it without reading.

consumed property 

consumed: bool

Whether the stream has already been handed out.

row_count property 

row_count: int | None

Number of rows when the underlying source knows it without reading.

consume 

consume() -> Iterator[SpreadsheetRowIR]

Return the row iterator exactly once.

Returns:

Raises:

materialized 

materialized() -> RowStream

Materialize these rows and return a fresh, unconsumed stream.

If the rows are lazy, this consumes the current stream. Keep the returned stream instead. Calling this method on a materialized stream returns another unconsumed stream over the same rows, so a renderer can request a second pass explicitly.

Returns:

  • RowStream –

    An unconsumed stream over a materialized row sequence.

SpreadsheetBlockKind

Bases: StrEnum

Stable identity of one resolved spreadsheet layout block.

SpreadsheetChartIR dataclass 

SpreadsheetChartIR(anchor: CellAddress, kind: ChartKind, sheet_name: str, series: Sequence[SpreadsheetSeriesIR], title: str | None = None, width: int = 480, height: int = 288, name: str | None = None)

Resolved chart placement with physical data ranges.

SpreadsheetColumnIR dataclass 

SpreadsheetColumnIR(offset: int, id: str, title: str, semantic_type: SemanticType, alignment: Alignment | None, width_hint: float | None, display_format: DisplayFormat | None, formula: ResolvedFormula | None = None, style: Style = Style(), auto_width: AutoWidth | None = None, matrix_key: tuple[CellValue, ...] | None = None)

Resolved renderer-facing column description.

SpreadsheetImageIR dataclass 

SpreadsheetImageIR(anchor: CellAddress, source: str | bytes, width: int, height: int, name: str | None = None, description: str | None = None)

Resolved picture placement with its declared pixel size.

SpreadsheetIR dataclass 

SpreadsheetIR(worksheets: Sequence[SpreadsheetWorksheetIR], metadata: DocumentMetadata = dict(), version: int = SPREADSHEET_IR_VERSION)

Versioned, read-only spreadsheet renderer contract.

SpreadsheetPlacementIR dataclass 

SpreadsheetPlacementIR(kind: SpreadsheetBlockKind, path: str, anchor: CellAddress, occupied: CellRange | None, name: str | None = None, explicit: bool = False)

Resolved position and occupied range of one layout block.

SpreadsheetRowIR dataclass 

SpreadsheetRowIR(index: int, values: Sequence[CellValue])

One evaluated data row ordered like its table columns.

SpreadsheetSeriesIR dataclass 

SpreadsheetSeriesIR(name: str, values: CellRange, categories: CellRange | None = None)

One resolved chart series bound to a physical worksheet range.

SpreadsheetTableIR dataclass 

SpreadsheetTableIR(name: str | None, anchor: CellAddress, columns: Sequence[SpreadsheetColumnIR], rows: RowStream, header_style: Style = Style(), footer: SpreadsheetFooterIR | None = None, rules: Sequence[SpreadsheetConditionalRuleIR] = (), autofilter: bool = False, merges: Sequence[CellRange] = ())

A resolved table schema with a lazy, single-pass row stream.

rows is a :class:RowStream: renderers consume it exactly once. A bare iterable is wrapped, so the contract holds however the table was built.

SpreadsheetTextIR dataclass 

SpreadsheetTextIR(anchor: CellAddress, text: str, span: int = 1, style: Style = Style())

Resolved heading text written into a single worksheet row.

SpreadsheetWorksheetIR dataclass 

SpreadsheetWorksheetIR(name: str, tables: Sequence[SpreadsheetTableIR], freeze: Freeze | None = None, texts: Sequence[SpreadsheetTextIR] = (), images: Sequence[SpreadsheetImageIR] = (), charts: Sequence[SpreadsheetChartIR] = (), placements: Sequence[SpreadsheetPlacementIR] = ())

An ordered collection of resolved spreadsheet layout blocks.