caxton.testing

A stable, pytest-independent inspection and comparison API. Every value it returns is immutable and backend-neutral.

See Testing and diagnostics for guidance on which level to use.

Semantic inspection

Classes:

• SpreadsheetSpec –

  Stable, read-only description of a spreadsheet specification.

• WorksheetSpec –

  Stable, read-only description of one semantic worksheet.

• TableSpec –

  Stable, read-only description of one semantic table.

• MatrixSpec –

  Stable semantic description of a declarative matrix.

• BlockSpec –

  Stable, read-only description of one declared layout block.

• BlockKind –

  Stable identity of one resolved spreadsheet layout block.

• ColumnSpec –

  Stable, read-only description of one semantic column.

• ConditionalRuleSpec –

  Stable conditional rule syntax and style intent.

• SourceSpec –

  Immutable syntax tree for one semantic column source.

• SourceKind –

  Stable kinds of semantic column source.

• FormulaSpec –

  Immutable syntax tree for one semantic artifact formula.

• FormulaKind –

  Stable kinds of artifact formula nodes.

• CallableSpec –

  Stable identity and diagnostic name of a callable source.

• SemanticTypeSpec –

  Stable semantic type identity and type-specific parameters.

Functions:

• inspect_spec –

  Describe spreadsheet intent without consuming table row sources.

SpreadsheetSpec dataclass

SpreadsheetSpec(worksheets: Sequence[WorksheetSpec], metadata: Mapping[str, object], styles: StyleSheet = (lambda: StyleSheet({}))(), theme: DocumentTheme = DocumentTheme())

Stable, read-only description of a spreadsheet specification.

Methods:

• worksheet –

  Select a worksheet by semantic name.

worksheet

worksheet(name: str) -> WorksheetSpec

Select a worksheet by semantic name.

Returns:

• WorksheetSpec –

  The selected worksheet description.

Raises:

• LookupError –

  If no worksheet has the requested name.

WorksheetSpec dataclass

WorksheetSpec(name: str, tables: Sequence[TableSpec], freeze: Freeze | None = None, blocks: Sequence[BlockSpec] = ())

Stable, read-only description of one semantic worksheet.

Methods:

• table –

  Select a named table.

table

table(name: str) -> TableSpec

Select a named table.

Returns:

• TableSpec –

  The selected table description.

Raises:

• LookupError –

  If no table has the requested name.

TableSpec dataclass

TableSpec(name: str | None, anchor: str | None, columns: Sequence[ColumnSpec], style: StyleInput | None = None, header_style: StyleInput | None = None, footer: Totals | None = None, rules: Sequence[ConditionalRuleSpec] = (), autofilter: bool = False, freeze_header: bool = False, auto_width: AutoWidth | None = None)

Stable, read-only description of one semantic table.

Methods:

• column –

  Select a column by semantic identity.

Attributes:

• column_ids (tuple[str, ...]) –

  Semantic column identities in declaration order.

column_ids property

column_ids: tuple[str, ...]

Semantic column identities in declaration order.

column

column(column_id: str) -> ColumnSpec

Select a column by semantic identity.

Returns:

• ColumnSpec –

  The selected column description.

Raises:

• LookupError –

  If no column has the requested identity.

MatrixSpec dataclass

MatrixSpec(row_dimensions: Sequence[ColumnSpec], column_dimensions: Sequence[ColumnSpec], value: ColumnSpec)

Stable semantic description of a declarative matrix.

BlockSpec dataclass

BlockSpec(kind: SpreadsheetBlockKind, anchor: str | None = None, name: str | None = None, text: str | None = None, rows: int | None = None, columns: int | None = None, width: int | None = None, height: int | None = None, chart_kind: str | None = None, source: str | None = None, category: str | None = None, values: Sequence[str] = (), direction: str | None = None, gap: int | None = None, items: Sequence[BlockSpec] = (), matrix: MatrixSpec | None = None)

Stable, read-only description of one declared layout block.

BlockKind

Bases: StrEnum

Stable identity of one resolved spreadsheet layout block.

ColumnSpec dataclass

ColumnSpec(id: str, title: str, semantic_type: SemanticTypeSpec, source: SourceSpec | None, alignment: Alignment | None, width: float | None, display_format: DisplayFormat | None, formula: FormulaSpec | None = None, style: StyleInput | None = None, auto_width: AutoWidth | None = None, grouping: Grouping | None = None)

