Fields⚓︎

fields ⚓︎

Schema field declarations.

Field declarations are descriptors collected by the schema metaclass. They describe how Gherkin data table labels map to Python attributes, which values are required, and how raw cell text should be converted.

Info

Labels are literal project vocabulary. talika does not infer meaning from characters such as * unless the schema explicitly sets options such as required=True.

ReferenceSpec `dataclass` ⚓︎

ReferenceSpec(target: str, many: bool, separator: str)

Configure local ID resolution within the same parsed table.

Attributes:

target (str) –

Attribute name on the referenced record used as the lookup key.
many (bool) –

Whether the source cell contains several references.
separator (str) –

Text separator used when many is true.

Info

Reference resolution happens after records are constructed and before record/table validation hooks run.

Field `dataclass` ⚓︎

Field(
    label: str | None,
    aliases: tuple[str, ...] = (),
    required: bool = False,
    default: Any = MISSING,
    default_factory: DefaultFactory | object = MISSING,
    parser: Parser | None = None,
    empty: str = "raw",
    is_id: bool = False,
    is_discriminator: bool = False,
    variants: Mapping[Any, type] | None = None,
    reference: ReferenceSpec | None = None,
    name: str = "",
)

Store one declared schema field and its conversion behavior.

Attributes:

label (str | None) –

Canonical Gherkin data table label. None is accepted only while an ordinary field() waits for its Python attribute name.
aliases (tuple[str, ...]) –

Alternate accepted labels for evolving feature vocabulary.
required (bool) –

Whether the field must be present and non-empty.
default (Any) –

Static value used when an optional field is absent.
default_factory (DefaultFactory | object) –

Context-aware factory used when an optional field is absent.
parser (Parser | None) –

Optional callable used to convert non-empty cell values.
empty (str) –

Effective policy for explicit empty cells.
is_id (bool) –

Whether this field identifies column-oriented records.
is_discriminator (bool) –

Whether this field selects record variants.
variants (Mapping[Any, type] | None) –

Declarative discriminator component mapping.
reference (ReferenceSpec | None) –

Optional local-record reference configuration.
name (str) –

Python attribute name assigned by the schema class body.

Warning

Field instances are mutable during class creation because __set_name__ records their Python attribute name. Schema inheritance uses clone() to avoid sharing that mutable state. The declaration is frozen after its schema plan is compiled.

labels `property` ⚓︎

labels: tuple[str, ...]

Return the canonical label followed by accepted aliases.

Returns:

tuple[str, ...] –

Tuple used during label matching and duplicate-label validation.

Info

Canonical label order is preserved so introspection can present the preferred table vocabulary first.

setattr ⚓︎

__setattr__(name: str, value: Any) -> None

Set declaration metadata while the field is being compiled.

Compiled declarations are immutable. Parsed record assignment still uses :meth:__set__ and is deliberately unaffected by this guard.

clone ⚓︎

clone() -> Field

Return an independent declaration for schema inheritance.

Returns:

Field –

A new Field with the same declaration options.

Info

Schema subclasses receive cloned fields so changing an inferred parser or descriptor name on one schema does not mutate its base schema's declaration.

__set_name__ ⚓︎

__set_name__(owner: type, name: str) -> None

Record the Python attribute name assigned by a schema class.

Parameters:

owner (type) –

Schema class receiving the descriptor.
name (str) –

Attribute name used in the class body.

Info

The table label and the Python attribute name are intentionally separate so feature files can use human-facing language while code keeps normal Python identifiers.

_freeze ⚓︎

_freeze() -> None

Freeze declaration metadata after schema compilation.

get ⚓︎

__get__(instance: object | None, owner: type | None = None) -> Any

Return the declaration on classes or parsed value on records.

Parameters:

instance (object | None) –

Parsed record instance, or None during class access.
owner (type | None, default: None ) –

Owning schema class.

Returns:

Any –

The Field declaration when accessed on a class, otherwise the
Any –

parsed attribute value stored on the record.

Warning

Parsed records are created through the schema lifecycle. Accessing a descriptor-backed attribute before construction populates the instance dictionary will raise KeyError.

set ⚓︎

__set__(instance: object, value: Any) -> None

Store a parsed value on a record instance.

Parameters:

instance (object) –

Parsed record object being populated.
value (Any) –

Parsed field value.

Info

Assignment is intentionally direct. Validation and conversion have already happened before values are attached to records.

_validate_field_options ⚓︎

_validate_field_options(
    label: str | None,
    aliases: Sequence[str],
    *,
    allow_implicit_label: bool = False,
    required: bool,
    default: Any,
    default_factory: DefaultFactory | object,
    parser: Parser | None = None,
    empty: str | None = None,
) -> tuple[tuple[str, ...], str]

Validate declaration options shared by field constructors.

Parameters:

label (str | None) –

Canonical table label, or None for an implicit ordinary field label.
aliases (Sequence[str]) –

Alternate accepted labels.
allow_implicit_label (bool, default: False ) –

Whether None may be resolved from the Python attribute name during class creation.
required (bool) –

Whether a value is required.
default (Any) –

Static default value or MISSING.
default_factory (DefaultFactory | object) –

Context-aware default factory or MISSING.
parser (Parser | None, default: None ) –

Optional value parser.
empty (str | None, default: None ) –

Explicit empty-cell policy, or None to choose "error" for required fields and "raw" for optional fields.

Returns:

tuple[tuple[str, ...], str] –

Aliases normalized to a tuple and the effective empty-cell policy.

Raises:

ValueError –

If labels/defaults are internally contradictory.
TypeError –

If default_factory is present but not callable.

Warning

Required fields cannot declare defaults because that would make missing table data appear valid.

field ⚓︎

