Skip to content

Tables And Cells⚓︎

table ⚓︎

Source-aware table values used by parsing and table transformations.

The public schema API accepts ordinary list[list[str]] values because that is what pytest-bdd supplies to step functions. Internally, every raw string is wrapped in :class:TableCell so later stages can report the location of the original feature-file cell.

Projects that implement a custom table transformation may use these classes directly. A transformed cell should normally be created with source_cell.with_value(new_value). That keeps diagnostics attached to the cell syntax the user actually wrote.

Info

Raw input is accepted as ordinary Sequence[Sequence[str]]. The parser upgrades it to TableData before running transformations or schema validation.

TableCell dataclass ⚓︎

TableCell(
    value: str,
    source_row: int,
    source_column: int,
    source_value: str,
    source_uri: str | None = None,
)

One current table value and the feature cell from which it originated.

Attributes:

  • value (str) –

    The value currently consumed by schema parsing. A transformer may change this value.

  • source_row (int) –

    One-based row number of the original Gherkin data table cell.

  • source_column (int) –

    One-based column number of the original Gherkin data table cell.

  • source_value (str) –

    The exact value before any table transformation.

  • source_uri (str | None) –

    URI of the source document when known.

A transformer may produce several cells from one source cell. Each new cell can therefore have a different value while sharing the same source location and source_value.

Example

expanded = source_cell.with_value("Article")
assert expanded.source_value == "3:Article"

__post_init__ ⚓︎

__post_init__() -> None

Validate the immutable source-aware cell boundary.

from_value classmethod ⚓︎

from_value(value: str, *, row: int, column: int) -> TableCell

Create an untransformed cell at a source location.

Parameters:

  • value (str) –

    Raw text from the table.

  • row (int) –

    One-based source row.

  • column (int) –

    One-based source column.

Returns:

  • TableCell –

    A TableCell whose current value and source value are the same.

Info

One-based coordinates match feature-file diagnostics and user expectations when reading Gherkin data tables.

with_value ⚓︎

with_value(value: str) -> TableCell

Return a changed cell that still points to this cell's source.

This is the preferred way for a table transformer to replace or expand syntax. For example, a source cell containing 3:Article may produce three cells whose current value is Article while all three still point back to the original 3:Article cell.

Parameters:

  • value (str) –

    New logical value consumed by later parsing stages.

Returns:

  • TableCell –

    A new TableCell with updated value and preserved source

  • TableCell –

    location/value.

Warning

Constructing fresh cells manually can lose original coordinates. Use this method inside transformers whenever a logical value derives from an existing source cell.

TableData dataclass ⚓︎

TableData(rows: tuple[tuple[TableCell, ...], ...], source_uri: str | None = None)

An immutable, source-aware representation of a Gherkin data table.

TableData intentionally provides only a few explicit operations. It is not a second table-processing framework. Its job is to carry current cell values and original source locations through the schema lifecycle.

Attributes:

  • rows (tuple[tuple[TableCell, ...], ...]) –

    Immutable rows of immutable TableCell tuples.

  • source_uri (str | None) –

    URI of the source document when known.

Info

Direct construction validates every cell and normalizes nested row sequences to tuples, so mutable input lists cannot change the stored table after construction.

__post_init__ ⚓︎

__post_init__() -> None

Validate cells and normalize directly constructed rows to tuples.

from_rows classmethod ⚓︎

from_rows(rows: RawTable, *, source: str | Path | None = None) -> TableData

Wrap ordinary string rows while recording source locations.

Parameters:

  • rows (RawTable) –

    Raw Gherkin data table rows, typically from pytest-bdd.

  • source (str | Path | None, default: None ) –

    Optional URI string or filesystem path for provenance.

Returns:

  • TableData –

    A source-aware TableData instance.

Example

table = TableData.from_rows([["name"], ["Alice"]])
assert table.cell(2, 1).source_row == 2

from_cells classmethod ⚓︎

from_cells(
    rows: Sequence[Sequence[TableCell]], *, source: str | Path | None = None
) -> TableData

Build a table from cells whose source information already exists.

Custom transformers use this constructor after arranging existing or transformed cells into their new logical table shape.

Parameters:

  • rows (Sequence[Sequence[TableCell]]) –

    Logical rows of source-aware cells.

  • source (str | Path | None, default: None ) –

    Optional URI string or filesystem path for provenance.

Returns:

  • TableData –

    A TableData instance containing immutable row/cell tuples.

Warning

This constructor trusts that cells already preserve useful source information. Prefer cell.with_value(...) when transforming.

ensure classmethod ⚓︎

ensure(table: RawTable | TableData) -> TableData

Return table as TableData.

Parameters:

  • table (RawTable | TableData) –

    Existing source-aware table or raw string rows.

Returns:

  • TableData –

    table unchanged when already source-aware, otherwise a new

  • TableData –

    TableData created from raw rows.

Info

Schema parsing calls this at the boundary so downstream code can work only with source-aware cells.

cell ⚓︎

cell(row: int, column: int) -> TableCell

Return a cell using one-based row and column indexes.

One-based indexes match the coordinates shown in Gherkin data table errors and make transformer code easier to compare with a feature file.

Parameters:

  • row (int) –

    One-based row number.

  • column (int) –

    One-based column number.

Returns:

Raises:

  • IndexError –

    If indexes are less than one or outside the table.

Warning

This helper is for human-facing coordinates. Use rows directly for zero-based Python iteration.

to_rows ⚓︎

to_rows() -> list[list[str]]

Return current values as ordinary mutable string rows.

Returns:

  • list[list[str]] –

    A new list[list[str]] containing each cell's current value.

Info

Source metadata is intentionally dropped. This method is useful for display, debugging, and compatibility with code expecting raw rows.

with_source ⚓︎

with_source(source: str | Path) -> TableData

Return this table with normalized source provenance attached.