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 0x0000028E221DF6A0>

data_format_configs = <ast.Dict object at 0x0000028E221DE8C0>

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"````

Attributes:

name: str

title: str

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

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

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

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

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

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

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

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

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 0x0000028E2172EE00>

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

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

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

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

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

class dataclass.gdimData.TemplateAppInfo

The application information of a template.

Inherits from:: BaseModel

Attributes:

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

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

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

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

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

class dataclass.gdimData.StandardLayerUpdate

Inherits from:: BaseModel

Attributes:

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

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

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 0x0000028E22167790>

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

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

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

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

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

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

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

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 0x0000028E22125F30>

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

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

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 0x0000028E221255A0>

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 0x0000028E224714B0>

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

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

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

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 0x0000028E2247C8B0>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 0x0000028E2247FC40>

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

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

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

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 0x0000028E2241D2A0>

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

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

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

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

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

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

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

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

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 0x0000028E2241E7A0>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.