dataclass.gdimData

Classes

class dataclass.gdimData.SerializableDict

A dictionary that automatically converts non-serializable numpy values.

Inherits from:: dict

Methods:

update() → None: Override update to clean values before storing.

class dataclass.gdimData.GdimWidgetDataStructure

The widget data structure in GDIM table with configurable validation capabilities.

This class provides widget metadata and validation functionality for GDIM table data.
It supports both individual value validation and efficient DataFrame column validation
using vectorized pandas operations where possible.

The validation system offers two independent configuration dimensions:

#. DateTime Strictness (strict_datetime_validation):
   - True: Regex + datetime parsing validation (slower, 100% accurate)
   - False: Regex-only validation (faster, ~99.9% accurate)

#. Validation Level (validation_level):
   - "full": Complete structural validation for complex types (file, address, texture)
   - "fast": Basic type checking only for complex types (faster)

Performance Matrix (truly independent settings):
- validation_level="fast" + strict_datetime_validation=False: Maximum speed
- validation_level="fast" + strict_datetime_validation=True: Fast structures + accurate dates
- validation_level="full" + strict_datetime_validation=False: Complete structures + fast dates
- validation_level="full" + strict_datetime_validation=True: Maximum accuracy (default)

Methods:

__init__(strict_datetime_validation: bool = True, validation_level: Literal[fast, full] = 'full')

Initialize the widget data structure.

Parameters

validation_levelValidation complexity level:

“fast”: Only vectorized operations + basic type checks (fastest)
“full”: Complete validation including complex structure checks (slower, most accurate)

Default is “full” for maximum data quality.

get_regex_pattern(cls, pattern: str): Get compiled regex pattern with caching for efficiency.

validate_single_value(widget_type: str, value: any, data_format: str | None = None) → bool

Validate a single value for a specific widget type.

Parameters

value : The value to validate

data_format : Optional data format specification for the widget

Returns

bool: True if the value is valid for the widget type, False otherwise

validate_series(widget_type: str, series: pd.Series, data_format: str | None = None) → pd.Series

Validate a pandas Series for a specific widget type using vectorized operations.

Parameters

series : The pandas Series to validate

data_format : Optional data format specification for the widget

Returns

pd.Series: Boolean series indicating which values are valid

validate_dataframe(df: pd.DataFrame, table_metadata: GdimTableMetaData, raise_error: bool = False) → tuple[dict[str, pd.Series], list[str]]

Validate all columns in a DataFrame using table metadata.

Parameters

df : The DataFrame to validate

table_metadata : Table metadata containing field information

Returns

dict: Column name -> boolean Series indicating valid rows for each column list: Column names that are not in the table metadata

get_validation_summary(validation_results: dict[str, pd.Series]) → dict[str, dict]

Get a summary of validation results.

Parameters

validation_results : Results from validate_dataframe

Returns

dict: Summary including total/valid/invalid counts per column

Properties:

widget_names: The names of the widgets.

widget_titles: The titles of the widgets.

widget_data_types: The data types of the widgets.

Attributes:

all_widgets = <ast.Dict object at 0x0000017357E73400>

data_format_configs = <ast.Dict object at 0x0000017357E72620>

class dataclass.gdimData.GdimFieldMetadata

The metadata of a field in a table.

Inherits from:: BaseModel

Methods:

to_pandas_dtype() → str

Returns

Any

and data_format.

Mapping
- ````"number"```` + ````data_format == "integer"````                       → ````"Int64"```` (pandas nullable integer)
- ````"number"```` + ````data_format == "realNumber"```` or ````None````        → ````"float64"````
- ````"dateTime"```` + ````data_format```` in ````("YYYY-MM-DD",````
  ````"YYYY-MM-DD HH:mm:ss", None)````                                  → ````"datetime64[ns]"````
- ````"dateTime"```` + ````data_format```` in ````("YYYY-MM", "HH:mm:ss")````   → ````"object"````
  (no pandas-native equivalent for partial date / time-only strings)
- all others                                                         → ````"object"````

validation_requirement_hint() → str

Attributes:

name: str

title: str

unit: Units = <ast.Call object at 0x000001735721CF70>