Stable, read-only description of one semantic column.

ConditionalRuleSpec dataclass

ConditionalRuleSpec(condition: FormulaSpec, style: StyleInput)

Stable conditional rule syntax and style intent.

SourceSpec dataclass

SourceSpec(kind: SourceKind, value: object = None, operands: Sequence[SourceSpec] = ())

Immutable syntax tree for one semantic column source.

SourceKind

Bases: StrEnum

Stable kinds of semantic column source.

FormulaSpec dataclass

FormulaSpec(kind: FormulaKind, value: object = None, operands: Sequence[FormulaSpec] = ())

Immutable syntax tree for one semantic artifact formula.

FormulaKind

Bases: StrEnum

Stable kinds of artifact formula nodes.

CallableSpec dataclass

CallableSpec(module: str | None, qualname: str, identity: str)

Stable identity and diagnostic name of a callable source.

SemanticTypeSpec dataclass

SemanticTypeSpec(name: str, parameters: Mapping[str, object] = dict())

Stable semantic type identity and type-specific parameters.

inspect_spec

inspect_spec(document: SpreadsheetDocument) -> SpreadsheetSpec

Describe spreadsheet intent without consuming table row sources.

Returns:

• SpreadsheetSpec –

  An immutable value view suitable for ordinary test assertions.

Layout inspection

Classes:

• Rows –

  Explicit row-consumption policy for layout inspection.

• RowsMode –

  Amount of table data explicitly requested for layout inspection.

• SpreadsheetLayout –

  Stable observed result of spreadsheet compilation.

• WorksheetLayout –

  Resolved blocks, tables and cells for one worksheet.

• TableLayout –

  Resolved table placement and explicitly inspected rows.

• BlockLayout –

  One placed block with its resolved anchor and occupied range.

• RowLayout –

  One evaluated semantic row in layout column order.

• CellLayout –

  One observed spreadsheet cell.

• CellKind –

  Semantic role of an observed layout cell.

• ColumnLayout –

  One resolved spreadsheet column.

• FooterLayout –
• TotalLayout –
• ChartLayout –

  One resolved chart placed by the flow layout.

• SeriesLayout –

  One chart series bound to a resolved worksheet range.

• ImageLayout –

  One resolved picture placed by the flow layout.

• TextLayout –

  One resolved heading placed by the flow layout.

• ConditionalRuleLayout –

Functions:

• inspect_layout –

  Compile a spreadsheet into a stable, backend-independent layout view.

Rows dataclass

Rows(mode: RowsMode, limit: int | None = None)

Explicit row-consumption policy for layout inspection.

Methods:

• none –

  Create a structure-only policy that never reads table rows.

• sample –

  Create a policy that reads at most limit rows per table.

• all –

  Create a policy that explicitly consumes every table row.

none classmethod

none() -> Self

Create a structure-only policy that never reads table rows.

Returns:

• Self –

  A structure-only row policy.

sample classmethod

sample(limit: int) -> Self

Create a policy that reads at most limit rows per table.

Returns:

• Self –

  A bounded row policy.

all classmethod

all() -> Self

Create a policy that explicitly consumes every table row.

Returns:

• Self –

  A full-consumption row policy.

RowsMode

Bases: StrEnum

Amount of table data explicitly requested for layout inspection.

SpreadsheetLayout dataclass

SpreadsheetLayout(worksheets: Sequence[WorksheetLayout], metadata: Mapping[str, object], version: int, row_scope: Rows)

Stable observed result of spreadsheet compilation.

Methods:

• worksheet –

  Select a worksheet by name.

worksheet

worksheet(name: str) -> WorksheetLayout

Select a worksheet by name.

Returns:

• WorksheetLayout –

  The selected worksheet layout.

Raises:

• LookupError –

  If no worksheet has the requested name.

WorksheetLayout dataclass

WorksheetLayout(name: str, tables: Sequence[TableLayout], freeze: Freeze | None = None, blocks: Sequence[BlockLayout] = (), texts: Sequence[TextLayout] = (), images: Sequence[ImageLayout] = (), charts: Sequence[ChartLayout] = ())

