Fields

Fields are the columns of a table. Every field has an id, a data type, and optional Validator instances. Three concrete field types differ in where the value comes from:

• DataField — imported data, with an optional default value.

• CalculatedField — value computed by a Formula.

• ComboField — carries both a formula and a stored value; the calculate_in_optimiser flag decides whether the optimiser evaluates the formula (True) or reads the stored value (False). The opposite mode is used outside optimisation, e.g. when the field is rendered in the UI.

Field hierarchy: Field base + the three concrete field types (DataField, CalculatedField, ComboField).

A field is a column on a Table. Each field carries an id, a data type, and an optional set of Validator instances. Concrete field types differ in where the value comes from — imported data, a formula, or a hybrid that switches between the two.

class Field(id, table, data_type)

Abstract base for a column on a Table.

Use the concrete subclasses DataField, CalculatedField, and ComboField rather than constructing Field directly. Every field has an id, an owning table, and a data_type; optionally an order_index, a description, and zero or more Validator instances (at most one per Severity).

table_id

The owning table’s id.

data_type

The BaseDataType of this field.

order_index: int | None

Order in which this field appears in the table (lower comes first).

description: str | None

Free-text description shown in the UI.

property table: Table

The Table that owns this field.

property tracking_group: str | None

Tracking-group identifier, or None when change tracking is disabled.

property tracking_id: str

ID of the matching tracking field, or empty string when this field is not tracked.

set_order_index(idx)

Set the field’s position within its table (lower values come first).

Return type:

Field

set_description(desc)

Set the field’s free-text description.

Return type:

Field

set_tracking_group(group)

Enable change tracking by assigning this field to a tracking group.

When set, build() generates a sibling <group>_TRACKING_<id> field; references to other tracked fields within the same group are rewritten to their tracking ids.

Return type:

Field

to_string()

Return type:

str

to_data_type()

Return type:

BaseDataType

add_validator(validator)

Attach a Validator to this field.

Each field may carry at most one validator per Severity.

Raises:

ValueError – If a validator with the same severity is already attached.

Return type:

None

get_validation_fields(severity=None)

Return the synthetic validation fields generated for this field’s validators.

Parameters:

severity (Severity | None) – When given, return only the validation fields for that severity. When None, return one ValidationFieldsContainer per attached validator, sorted by ascending severity rank.

Return type:

list[ValidationFieldsContainer] | ValidationFieldsContainer | None

Returns:

A single ValidationFieldsContainer, a list of them, or None if no validator matches.

get_combined_message_field()

Return a single calculated field combining all per-severity messages.

The combined field is a STRING_ARRAY ordered from highest to lowest severity (CRITICAL → ERROR → WARNING → INFO); blank messages are excluded. The field is registered on the table as {id}__message__combined on first call and cached for subsequent calls.

Return type:

Field | None

Returns:

The combined-message field, or None if this field has no validators. When exactly one validator is attached, that validator’s existing message field is returned directly.

class CalculatedField(id, table, formula)

A field whose value is computed by a Formula.

The field’s data type is taken from the formula. Calculated fields are read-only — their value is recomputed whenever inputs change.

formula

The formula evaluated to produce this field’s value.

class DataField(id, table, data_type)

A field populated from imported data or an optional default value.

default_value: Any

Default value applied when no imported value is present.

import_format: str | None

Import format hint (e.g. a date pattern) applied when parsing input rows.

unique: bool

Whether values in this column must be unique within the table.

nullable: bool

Whether this field accepts null/blank values.

set_default_value(value)

Set the default value used when no imported value is present.

Return type:

DataField

set_import_format(fmt)

Set the import format hint applied when parsing this field on import.

Return type:

DataField

set_unique(unique)

Require values in this column to be unique within the table.

Return type:

DataField

set_nullable(nullable)

Allow null/blank values in this column.

Return type:

DataField

class ComboField(id, table, formula, calculate_in_optimiser)

A field that switches between data and calculated behaviour.

Combo fields carry a Formula and an underlying stored value. The calculate_in_optimiser flag chooses which one the optimiser sees:

• calculate_in_optimiser=True: the optimiser evaluates the formula (treating the field as a CalculatedField), while outside optimisation the stored data value is used.

• calculate_in_optimiser=False: the optimiser uses the stored data value (treating the field as a DataField), while outside optimisation — for example when the field is rendered in the UI — the formula is evaluated (treating the field as a CalculatedField).

formula

Formula evaluated when the field is treated as calculated.

calculate_in_optimiser

Selects whether the optimiser evaluates the formula or reads the stored value. See the class docstring for the full behaviour.

default_value: Any

Default value applied when no imported value is present.

import_format: str | None

Import format hint applied when parsing input rows.

set_default_value(value)

Set the default value used when no imported value is present.

Return type:

ComboField

set_import_format(fmt)

Set the import format hint applied when parsing this field on import.

Return type:

ComboField