Data

Data types and value wrappers for the UI Generator system.

This module provides a comprehensive type system for representing and validating data values in UI definitions. It includes type-safe wrappers for primitive and complex data types, along with configuration enums and filter modes.

Main Components

Configuration Enums:

• DefaultValueType: Specifies the source of default values (FIELD or NAMED_VALUE)

• DefaultValueBehaviour: Controls how defaults interact with user overrides

• DataValidationType: Defines validation types (LIST or RANGE)

• ValidationFlag: Specifies boundary inclusion/exclusion for range validation

Value Classes:

All value classes extend the generic Value[T] base class and are serializable to JSON with type information.

Primitive Values:

• IntegerValue, StringValue, BooleanValue, DecimalValue

• DateValue, TimeValue, DateTimeValue

Array Values:

• IntegerArrayValue, StringArrayValue, BooleanArrayValue, DecimalArrayValue

• DateArrayValue, TimeArrayValue, DateTimeArrayValue

Object References:

• ObjectValue: References a single row by rowUid or stringKey

• ObjectArrayValue: References multiple rows

Map Values:

Maps associate row identifiers with typed values: - IntegerMapValue, DecimalMapValue, StringMapValue, BooleanMapValue - DateMapValue, TimeMapValue, DateTimeMapValue

Filter Classes:

• ObjectReferenceFilter: References source table/field for filtering

• FilterMode: Base class for filter mode definitions

• MatchRowFilterMode: Filters by matching row index from context variable

• MatchFieldFilterMode: Filters by matching field value from context variable

Base Classes:

• Value[T]: Generic base class for all value types

• MapValue[T]: Generic base class for map types

• Condition: Base class for conditional logic (supports negation)

Type Safety and Validation

All classes use @typechecked decorators and implement validation in __post_init__ or __init__ methods to ensure type correctness at runtime. Date/time values are serialized to arrays for JSON compatibility ([year, month, day] format, etc.).

Examples

Creating values:

# Primitive value
age = IntegerValue(25)

# Array value
tags = StringArrayValue(["python", "ui", "generator"])

# Date value (serializes to [2024, 1, 15])
start_date = DateValue(date(2024, 1, 15))

# Object reference by row number
user = ObjectValue(row_num=42)

# Object reference by string key (requires table with id_field)
user = ObjectValue(string_key="user_123", table=user_table)

# Map value
scores = IntegerMapValue({"row1": 100, "row2": 95})

class DefaultValueType(*values)

Bases: Enum

Specifies the source type of the default value.

FIELD

The default value is derived from another field.

NAMED_VALUE

The default value is specified as a named constant or parameter.

FIELD = 'FIELD'

NAMED_VALUE = 'NAMED_VALUE'

class DefaultValueBehaviour(*values)

Bases: Enum

Specifies how the default value behaves in relation to user-overridden values.

DEFAULT

If the current value differs from the reference value, a reset icon is shown to restore it.

REFERENCE_WITH_OVERRIDE

The reference value is shown when the underlying value is blank. If a user enters a value, it overrides the reference, and a reset icon will clear it.

DEFAULT = 'DEFAULT'

REFERENCE_WITH_OVERRIDE = 'REFERENCE_WITH_OVERRIDE'

class DataValidationType(*values)

Bases: Enum

The type of data validation to apply.

LIST

The value must match an item in a predefined list (like a dropdown).

RANGE

The value must fall within a minimum and maximum range.

LIST = 'LIST'

RANGE = 'RANGE'

class ValidationFlag(*values)

Bases: Enum

Specifies whether the range boundaries are inclusive or exclusive.

INCLUSIVE

The boundary values (min and max) are included as valid values.

EXCLUSIVE

The boundary values are excluded from the valid range.

INCLUSIVE = 'INCLUSIVE'

EXCLUSIVE = 'EXCLUSIVE'

class Value(value)

Bases: Generic[T], Buildable

Base class for all value types in the UI generator.

This generic class wraps primitive and complex values, providing a consistent interface for building and retrieving typed values.

value

The underlying value of generic type T.

Type:

T

value: T

get_value()

Retrieve the underlying value.

Returns:

The stored value of type T.

Return type:

T

class IntegerValue(value)

Bases: Value[int]

Represents a single integer value.

This class wraps an integer value for use in the UI definition system.

class StringValue(value)

Bases: Value[str]

Represents a single string value.

This class wraps a string value for use in the UI definition system.

class BooleanValue(value)

Bases: Value[bool]

Represents a single boolean value.

This class wraps a boolean value for use in the UI definition system.

class DecimalValue(value)

Bases: Value[float]

Represents a single decimal (floating-point) value.

This class wraps a float value for use in the UI definition system.

class IntegerArrayValue(value)

Bases: Value[list[int]]

Represents an array of integer values.

This class wraps a list of integers for use in the UI definition system. Validates that all items in the array are integers.

Raises:

TypeError – If the value is not a list or if any item is not an integer.

class StringArrayValue(value)

Bases: Value[list[str]]

Represents an array of string values.

This class wraps a list of strings for use in the UI definition system. Validates that all items in the array are strings.

Raises:

TypeError – If the value is not a list or if any item is not a string.

class BooleanArrayValue(value)

Bases: Value[list[bool]]

Represents an array of boolean values.

This class wraps a list of booleans for use in the UI definition system. Validates that all items in the array are booleans.

Raises:

TypeError – If the value is not a list or if any item is not a boolean.

class DecimalArrayValue(value)

Bases: Value[list[float]]

Represents an array of decimal (floating-point) values.