Resolved blocks, tables and cells for one worksheet.

Methods:

• block –

  Select a placed block by its declaration path.

• table –

  Select a named resolved table.

• cell –

  Select an observed header or inspected data cell by A1 address.

block

block(path: str) -> BlockLayout

Select a placed block by its declaration path.

Returns:

• BlockLayout –

  The selected block layout.

Raises:

• LookupError –

  If no block has the requested path.

table

table(name: str) -> TableLayout

Select a named resolved table.

Returns:

• TableLayout –

  The selected table layout.

Raises:

• LookupError –

  If no table has the requested name.

cell

cell(address: str) -> CellLayout

Select an observed header or inspected data cell by A1 address.

Returns:

• CellLayout –

  The selected cell layout.

Raises:

• LookupError –

  If the cell was not observed.

TableLayout dataclass

TableLayout(name: str | None, anchor: str, columns: Sequence[ColumnLayout], rows: Sequence[RowLayout], header_style: Style = Style(), footer: FooterLayout | None = None, rules: Sequence[ConditionalRuleLayout] = (), autofilter: bool = False, merged_ranges: Sequence[str] = ())

Resolved table placement and explicitly inspected rows.

Methods:

• column –

  Select a resolved column by semantic identity.

• matrix_column –

  Select a generated matrix value column by its dimension key.

• row –

  Select an inspected row by its zero-based source index.

Attributes:

• column_ids (tuple[str, ...]) –

  Resolved semantic column identities in physical order.

column_ids property

column_ids: tuple[str, ...]

Resolved semantic column identities in physical order.

column

column(column_id: str) -> ColumnLayout

Select a resolved column by semantic identity.

Returns:

• ColumnLayout –

  The selected column layout.

Raises:

• LookupError –

  If no column has the requested identity.

matrix_column

matrix_column(*key: object) -> ColumnLayout

Select a generated matrix value column by its dimension key.

Returns:

• ColumnLayout –

  The selected matrix column layout.

Raises:

• LookupError –

  If no generated column has the requested key.

row

row(index: int) -> RowLayout

Select an inspected row by its zero-based source index.

Returns:

• RowLayout –

  The selected row layout.

Raises:

• LookupError –

  If that row was not inspected.

BlockLayout dataclass

BlockLayout(kind: SpreadsheetBlockKind, path: str, anchor: str, cell_range: str | None, rows: int | None, columns: int, name: str | None = None, explicit: bool = False)

One placed block with its resolved anchor and occupied range.

RowLayout dataclass

RowLayout(index: int, values: Mapping[str, object])

One evaluated semantic row in layout column order.

CellLayout dataclass

CellLayout(address: str, value: object, kind: CellKind, column_id: str, row_index: int | None = None, formula: str | None = None)

One observed spreadsheet cell.

CellKind

Bases: StrEnum

Semantic role of an observed layout cell.

ColumnLayout dataclass

ColumnLayout(offset: int, id: str, title: str, semantic_type: SemanticTypeSpec, alignment: Alignment | None, width: float | None, display_format: DisplayFormat | None, header_address: str, formula: ResolvedFormula | None = None, style: Style = Style(), auto_width: AutoWidth | None = None, matrix_key: tuple[object, ...] | None = None)

One resolved spreadsheet column.

FooterLayout dataclass

FooterLayout(label: str, label_column_offset: int, items: Sequence[TotalLayout], style: Style)

TotalLayout dataclass

TotalLayout(column_offset: int, function: AggregateFunction)

ChartLayout dataclass

ChartLayout(anchor: str, kind: ChartKind, series: Sequence[SeriesLayout], title: str | None = None, width: int = 480, height: int = 288, name: str | None = None)

One resolved chart placed by the flow layout.

SeriesLayout dataclass

SeriesLayout(name: str, values: str, categories: str | None)

One chart series bound to a resolved worksheet range.

ImageLayout dataclass

ImageLayout(anchor: str, width: int, height: int, name: str | None = None, description: str | None = None)

One resolved picture placed by the flow layout.

TextLayout dataclass

TextLayout(anchor: str, text: str, span: int, style: Style)

One resolved heading placed by the flow layout.

ConditionalRuleLayout dataclass

ConditionalRuleLayout(formula: str, style: Style)