widget_type: Literal[(input, textarea, number, dateTime, select, multiSelect, radio, checkbox, member, multiMember, serialNumber, image, address, attach, video, color, texture)] = <ast.Call object at 0x000001735721E230>

data_format: str | None = <ast.Call object at 0x000001735721F3A0>

field_type: Literal[(reserved, regular)] | None = <ast.Call object at 0x000001735721C280>

description: str | None = <ast.Call object at 0x0000017357238C70>

required: bool = <ast.Call object at 0x000001735723A5C0>

not_allow_duplicate_values: bool = <ast.Call object at 0x0000017357238D90>

regex: str | None = <ast.Call object at 0x0000017357238E20>

class dataclass.gdimData.GdimTableMetaData

The metadata of a table.

Inherits from:: BaseModel

Methods:

__init__()

get_field_metadata(key: str) → GdimFieldMetadata | None

Get field metadata by either name or title.

Parameters

key : The name or title of the field

Returns

Any: The field metadata if found, None otherwise

to_empty_tabledata(table_type: Literal[reserved, regular] | None = None) → TableData

Returns

Any

TableData
    Zero-row ````TableData```` with columns and dtypes derived from
    :meth:``GdimFieldMetadata.to_pandas_dtype``.

Attributes:

name: str

title: str

description: str | None = <ast.Call object at 0x0000017357223400>

table_type: Literal[(reserved, regular)] | None = <ast.Call object at 0x0000017357222830>

fields_metadata: dict[(str, GdimFieldMetadata)] = <ast.Call object at 0x00000173572221A0>

title_to_name: dict[(str, str)] = <ast.Call object at 0x0000017357220310>

primary_key: str | None = <ast.Call object at 0x0000017357222CE0>

sub_tables: list[str] = <ast.Call object at 0x0000017357222350>

class dataclass.gdimData.TemplateAppInfo

The application information of a template.

Inherits from:: BaseModel

Attributes:

applicationId: str = <ast.Call object at 0x0000017357E6D4B0>

applicationName: str = <ast.Call object at 0x0000017357E6D330>

applicationTitle: str = <ast.Call object at 0x0000017357E6D1B0>

applicationType: Literal[(builtInJava, builtInComposite, builtInPipe, builtInUserPipe, userPipe)] = <ast.Call object at 0x0000017357E6CEB0>

subApp: list[_PipelineAppInfo] | None = <ast.Call object at 0x0000017357E6CC70>

class dataclass.gdimData.StandardLayerUpdate

Inherits from:: BaseModel

Attributes:

update_method: Literal[(autoGeneration, manual)] | None = <ast.Call object at 0x0000017357E6C940>

define_layer_fields: list[str] | None = <ast.Call object at 0x0000017357E6C6D0>

class dataclass.gdimData.GdimTemplate

Container for table metadata with efficient name/title lookup and tree structure.

Inherits from:: BaseModel

Methods:

__init__()

get_table_metadata(key: str) → GdimTableMetaData | None

Get table metadata by either name or title.

Parameters

key : The name or title of the table

Returns

Any: The table metadata if found, None otherwise

get_app_info(key: str) → TemplateAppInfo | None: Get the application information by either name or title.

get_children(table_name: str) → list[str]

Get the list of child table names for a given table.

Parameters

table_name : The name of the parent table (can be name or title)

Returns

Any: List of child table names. Empty list if table has no children or doesn’t exist.

get_parent(table_name: str) → str | None

Get the parent table name for a given table.

Parameters

table_name : The name of the child table (can be name or title)

Returns

Any: Parent table name if exists, None otherwise.

is_root_table(table_name: str) → bool

Check if a table is a root table (has no parent).

Parameters

table_name : The name of the table (can be name or title)

Returns

Any: True if the table is a root table, False otherwise.

is_parent_table(table_name: str) → bool

Check if a table has children.

Parameters

table_name : The name of the table (can be name or title)

Returns

Any: True if the table has children, False otherwise.

is_child_table(table_name: str) → bool

Check if a table is a child of another table.

Parameters

table_name : The name of the table (can be name or title)

Returns

Any: True if the table is a child table, False otherwise.

Attributes:

tables: dict[(str, GdimTableMetaData)] = <ast.Call object at 0x0000017357E6C3A0>

title_to_name: dict[(str, str)] = <ast.Call object at 0x0000017357E6C160>

