Skip to content

Transformers⚓︎

transformers ⚓︎

Composition utilities for source-aware table transformations.

Transformers run after raw rows become TableData and before schema labels and values are validated. They let projects turn compact BDD authoring syntax into the logical table shape that schemas already understand.

Info

Transformers must preserve source-aware cells so downstream diagnostics can still point at the original feature text.

TableTransformer ⚓︎

Bases: Protocol

Structural contract implemented by reusable table transformers.

Info

Any object with a compatible transform method satisfies this protocol; inheritance is not required.

transform ⚓︎

transform(
    table: TableData, context: ParseContext, *, schema: type | str | None = None
) -> TableData

Return a source-aware table for the next transformation stage.

Parameters:

  • table (TableData) –

    Current source-aware logical table.

  • context (ParseContext) –

    Parse context for the current operation.

  • schema (type | str | None, default: None ) –

    Optional schema identity for diagnostics.

Returns:

Warning

Return TableData, not raw rows. Use TableData.from_cells after arranging source-aware cells.

TransformerPipeline ⚓︎

TransformerPipeline(transformers: Sequence[TableTransformer])

Run table transformers from left to right.

Each stage receives the previous stage's TableData and the same parse context. Unexpected failures identify the stage, while intentional TableError diagnostics pass through unchanged.

Attributes:

  • transformers –

    Immutable ordered transformation stages.

Example

table_transformer = compose_transformers(
    NormalizeLabels(),
    ColumnGroupExpander(...),
)

Validate and store transformation stages.

Parameters:

Raises:

  • ValueError –

    If no transformers are supplied.

  • TypeError –

    If a stage lacks a callable transform method.

Warning

Pipeline order is observable because each stage receives the previous stage's output.

transform ⚓︎

transform(
    table: TableData, context: ParseContext, *, schema: type | str | None = None
) -> TableData

Apply every configured transformer and validate each result.

Parameters:

  • table (TableData) –

    Initial source-aware table.

  • context (ParseContext) –

    Parse context for the current operation.

  • schema (type | str | None, default: None ) –

    Optional schema identity for diagnostics.

Returns:

  • TableData –

    Final TableData produced by the last stage.

Raises:

  • TableError –

    If a stage raises a table error, raises an unexpected exception, or returns a non-TableData value.

Info

Intentional TableError instances are re-raised unchanged so custom transformers keep their precise source diagnostics.

compose_transformers ⚓︎

compose_transformers(*transformers: TableTransformer) -> TransformerPipeline

Create a reusable left-to-right table transformation pipeline.

Parameters:

  • *transformers (TableTransformer, default: () ) –

    Ordered transformer stages.

Returns:

Example

class ContentTable(ColumnTable):
    table_transformer = compose_transformers(clean, expand)