inspect_layout

inspect_layout(document: SpreadsheetDocument, *, rows: Rows | None = None, backend: str | None = None) -> SpreadsheetLayout

Compile a spreadsheet into a stable, backend-independent layout view.

Grouped tables and matrices are always consumed once during compilation because their schema or occupied range depends on the complete source. rows controls which compiled rows the returned view exposes.

By default inspection is renderer-agnostic and does not prove that a renderer can materialize every requested capability. Pass backend to preflight that bundled renderer and compile against its capabilities. Template placement is not represented; inspect the rendered artifact for template-backed documents.

Returns:

• SpreadsheetLayout –

  An immutable layout view with only the explicitly requested rows.

Raises:

• UnsupportedFeatureError –

  If templates or the requested backend are incompatible with layout inspection.

Artifact inspection

Classes:

• SpreadsheetArtifact –

  Stable, backend-neutral observation of one spreadsheet artifact.

• ArtifactWorksheet –

  Stable observed contents of one artifact worksheet.

• ArtifactTable –

  One native table observed in an XLSX worksheet.

• ArtifactColumn –

  One observed spreadsheet column dimension.

• ArtifactCell –

  One cell observed in a materialized spreadsheet artifact.

• ArtifactConditionalFormat –

  One backend-neutral conditional-format expression.

• ArtifactInspectionError –

  Raised when a materialized artifact cannot be read or inspected.

Functions:

• inspect_artifact –

  Inspect an XLSX artifact without exposing backend-native objects.

Attributes:

• ArtifactSource (TypeAlias) –

ArtifactSource module-attribute

ArtifactSource: TypeAlias = RenderResult | bytes | bytearray | memoryview | str | os.PathLike[str] | _BinaryReader

SpreadsheetArtifact dataclass

SpreadsheetArtifact(format: str, worksheets: Sequence[ArtifactWorksheet])

Stable, backend-neutral observation of one spreadsheet artifact.

Methods:

• worksheet –

  Select an artifact worksheet by name.

worksheet

worksheet(name: str) -> ArtifactWorksheet

Select an artifact worksheet by name.

Returns:

• ArtifactWorksheet –

  The selected artifact worksheet.

Raises:

• LookupError –

  If no worksheet has the requested name.

ArtifactWorksheet dataclass

ArtifactWorksheet(name: str, cells: Sequence[ArtifactCell], columns: Sequence[ArtifactColumn], tables: Sequence[ArtifactTable], merged_ranges: Sequence[str] = (), freeze_panes: str | None = None, autofilter: str | None = None, conditional_formats: Sequence[ArtifactConditionalFormat] = ())

Stable observed contents of one artifact worksheet.

Methods:

• cell –

  Select an observed cell by A1 address.

• column –

  Select an observed column dimension by letter.

• table –

  Select a native table by name.

Attributes:

• addresses (tuple[str, ...]) –

  Observed cell addresses in physical row-major order.

• used_range (str | None) –

  Bounding range of observed cells, if any exist.

addresses property

addresses: tuple[str, ...]

Observed cell addresses in physical row-major order.

used_range property

used_range: str | None

Bounding range of observed cells, if any exist.

cell

cell(address: str) -> ArtifactCell

Select an observed cell by A1 address.

Returns:

• ArtifactCell –

  The selected artifact cell.

Raises:

• LookupError –

  If the cell was not observed.

column

column(letter: str) -> ArtifactColumn

Select an observed column dimension by letter.

Returns:

• ArtifactColumn –

  The selected artifact column.

Raises:

• LookupError –

  If the column dimension was not observed.

table

table(name: str) -> ArtifactTable

Select a native table by name.

Returns:

• ArtifactTable –

  The selected artifact table.

Raises:

• LookupError –

  If the table was not observed.

ArtifactTable dataclass

ArtifactTable(name: str, cell_range: str, column_titles: Sequence[str], row_count: int, autofilter: bool = False)

One native table observed in an XLSX worksheet.

row_count excludes the single native header row.

ArtifactColumn dataclass

ArtifactColumn(letter: str, width: float | None)

One observed spreadsheet column dimension.

ArtifactCell dataclass

