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 –

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

• CellAddress –

  One-based backend-independent spreadsheet coordinate.

• CellRange –

  Inclusive rectangular region of one worksheet.

• ResolvedCellReference –

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

• ResolvedFormula –

  Base for backend-independent formulas with resolved semantic references.

• SpreadsheetBlockKind –

  Stable identity of one resolved spreadsheet layout block.

• SpreadsheetChartIR –

  Resolved chart placement with physical data ranges.

• SpreadsheetColumnIR –

  Resolved renderer-facing column description.

• SpreadsheetImageIR –

  Resolved picture placement with its declared pixel size.

• SpreadsheetIR –

  Versioned, read-only spreadsheet renderer contract.

• SpreadsheetPlacementIR –

  Resolved position and occupied range of one layout block.

• SpreadsheetRowIR –

  One evaluated data row ordered like its table columns.

• SpreadsheetSeriesIR –

  One resolved chart series bound to a physical worksheet range.

• SpreadsheetTableIR –

  A resolved table schema with a lazy row stream.

• SpreadsheetTextIR –

  Resolved heading text written into a single worksheet row.

• SpreadsheetWorksheetIR –

  An ordered collection of resolved spreadsheet layout blocks.

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.

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: bool = False, 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: Iterable[SpreadsheetRowIR], header_style: Style = Style(), footer: SpreadsheetFooterIR | None = None, rules: Sequence[SpreadsheetConditionalRuleIR] = (), autofilter: bool = False, merges: Sequence[CellRange] = ())

A resolved table schema with a lazy row stream.

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.