Parsing Helpers⚓︎

parsing ⚓︎

Functional parsing helpers for projects that prefer explicit APIs.

The schema methods remain the primary interface:

UserTable.parse(datatable)

Some teams prefer a parser-function style because it makes the schema an argument rather than the object receiving the call. The helpers in this module support that style without creating another parsing implementation.

Info

These helpers are thin delegates. The schema class still owns orientation, validation, transformation, references, and output conversion.

parse_table ⚓︎

parse_table(
    schema: type[TableT],
    datatable: RawTable | TableData,
    *,
    context: Mapping[str, Any] | ParseContext | None = None,
    error_mode: str = "first",
) -> list[TableT]

Parse a Gherkin data table using a schema class.

This is the functional equivalent of schema.parse(datatable). It is useful in codebases that prefer explicit parser functions over classmethod calls. It always returns validated schema records; output conversion uses :func:parse_table_as.

Parameters:

schema (type[TableT]) –

Concrete RowTable or ColumnTable subclass.
datatable (RawTable | TableData) –

Raw list[list[str]] table or source-aware TableData.
context (Mapping[str, Any] | ParseContext | None, default: None ) –

Optional project data or existing parse context.
error_mode (str, default: 'first' ) –

"first" for fail-fast parsing or "collect" for aggregate diagnostics.

Returns:

list[TableT] –

Validated instances of schema.

Raises:

ValueError –

If error_mode is unsupported.
SchemaDefinitionError –

If the schema family is invalid.
TableError –

If parsing or validation fails in first-error mode.
TableErrors –

If collect mode finds error-severity failures.

Note

Warning-severity validation diagnostics are emitted as TalikaWarning and records are still returned.

Example

users = parse_table(UserTable, datatable)

parse_table_as ⚓︎

parse_table_as(
    schema: type[BaseTable],
    datatable: RawTable | TableData,
    output_model: Callable[..., OutputT],
    *,
    context: Mapping[str, Any] | ParseContext | None = None,
    error_mode: str = "first",
) -> list[OutputT]

parse_table_as(
    schema: type[BaseTable],
    datatable: RawTable | TableData,
    output_model: None = None,
    *,
    context: Mapping[str, Any] | ParseContext | None = None,
    error_mode: str = "first",
) -> list[Any]

parse_table_as(
    schema: type[BaseTable],
    datatable: RawTable | TableData,
    output_model: Callable[..., OutputT] | None = None,
    *,
    context: Mapping[str, Any] | ParseContext | None = None,
    error_mode: str = "first",
) -> list[OutputT] | list[Any]

Parse a Gherkin data table and build public output objects.

This is the functional equivalent of schema.parse_as(...). An explicit callable overrides configured schema and variant output hooks. Omitting it uses the schema's output_model or custom build_output().

Parameters:

schema (type[BaseTable]) –

Concrete RowTable or ColumnTable subclass.
datatable (RawTable | TableData) –

Raw list[list[str]] table or source-aware TableData.
output_model (Callable[..., OutputT] | None, default: None ) –

Optional callable receiving parsed record fields as keyword arguments.
context (Mapping[str, Any] | ParseContext | None, default: None ) –

Optional project data or existing parse context.
error_mode (str, default: 'first' ) –

"first" for fail-fast parsing or "collect" for aggregate diagnostics.

Returns:

list[OutputT] | list[Any] –

Converted public output objects.

Raises:

TypeError –

If output_model is not callable.
ValueError –

If no explicit or configured output conversion exists.
TableError –

If parsing, validation, or output construction fails.
TableErrors –

If collect mode finds multiple failures.

Note

Warning-severity validation diagnostics are emitted as TalikaWarning and converted objects are still returned.

validate_table ⚓︎

validate_table(
    schema: type[TableT],
    datatable: RawTable | TableData,
    *,
    context: Mapping[str, Any] | ParseContext | None = None,
) -> ValidationResult[TableT]

Validate a table and return records or diagnostics without raising.

This is the functional equivalent of schema.validate(datatable). Output-model conversion is skipped, and invalid results never expose partially parsed records.

Parameters:

schema (type[TableT]) –

Concrete RowTable or ColumnTable subclass.
datatable (RawTable | TableData) –

Raw string rows or source-aware TableData.
context (Mapping[str, Any] | ParseContext | None, default: None ) –

Optional project data or existing parse context.

Returns:

ValidationResult[TableT] –

A frozen validation result containing complete records and ordered
ValidationResult[TableT] –

diagnostics. Warning-only results remain valid and retain records.

Note

Schema declaration errors and API misuse still raise because they are not authored table-data diagnostics.