Skip to content

Parsers⚓︎

parsers ⚓︎

Reusable field parsers and parser-composition helpers.

Every parser follows the same callable contract used by field(parser=...): it accepts the current value and a :class:~talika.CellContext. Parser factories return plain callable objects, so projects can use them directly, compose them, or mix them with custom functions.

Info

Parser factories in this module do not know BDD business vocabulary. They provide small, predictable conversion primitives that project schemas can combine into their own table language.

_OptionalParser dataclass ⚓︎

_OptionalParser(parser: Parser, none_values: frozenset[str], case_sensitive: bool)

Parser wrapper that converts configured null-like tokens to None.

Attributes:

  • parser (Parser) –

    Parser used when the value is not null-like.

  • none_values (frozenset[str]) –

    Normalized tokens that should become None.

  • case_sensitive (bool) –

    Whether null-token matching preserves case.

Info

Field declarations decide whether explicit empty cells reach this parser through empty="parse".

__call__ ⚓︎

__call__(value: Any, context: CellContext) -> Any

Return None for null-like input or delegate to the wrapped parser.

Parameters:

  • value (Any) –

    Current logical cell value.

  • context (CellContext) –

    Source-aware parser context for the active field.

Returns:

  • Any –

    None for empty or configured null tokens; otherwise the wrapped

  • Any –

    parser's result.

Warning

Empty strings are always treated as None by this wrapper. Use a custom parser when empty text is a meaningful domain value.

string ⚓︎

string(*, strip: bool = False, lower: bool = False, upper: bool = False) -> Parser

Return a parser that normalizes text.

Parameters:

  • strip (bool, default: False ) –

    Remove leading and trailing whitespace before case conversion.

  • lower (bool, default: False ) –

    Convert the resulting text to lowercase.

  • upper (bool, default: False ) –

    Convert the resulting text to uppercase.

Returns:

  • Parser –

    A parser that always returns str.

Raises:

  • ValueError –

    If both lower and upper are enabled.

Warning

This parser deliberately performs no semantic validation. Use choice() or a custom parser when the table cell must be one of a known set of values.

Example

class UserTable(RowTable):
    role = field("role", parser=string(strip=True, lower=True))

integer ⚓︎

integer(*, base: int = 10) -> Parser

Return a parser that converts values to int.

Parameters:

  • base (int, default: 10 ) –

    Numeric base used when the incoming value is a string.

Returns:

  • Parser –

    A parser that returns an integer.

Warning

The base is passed to Python's int(value, base) only for strings. Non-string values use int(value) so already-typed project values still follow Python's normal conversion rules.

Example

class Flags(RowTable):
    mask = field("mask", parser=integer(base=16))

floating ⚓︎

floating() -> Parser

Return a parser that converts values to float.

Returns:

  • Parser –

    A parser that returns a Python float.

Warning

Use decimal() instead when tests need exact decimal arithmetic or should avoid binary floating-point representation.

Example

class Product(RowTable):
    rating = field("rating", parser=floating())

decimal ⚓︎

decimal() -> Parser

Return a parser that converts through text to Decimal.

Returns:

  • Parser –

    A parser that returns decimal.Decimal.

Info

Conversion goes through str(value) so existing numeric objects and raw table text follow the same exact decimal path.

Example

class PriceTable(RowTable):
    total = field("total", parser=decimal())

boolean ⚓︎

boolean(
    *,
    true_values: Iterable[str] = ("true",),
    false_values: Iterable[str] = ("false",),
    case_sensitive: bool = False,
) -> Parser

Return a boolean parser with an explicit accepted vocabulary.

Parameters:

  • true_values (Iterable[str], default: ('true',) ) –

    Strings accepted as True.

  • false_values (Iterable[str], default: ('false',) ) –

    Strings accepted as False.

  • case_sensitive (bool, default: False ) –

    Whether matching should preserve case.

Returns:

  • Parser –

    A parser that returns bool.

Raises:

  • TypeError –

    If token collections or case_sensitive have invalid types.

  • ValueError –

    If the true and false token sets overlap.