standard_layer_update: StandardLayerUpdate | None = <ast.Call object at 0x0000017357E13F10>

app_info: dict[(str, TemplateAppInfo)] | None = <ast.Call object at 0x0000017357E13C40>

app_title_to_name: dict[(str, str)] = <ast.Call object at 0x0000017357E139D0>

parent_to_children: dict[(str, list[str])] = <ast.Call object at 0x0000017357E13700>

child_to_parent: dict[(str, str)] = <ast.Call object at 0x0000017357E13430>

root_tables: list[str] = <ast.Call object at 0x0000017357E131C0>

class dataclass.gdimData.GdimTableCell

A cell in a table.

Inherits from:: BaseModel

Attributes:

value: str | int | float | bool | None

colspan: int | None = <ast.Call object at 0x0000017357CC1510>

rowspan: int | None = <ast.Call object at 0x0000017357CC16F0>

cellType: Literal[(th, td)] = <ast.Call object at 0x0000017357CC1930>

class dataclass.gdimData.GdimJsonTable

The data of a table to be rendered on Gdim.

Inherits from:: BaseModel

Methods:

print_table(): Print the table in a formatted way to the terminal.

Attributes:

table: list[_GdimTableRow] = <ast.Call object at 0x0000017357CC1EA0>

class dataclass.gdimData.SimpleJsonTable

A simple table data to be rendered on Gdim.

Inherits from:: BaseModel

Methods:

print_table(): Print the table in a formatted way to the terminal.

Attributes:

name: str = <ast.Call object at 0x0000017357CD88E0>

data: list[dict[(str, Any)]] | None = <ast.Call object at 0x0000017357CD8BE0>

columns: list[str] | None = <ast.Call object at 0x0000017357CD8E20>

highlight_rows: list[int] | None = <ast.Call object at 0x0000017357CD9060>

class dataclass.gdimData.GdimMinIOFile

The minIO file object.

Inherits from:: BaseModel

Methods:

convert_empty_string_to_none(cls, v): Convert empty strings to None for optional string fields.

get_download_url() → str: Get the download url of the file.

get_file_url() → str | None: Get the file url of the file.

Attributes:

success: bool = <ast.Call object at 0x0000017357CDBCA0>

fileId: str = <ast.Call object at 0x0000017357CDBE20>

fileUrl: str | None = <ast.Call object at 0x0000017357C54040>

originalFilename: str = <ast.Call object at 0x0000017357C541C0>

filename: str = <ast.Call object at 0x0000017357C54340>

size: int = <ast.Call object at 0x0000017357C544C0>

contentType: str = <ast.Call object at 0x0000017357C54640>

objectId: str | None = <ast.Call object at 0x0000017357C54820>

objectType: str | None = <ast.Call object at 0x0000017357C54A00>

message: str | None = <ast.Call object at 0x0000017357C54BE0>

thFileUrl: str | None = <ast.Call object at 0x0000017357C54DC0>

thFilename: str | None = <ast.Call object at 0x0000017357C54FA0>

thSize: int | None = <ast.Call object at 0x0000017357C55180>

downloadUrl: str = <ast.Call object at 0x0000017357C55300>

md5: str | None = <ast.Call object at 0x0000017357C554E0>

host: str | None = <ast.Call object at 0x0000017357C556C0>

class dataclass.gdimData.ProjectAddress

The address of the project.

Inherits from:: BaseModel

Methods:

to_single_result_fields() → list[UnitResult]

Convert ProjectAddress to a list of UnitResult objects for inclusion in SingleResult.

Returns

Any

list[UnitResult]
    List of UnitResult objects representing the address fields:
    - projectAddressProvince: The province of the project
    - projectAddressCity: The city of the project
    - projectAddressDistrict: The district of the project
    - projectAddressDetail: The detailed address of the project

Attributes:

province: str | None = <ast.Call object at 0x0000017357C56BC0>

city: str | None = <ast.Call object at 0x0000017357C56DD0>

district: str | None = <ast.Call object at 0x0000017357C56FE0>

address: str | None = <ast.Call object at 0x0000017357C571F0>

class dataclass.gdimData.GdimProjectInfo

Inherits from:: BaseModel

Methods:

validate_custom_fields(cls, v: dict[str, Any]) → SerializableDict: Convert customFields to SerializableDict and clean non-serializable values.

to_single_result() → SingleResult

Convert GdimProjectInfo to a SingleResult object.

This method converts all fields of the GdimProjectInfo instance into UnitResult objects and returns them as a SingleResult. The projectAddress field is converted to separate keys using the ProjectAddress.to_single_result_fields() method.

Returns

Any

SingleResult
    A SingleResult containing all project information as UnitResult objects

to_result_model(model_name: str = 'GdimProjectInfoResult') → ResultModel

Convert this instance to a :class:~gdi.dataclass.results.ResultModel.

Field names, titles, units, descriptions, and values match :meth:to_single_result (including projectAddress keys and custom fields).

Returns

Any

ResultModel
    Structured result with per-field metadata preserved for pipelines and docs.

Attributes:

id: str | None = <ast.Call object at 0x0000017357C9C220>

dataTemplateId: str | None = <ast.Call object at 0x0000017357C9C430>

dataTemplateName: str | None = <ast.Call object at 0x0000017357C9C640>

projectName: str | None = <ast.Call object at 0x0000017357C9C850>

dataTemplateGroupId: str | None = <ast.Call object at 0x0000017357C9CA30>

dataTemplateGroupName: str | None = <ast.Call object at 0x0000017357C9CC40>

spaceId: str | None = <ast.Call object at 0x0000017357C9CE50>

spaceType: Literal[(company, user)] = <ast.Call object at 0x0000017357C9D0C0>

projectManager: str | None = <ast.Call object at 0x0000017357C9D2D0>

coordinateSystem: Literal[(WGS84_UTM_S, WGS84_UTM_N, CGCS2000_3, CGCS2000_6, Xian1980_3, Xian1980_6, Beijing1954_3, Beijing1954_6, WGS84, RELATIVE_CRS)] | None = <ast.Call object at 0x0000017357C9D720>

zoneMethod: Literal[(manualInput, autoInput)] | None = <ast.Call object at 0x0000017357C9D9F0>

zoneNumber: int | None = <ast.Call object at 0x0000017357C9DC00>

centralMeridian: float | None = <ast.Call object at 0x0000017357C9DE10>

refPointLongitude: float | None = <ast.Call object at 0x0000017357C9E020>

refPointLatitude: float | None = <ast.Call object at 0x0000017357C9E230>

refPointX: float | None = <ast.Call object at 0x0000017357C9E440>

refPointY: float | None = <ast.Call object at 0x0000017357C9E650>

elevationDatum: str | None = <ast.Call object at 0x0000017357C9E860>

yAxisDirection: Literal[(east, north)] | None = <ast.Call object at 0x0000017357C9EB30>

readOnly: bool = <ast.Call object at 0x0000017357C9ECE0>

projectAddress: ProjectAddress | None = <ast.Call object at 0x0000017357C9EEF0>

currentUserIsProjectManager: bool = <ast.Call object at 0x0000017357C9F0A0>

accessPermission: bool = <ast.Call object at 0x0000017357C9F250>

customFields: dict[(str, Any)] = <ast.Call object at 0x0000017357C9F4C0>

proj_info_structure: GdimTableMetaData | None = <ast.Call object at 0x0000017357C9F670>

Functions

dataclass.gdimData.normalize_layer_number(value: Any) → Any

Convert circled layer labels (e.g. ``③1``) to GDIM form (``3-1``).

Leaves already-normalized values such as ``3-1`` or ``2-4A`` unchanged.

dataclass.gdimData.coerce_for_gdim_write(df: pd.DataFrame, table_metadata: GdimTableMetaData) → tuple[pd.DataFrame, list[str]]

Coerce DataFrame values to match GDIM widget types before validation.

Only performs safe, predictable conversions:

numeric scalars -> string for string-backed widgets
datetime/Timestamp -> formatted string for dateTime widgets
numeric strings -> numbers for number widgets

Parameters

dfpd.DataFrame: Source data to coerce.
table_metadataGdimTableMetaData: GDIM table metadata describing target field widget types.

Returns

Any

tuple[pd.DataFrame, list[str]]
    A copy of ````df```` with coerced values and the list of converted column names.