ArtifactCell(address: str, value: object, formula: str | None, number_format: str, alignment: str | None, hyperlink: str | None, bold: bool, font_name: str | None = None, font_size: float | None = None, font_color: str | None = None, fill_color: str | None = None, border_bottom: str | None = None)

One cell observed in a materialized spreadsheet artifact.

Formula cells expose formula text in both value and formula because inspection preserves formulas instead of loading calculated cached values.

ArtifactConditionalFormat dataclass

ArtifactConditionalFormat(cell_range: str, formulae: Sequence[str], font_color: str | None = None, fill_color: str | None = None)

One backend-neutral conditional-format expression.

ArtifactInspectionError dataclass

ArtifactInspectionError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError

Raised when a materialized artifact cannot be read or inspected.

inspect_artifact

inspect_artifact(source: ArtifactSource, *, format: str | None = None) -> SpreadsheetArtifact

Inspect an XLSX artifact without exposing backend-native objects.

Unsupported source objects raise TypeError. An unreadable or malformed XLSX package raises ArtifactInspectionError with source context.

Returns:

• SpreadsheetArtifact –

  An immutable observation of workbook contents and presentation.

Raises:

• ValueError –

  If the format is unsupported or conflicts with the source.

Comparison and snapshots

Classes:

• SpreadsheetAssertionError –

  Spreadsheet mismatch with machine-readable differences.

• Difference –

  One stable, path-addressed mismatch between expected and actual values.

• DifferenceKind –

  Kind of observable mismatch between two inspected values.

Functions:

• assert_spreadsheet_equal –

  Assert equality of two spreadsheet specifications.

• canonical_snapshot –

  Serialize a testing value as deterministic, human-readable JSON.

Attributes:

• SNAPSHOT_SCHEMA –

SNAPSHOT_SCHEMA module-attribute

SNAPSHOT_SCHEMA = 'caxton.testing.snapshot/v2'

SpreadsheetAssertionError

SpreadsheetAssertionError(differences: Sequence[Difference])

Bases: AssertionError

Spreadsheet mismatch with machine-readable differences.

Difference dataclass

Difference(path: str, kind: DifferenceKind, expected: object, actual: object)

One stable, path-addressed mismatch between expected and actual values.

DifferenceKind

Bases: StrEnum

Kind of observable mismatch between two inspected values.

assert_spreadsheet_equal

assert_spreadsheet_equal(actual: SpecInput, expected: SpecInput, *, check_order: bool = True, check_metadata: bool = True) -> None

Assert equality of two spreadsheet specifications.

Both inspected specifications and source documents are accepted. Inspecting a source document is structural and never consumes its table row sources.

Parameters:

• actual (SpecInput) –

  Observed spreadsheet specification or source document.

• expected (SpecInput) –

  Expected spreadsheet specification or source document.

• check_order (bool, default: True ) –

  Whether declaration order is significant.

• check_metadata (bool, default: True ) –

  Whether document metadata is significant.

Raises:

• SpreadsheetAssertionError –

  If observable specifications differ.

canonical_snapshot

canonical_snapshot(value: object) -> str

Serialize a testing value as deterministic, human-readable JSON.

Unsupported runtime objects raise TypeError; recursive containers raise ValueError.

Returns:

• str –

  Canonical JSON ending with one newline.

Hypothesis strategies

Requires the hypothesis extra.

Functions:

• identifiers –

  Generate compact identifiers accepted by Caxton models.

• semantic_types –

  Generate built-in semantic type declarations.

• columns –

  Generate one valid semantic column.

• spreadsheet_documents –

  Generate a bounded, structurally valid spreadsheet declaration.

identifiers

identifiers() -> SearchStrategy[str]

Generate compact identifiers accepted by Caxton models.

Returns:

• SearchStrategy[str] –

  An identifier strategy.

semantic_types

semantic_types() -> SearchStrategy[SemanticType]

Generate built-in semantic type declarations.

Returns:

• SearchStrategy[SemanticType] –

  A semantic type strategy.

columns

columns(draw: DrawFn) -> Column

Generate one valid semantic column.

Returns:

• Column –

  A generated column.

spreadsheet_documents

spreadsheet_documents(draw: DrawFn) -> SpreadsheetDocument

Generate a bounded, structurally valid spreadsheet declaration.

Returns:

• SpreadsheetDocument –

  A generated spreadsheet document.