This class wraps a list of floats for use in the UI definition system. Validates that all items in the array are numeric (int or float).

Raises:

TypeError – If the value is not a list or if any item is not numeric.

class DateValue(value)

Bases: Value[date]

Represents a single date value.

This class wraps a Python date object for the UI definition system.

class DateArrayValue(value)

Bases: Value[list[date]]

Represents an array of date values.

This class wraps a list of Python date objects for the UI definition system.

Raises:

TypeError – If the value is not a list or if any item is not a date object.

class TimeValue(value)

Bases: Value[time]

Represents a single time value.

This class wraps a Python time object for the UI definition system.

class TimeArrayValue(value)

Bases: Value[list[time]]

Represents an array of time values.

This class wraps a list of Python time objects and serializes each as [hour, minute, second] for the UI definition system.

Raises:

TypeError – If the value is not a list or if any item is not a time object.

class DateTimeValue(value)

Bases: Value[datetime]

Represents a single datetime value.

This class wraps a Python datetime object for the UI definition system.

class DateTimeArrayValue(value)

Bases: Value[list[datetime]]

Represents an array of datetime values.

This class wraps a list of Python datetime objects for the UI definition system.

Raises:

TypeError – If the value is not a list or if any item is not a datetime object.

class ObjectValue(table, row_num=None, string_key=None)

Bases: Value[dict]

Represents an object row reference.

Exactly one of (row_num, string_key) must be provided.

• row_num -> serialises to: {“rowUid”: <int>}

• string_key -> serialises to: {“stringKey”: <str>} Only valid if the referenced table has an id_field.

class ObjectArrayValue(objects)

Bases: Value[list[dict]]

Represents an array of object row references.

Each element must be either:

• row_num -> {“rowUid”: <int>}

• string_key -> {“stringKey”: <str>} Only valid if the referenced table has an id_field.

class MapValue(value)

Bases: Value[dict[int, T]]

Base class for all MAP values.

Maps associate row identifiers (string keys) with primitive values of type T. This provides a dictionary-like structure for mapping rows to values in the UI.

value

The underlying dictionary mapping row IDs to values.

Type:

dict[int, T]

add_mapping(row, value)

Add or update a row-to-value mapping.

Parameters:

• row (int) – The row identifier (key).

• value (TypeVar(T)) – The value to associate with this row.

Return type:

None

class IntegerMapValue(value)

Bases: MapValue[int]

Represents a map of row identifiers to integer values.

This class wraps a dictionary with string keys and integer values for use in the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not integers.

class DecimalMapValue(value)

Bases: MapValue[float]

Represents a map of row identifiers to decimal (floating-point) values.

This class wraps a dictionary with string keys and numeric (int or float) values for use in the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not numeric.

class StringMapValue(value)

Bases: MapValue[str]

Represents a map of row identifiers to string values.

This class wraps a dictionary with string keys and string values for use in the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not strings.

class BooleanMapValue(value)

Bases: MapValue[bool]

Represents a map of row identifiers to boolean values.

This class wraps a dictionary with string keys and boolean values for use in the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not booleans.

class DateMapValue(value)

Bases: MapValue[date]

Represents a map of row identifiers to date values.

This class wraps a dictionary with string keys and date values, for the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not date objects (datetime objects are not allowed).

class TimeMapValue(value)

Bases: MapValue[time]

Represents a map of row identifiers to time values.

This class wraps a dictionary with string keys and time values for the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not time objects.

class DateTimeMapValue(value)

Bases: MapValue[datetime]

Represents a map of row identifiers to datetime values.

This class wraps a dictionary with string keys and datetime values, for the UI definition system.

Raises:

TypeError – If the value is not a dict, if keys are not strings, or if values are not datetime objects.

class ObjectReferenceFilter(source_table, source_field)

Bases: Buildable

Represents a reference to a source table and field used in filtering.

source_table

The name of the source table.

Type:

str

source_field

The field in the source table.

Type:

str

source_table: str

source_field: str

class FilterMode(context_variable_ids=<factory>, object_reference_filter=None)

Bases: Buildable

Base class for defining filter modes in a UI model.

context_variable_ids

A mapping of context variable names to their associated IDs.

Type:

Dict[str, str]

object_reference_filter

When populated, specifies an external table and field to use as the source of the filter value.

Type:

Optional[ObjectReferenceFilter]

context_variable_ids: dict[str, str]

object_reference_filter: ObjectReferenceFilter | None = None

class MatchRowFilterMode(context_variable_ids=<factory>, object_reference_filter=None)

Bases: FilterMode

Filter mode that matches rows based on a context variable identifying the row index.

This filter mode uses a context variable containing a row index to filter and display only the matching row.

set_filter_row(filter_row)

Set the context variable used to identify the row for filtering.

Parameters:

filter_row (str) – The ID of the context variable containing the row index.

class MatchFieldFilterMode(context_variable_ids=<factory>, object_reference_filter=None, filter_target_field=None)

Bases: FilterMode

Filter mode that matches rows based on a comparison between a context variable value and a target field value in the table.

This filter mode compares a context variable’s value against a specified field in the table, displaying only rows where the field value matches.

filter_target_field

The field in the target table to compare against.

Type:

Optional[str]

filter_target_field: str | None = None

set_filter_source_value(filter_source_value)

Set the context variable that provides the source value for filtering.

Parameters:

filter_source_value (str) – The ID of the context variable containing the value to match against the target field.

class Condition(negate=False)

Bases: Buildable

Base condition class. Supports logical negation.

negate

If True, the result of the condition will be logically negated.

negate: bool = False