Skip to content

caxton.core.protocols

Structural contracts. Implement these to plug in your own data source, output target or renderer — no registration or private implementation import required.

Data

Classes:

Attributes:

RowSourceInput module-attribute 

RowSourceInput: TypeAlias = DataSource[Any] | Iterable[object] | Mapping[str, object]

Row input accepted by the public table factories.

A ready :class:DataSource, any iterable of rows, or one mapping row. Rows themselves stay untyped: a row is read field by field through a :class:RowAccessor, never introspected as a whole.

One bare dataclass, NamedTuple or attribute object is also accepted at runtime as a single-row source. That shape is not expressible in a type that still rejects scalars, so typed callers wrap it in a one-element sequence.

DataSource

Bases: Protocol[RowT]

Lazy row source used by semantic table data.

DataSourceInfo

Bases: Protocol

Optional execution hints exposed by a data source.

RowAccessor

Bases: Protocol[AccessorRowT_contra]

Read one exact field from one row.

Repeatability

Bases: Enum

Built-in row accessors

Classes:

MappingRowAccessor

Read fields using exact mapping key semantics.

AttributeRowAccessor

Read exact attributes without masking descriptor failures.

DefaultRowAccessor 

DefaultRowAccessor()

Select exact mapping or attribute semantics for each row.

Rendering and output

Classes:

  • Renderer –

    Backend adapter consuming one compatible family IR.

  • OutputSink –

    Destination accepting rendered binary chunks or raising on failure.

  • BinaryWritable –

    External binary buffer whose short writes are completed by adapters.

  • BinarySeekable –

    Seekable binary stream that can receive an artifact directly.

Attributes:

OutputTarget module-attribute 

OutputTarget: TypeAlias = str | os.PathLike[str] | BinaryWritable

Renderer

Bases: Protocol[DocumentIR_contra]

Backend adapter consuming one compatible family IR.

Lazy iterables carried by a family IR are single-pass renderer inputs unless that IR explicitly documents repeatability.

OutputSink

Bases: Protocol

Destination accepting rendered binary chunks or raising on failure.

BinaryWritable

Bases: Protocol

External binary buffer whose short writes are completed by adapters.

BinarySeekable

Bases: BinaryWritable, Protocol

Seekable binary stream that can receive an artifact directly.

Templates

Classes:

  • TemplateRenderer –

    Renderer consuming a generic template compilation result.

  • TemplateInspector –

    Read-only adapter that discovers facts about one template source.

TemplateRenderer

Bases: Protocol[IR_contra]

Renderer consuming a generic template compilation result.

TemplateInspector

Bases: Protocol

Read-only adapter that discovers facts about one template source.

Renderer contracts and results

Classes:

WorkbookOperation

Bases: StrEnum

How rendering obtains the workbook that will receive compiled content.

ExecutionMode

Bases: StrEnum

Backend-neutral execution preference for a renderer.

DataSourceRequirements dataclass 

DataSourceRequirements(worksheet_index: int, table_index: int, repeatability: Repeatability = UNKNOWN, row_count: int | None = None)

Execution metadata collected without reading a table row source.

ExecutionRequirements dataclass 

ExecutionRequirements(mode: ExecutionMode = AUTO, data_sources: tuple[DataSourceRequirements, ...] = (), append_only: bool = False, has_named_tables: bool = False, requires_buffering: bool = False)

Backend-neutral constraints used to choose an execution plan.

Attributes:

requires_single_pass property 

requires_single_pass: bool

Whether source metadata forbids an implicit second data pass.

RequiredCapabilities dataclass 

RequiredCapabilities(document_kind: DocumentKind, ir_versions: frozenset[int], features: frozenset[str] = frozenset(), workbook_operation: WorkbookOperation = CREATE_NEW_WORKBOOK, execution: ExecutionRequirements = ExecutionRequirements())

Backend-independent requirements discovered from a semantic graph.

RendererCapabilities dataclass 

RendererCapabilities(ir_versions: Mapping[DocumentKind, frozenset[int]], features: frozenset[str] = frozenset(), workbook_operations: frozenset[WorkbookOperation] = frozenset((CREATE_NEW_WORKBOOK,)), execution_modes: frozenset[ExecutionMode] = frozenset((STANDARD,)))

IR versions and semantic features supported by a renderer.

Methods:

  • supports –

    Return whether every required version and feature is compatible.

supports 

supports(required: RequiredCapabilities) -> bool

Return whether every required version and feature is compatible.

RendererDescriptor dataclass 

RendererDescriptor(name: str, version: str, formats: frozenset[str], mime_types: frozenset[str], extensions: frozenset[str], capabilities: RendererCapabilities, contract_version: int = RENDERER_CONTRACT_VERSION)

Stable metadata used before selecting and invoking a renderer.

RenderContext dataclass 

RenderContext(format: str, backend: str, execution: ExecutionRequirements = ExecutionRequirements())

Resolved invocation settings passed to a renderer.

RenderResult dataclass 

RenderResult(format: str, mime_type: str, renderer: str, bytes_written: int, data: bytes | None = None, target: str | None = None, execution_mode: ExecutionMode = STANDARD, execution_plan: str | None = None)

Result of a completed rendering operation.

Attributes:

  • content (bytes | None) –

    Deprecated alias of :attr:data.

content property 

content: bytes | None

Deprecated alias of :attr:data.

Returns:

  • bytes | None –

    The artifact bytes held by :attr:data.