The default vocabulary is deliberately small

Without configuration, the parser accepts only "true" and "false". Matching is case-insensitive by default, so "TRUE" and "False" also work. Words such as "yes" and "on" and numeric flags such as "1" must be declared by the schema.

Warning

Unknown values fail instead of falling back to Python truthiness. This prevents cells such as "False" or "nope" from accidentally becoming true.

Whitespace is not removed

" true " is different from "true". Compose string(strip=True) before this parser when the authored format permits padding.

Example

active = field(
    "active",
    parser=boolean(true_values=("Y",), false_values=("N",)),
)

choice ⚓︎

choice(*values: str, case_sensitive: bool = True) -> Parser

Return a parser that validates one allowed string value.

Parameters:

  • *values (str, default: () ) –

    Accepted display values.

  • case_sensitive (bool, default: True ) –

    Whether input must match the case of an accepted value.

Returns:

  • Parser –

    A parser that returns the canonical value from values.

Raises:

Info

With case_sensitive=False, the returned value is still the canonical spelling passed to the factory.

Example

role = field("role", parser=choice("admin", "editor", "viewer"))

split ⚓︎

split(
    separator: str = ",", *, strip_items: bool = True, keep_empty: bool = False
) -> Parser

Return a parser that splits one cell into a list of strings.

Parameters:

  • separator (str, default: ',' ) –

    Text separator used between items.

  • strip_items (bool, default: True ) –

    Strip whitespace around each split item.

  • keep_empty (bool, default: False ) –

    Preserve empty segments instead of filtering them out.

Returns:

  • Parser –

    A parser that returns list[str].

Raises:

Info

This parser is often paired with each(...) when a table cell holds a compact list of typed values.

Example

tags = field("tags", parser=split(","))

map_value ⚓︎

map_value(values: Mapping[str, Any], *, case_sensitive: bool = True) -> Parser

Return a parser that maps cell strings to Python values.

Parameters:

  • values (Mapping[str, Any]) –

    Mapping from table text to the Python value to return.

  • case_sensitive (bool, default: True ) –

    Whether lookup should preserve case.

Returns:

  • Parser –

    A parser that returns the mapped value.

Info

This is useful for compact BDD vocabulary such as "TBD" becoming a sentinel object or "high" becoming a domain enum value.

Example

priority = field("priority", parser=map_value({"low": 1, "high": 3}))

compose ⚓︎

compose(*parsers: Parser) -> Parser

Run parsers left-to-right.

Parameters:

  • *parsers (Parser, default: () ) –

    Parser callables following the talika parser contract.

Returns:

  • Parser –

    A parser that feeds each result into the next parser.

Raises:

Info

Every parser receives the same CellContext so later stages still know the original field, item ID, and source value.

Example

scores = field("scores", parser=compose(split(","), each(integer())))

each ⚓︎

each(parser: Parser) -> Parser

Apply one parser to every item in an iterable value.

Parameters:

  • parser (Parser) –

    Parser applied to each non-string item.

Returns:

  • Parser –

    A parser that returns list[Any].

Info

each() is designed for composition after parsers that produce a sequence, such as split().

Example

ids = field("ids", parser=compose(split(","), each(integer())))

optional ⚓︎

optional(
    parser: Parser,
    *,
    none_values: Iterable[str] = ("none", "null"),
    case_sensitive: bool = False,
) -> Parser

Return a parser that maps empty or null-like tokens to None.

Parameters:

  • parser (Parser) –

    Parser used for non-null values.

  • none_values (Iterable[str], default: ('none', 'null') ) –

    Text tokens that should parse as None.

  • case_sensitive (bool, default: False ) –

    Whether matching none_values should preserve case.

Returns:

  • Parser –

    A parser object that converts empty or configured null-like values to

  • Parser –

    None when the field invokes it.

Info

Use field(..., empty="parse") when an explicit blank cell should reach the returned parser. Without that field policy, blanks follow the field's normal empty-cell behavior.

Example

due_date = field("due", parser=optional(string(strip=True)))