field(
    label: str | None = None,
    *,
    required: bool = False,
    default: Any = MISSING,
    default_factory: DefaultFactory | object = MISSING,
    parser: Parser | None = None,
    aliases: Sequence[str] = (),
    empty: str | None = None,
) -> Any

Declare a row or column in a table schema.

The Python attribute name becomes the table label when label is omitted. Empty cells are controlled only by empty; parser objects do not opt into blank handling implicitly.

Parameters:

label (str | None, default: None ) –

Canonical Gherkin data table label. When omitted, use the Python attribute name.
required (bool, default: False ) –

Whether the field must be present and non-empty.
default (Any, default: MISSING ) –

Static value used when the entire field is absent.
default_factory (DefaultFactory | object, default: MISSING ) –

Factory called for an absent optional field.
parser (Parser | None, default: None ) –

Optional parser for non-empty values.
aliases (Sequence[str], default: () ) –

Alternate accepted table labels.
empty (str | None, default: None ) –

Policy for explicit empty cells. When omitted, required fields use "error" and optional fields use "raw". "parse" sends an empty string through the parser, "none" returns None, and "error" rejects it.

Returns:

Any –

A descriptor collected by RowTable or ColumnTable subclasses.

Raises:

TypeError –

If labels, aliases, parsers, factories, or defaults have an invalid runtime shape.
ValueError –

If required/default/empty options contradict each other or an empty policy is unknown.

Example

class UserTable(RowTable):
    name = field(required=True)
    role = field("role", default="viewer", aliases=("type",))

id_field ⚓︎

id_field(
    label: str, *, parser: Parser | None = None, aliases: Sequence[str] = ()
) -> Any

Declare the item identifier field for parsed records.

Parameters:

label (str) –

Canonical ID row label.
parser (Parser | None, default: None ) –

Optional parser for ID values.
aliases (Sequence[str], default: () ) –

Alternate accepted ID row labels.

Returns:

Any –

A required identifier Field descriptor.

Warning

A column-oriented table must declare exactly one ID field. A row-oriented table may declare one when parser contexts, defaults, and diagnostics need a stable item_id.

discriminator_field ⚓︎

discriminator_field(
    label: str, *, parser: Parser | None = None, aliases: Sequence[str] = ()
) -> Any

Declare the field used to select registered record variants.

A discriminator is always required because the parser cannot choose a variant without it. The optional parser runs before variant lookup, so a project may register enum members or other typed values as variant keys.

Declaring this field does not enable variants by itself. Register variant schema subclasses with @BaseSchema.variant(value).

Parameters:

label (str) –

Canonical discriminator label.
parser (Parser | None, default: None ) –

Optional parser that runs before variant lookup.
aliases (Sequence[str], default: () ) –

Alternate accepted labels.

Returns:

Any –

A required discriminator Field descriptor.

Example

class ContentTable(ColumnTable):
    content_type = discriminator_field("Type*")

discriminator ⚓︎

discriminator(
    label: str,
    *,
    variants: Mapping[Any, type],
    parser: Parser | None = None,
    aliases: Sequence[str] = (),
) -> Any

Declare a discriminator and variant field components together.

variants maps parsed discriminator values to TableFields subclasses. When the containing table schema is created, talika composes each component with that schema and registers the resulting record variant automatically.

This is the concise alternative to discriminator_field() plus @Table.variant(value) classes. The explicit decorator form remains useful when a project prefers named variant schema classes.

Parameters:

label (str) –

Canonical discriminator label.
variants (Mapping[Any, type]) –

Mapping from parsed discriminator values to TableFields component classes.
parser (Parser | None, default: None ) –

Optional parser that runs before variant lookup.
aliases (Sequence[str], default: () ) –

Alternate accepted labels.

Returns:

Any –

A required discriminator Field descriptor with variant metadata.

Raises:

TypeError –

If variants is not a mapping.
ValueError –

If variants is empty.

Example

content_type = discriminator(
    "Type*",
    variants={"Article": ArticleFields, "Poll": PollFields},
)

reference ⚓︎

reference(
    label: str,
    *,
    target: str = "id",
    many: bool = False,
    separator: str = ",",
    required: bool = False,
    default: Any = MISSING,
    aliases: Sequence[str] = (),
) -> Any

Declare a local reference to another parsed record in the same table.

The raw cell contains one target value, or a separator-delimited list when many=True. Resolution occurs after all records are constructed and before validation hooks run.

Parameters:

label (str) –

Canonical table label containing reference keys.
target (str, default: 'id' ) –

Attribute on records used as the lookup key.
many (bool, default: False ) –

Whether the cell contains several keys.
separator (str, default: ',' ) –

Separator used when many is true.
required (bool, default: False ) –

Whether the reference cell must be present and non-empty.
default (Any, default: MISSING ) –

Static value used when an optional reference field is absent.
aliases (Sequence[str], default: () ) –

Alternate accepted table labels.

Returns:

Any –

A Field descriptor whose parsed value is resolved to record
Any –

objects.

Raises:

ValueError –

If many=True and separator is empty.

Warning

Reference keys are parsed with the target field's parser before lookup. Keep separators distinct from valid key text when using many=True.

Fields⚓︎

fields ⚓︎

ReferenceSpec dataclass ⚓︎

Field dataclass ⚓︎

labels property ⚓︎

__setattr__ ⚓︎

clone ⚓︎

__set_name__ ⚓︎

_freeze ⚓︎

__get__ ⚓︎

__set__ ⚓︎

_validate_field_options ⚓︎

field ⚓︎

id_field ⚓︎

discriminator_field ⚓︎

discriminator ⚓︎

reference ⚓︎

ReferenceSpec `dataclass` ⚓︎

Field `dataclass` ⚓︎

labels `property` ⚓︎

setattr ⚓︎

get ⚓︎

set ⚓︎