Skip to content

Annotation Parsers⚓︎

annotations ⚓︎

Infer field parsers from supported Python type annotations.

This module keeps annotation handling intentionally conservative. It only infers parsers for types with obvious, local conversion semantics and returns None for annotations that should remain raw text.

Info

Explicit field(parser=...) values always win. Annotation inference is a convenience for common schema declarations, not a second parser registry.

annotation_accepts_raw_text ⚓︎

annotation_accepts_raw_text(annotation: Any) -> bool

Return whether arbitrary unparsed cell text fits an annotation.

Parameters:

  • annotation (Any) –

    Resolved annotation attached to a schema field.

Returns:

  • bool –

    True for Any, object, str, or a union containing one

  • bool –

    of those types. Literal annotations return False because an

  • bool –

    arbitrary cell is not guaranteed to match their finite vocabulary.

Info

This helper validates only Talika's raw-text path. It does not inspect or constrain values returned by explicit project parsers.

annotation_accepts_value ⚓︎

annotation_accepts_value(annotation: Any, value: Any) -> bool

Return whether one framework-created value fits an annotation.

Parameters:

  • annotation (Any) –

    Resolved field annotation.

  • value (Any) –

    Missing, empty-policy, or static-default value created directly by Talika.

Returns:

  • bool –

    Whether the value matches common runtime-checkable annotations.

  • bool –

    Unsupported typing constructs are treated conservatively as not

  • bool –

    matching unless they expose a runtime origin that accepts the value.

Warning

This is deliberately not a general-purpose Python type checker. It is used only for declaration paths controlled by the framework.

parser_for_annotation ⚓︎

parser_for_annotation(annotation: Any) -> Parser | None

Return a parser for one supported annotation.

Parameters:

  • annotation (Any) –

    The runtime annotation object gathered from a schema attribute, usually through typing.get_type_hints.

Returns:

  • Parser | None –

    A parser compatible with field(parser=...) when the annotation is

  • Parser | None –

    supported, or None when Talika cannot infer a conversion. Schema

  • Parser | None –

    compilation then verifies whether an unparsed string is compatible

  • Parser | None –

    with the annotation.

Info

Supported annotations are str, int, float, bool, Decimal, enums, string Literal values, and optional unions containing exactly one non-None type.

Warning

Unsupported unions deliberately return None. This prevents ambiguous coercion when more than one non-null type could accept the same cell text.

Example

class UserTable(RowTable):
    age: int = field("age", required=True)
    reviewer: int | None = field("reviewer", empty="parse")

_identity ⚓︎

_identity(value: Any, context: Any) -> Any

Return value unchanged for composed inferred parsers.

Parameters:

  • value (Any) –

    Current parser input.

  • context (Any) –

    Parser context supplied by the schema lifecycle.

Returns:

  • Any –

    The same object received as value.

Info

This helper is used inside inferred Optional parsers when the inner annotation means "keep this value as-is".

_enum_parser ⚓︎

_enum_parser(enum_type: type[Enum]) -> Parser

Return a parser that matches enum values before member names.

Parameters:

  • enum_type (type[Enum]) –

    Enum subclass used by a schema field annotation.

Returns:

  • Parser –

    A parser that converts cell text into a member of enum_type.

Info

Matching enum values first lets feature files use domain-facing values while still accepting member names for tests that prefer Python identifiers.