caxton.core.protocols

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

Data

Rendering and output

Templates

Renderer contracts and results

Classes:

• WorkbookOperation –

  How rendering obtains the workbook that will receive compiled content.

• ExecutionMode –

  Backend-neutral preference for how a renderer executes a render.

• DataSourceRequirements –

  Non-consuming execution facts about one table row source.

• ExecutionRequirements –

  Backend-neutral constraints used to choose an execution plan.

• RequiredCapabilities –

  Backend-independent requirements discovered from a semantic graph.

• RendererCapabilities –

  IR versions and semantic features supported by a renderer.

• RendererDescriptor –

  Stable metadata used before selecting and invoking a renderer.

• RenderContext –

  Resolved invocation settings passed to a renderer.

• RenderResult –

  Description of one completed rendering operation.

WorkbookOperation

Bases: StrEnum

How rendering obtains the workbook that will receive compiled content.

ExecutionMode

Bases: StrEnum

Backend-neutral preference for how a renderer executes a render.

DataSourceRequirements dataclass

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

Non-consuming execution facts about one 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 (bool) –

  Whether source metadata forbids an implicit second data pass.

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)

Description of one completed rendering operation.

Attributes:

• content (bytes | None) –

  Artifact bytes under the delivery-oriented public name.

content property

content: bytes | None

Artifact bytes under the delivery-oriented public name.