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

data_format_configs = <ast.Dict object at 0x0000021FE181A4A0>

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 == "YYYY-MM"````                     → ````"object"````
  (no pandas-native equivalent for a year-month string)
- all others                                                         → ````"object"````

validation_requirement_hint() → str

Attributes:

name: str

title: str

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class dataclass.gdimData.TemplateAppInfo

The application information of a template.

Inherits from:

BaseModel

Attributes:

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

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

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

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

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

class dataclass.gdimData.StandardLayerUpdate

Inherits from:

BaseModel

Attributes:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class dataclass.gdimData.GdimTableFile

A file stored in a GDIM table cell (image / attach / video widget).

Inherits from:

BaseModel

Methods:

convert_empty_string_to_none(cls, v)

Convert empty strings to None for optional string fields.

get_file_url() → str

Get the file url of the file.

Attributes:

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

fileUrl: str = <ast.Call object at 0x0000021FE2DE9060>

fileName: str = <ast.Call object at 0x0000021FE2DE91E0>

fileSize: int = <ast.Call object at 0x0000021FE2DE9360>

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

thumbnailUrl: str | None = <ast.Call object at 0x0000021FE2DE96C0>

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

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
    - projectAddressCenter: The map center, as longitude,latitude

Attributes:

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

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

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

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

center: str | None = <ast.Call object at 0x0000021FE2DEAD10>

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

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

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

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

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

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

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

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

spaceName: str | None = <ast.Call object at 0x0000021FE2DC50F0>

spaceUserMobile: str | None = <ast.Call object at 0x0000021FE2DC5300>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

archived: bool | None = <ast.Call object at 0x0000021FE2DC76A0>

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

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

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.