dataclass.tables

Classes

class dataclass.tables.TableMetadata

Metadata used for TableData or TableCollection.

Inherits from:

BaseModel

Attributes:

model_config = <ast.Call object at 0x0000028E224D1840>

name: str | None = None

title: str | None = None

description: str | None = None

class dataclass.tables.FieldMetadata

Methods:

__init__(name: str, title: str | None = None, unit: Units | None = None, widget_type: Literal[input, textarea, number, dateTime, select, multiSelect, radio, checkbox, member, multiMember, serialNumber, image, address, attach, video, color, texture] | None = None, data_format: str | None = None, field_type: Literal[reserved, regular] | None = None, description: str | None = None)

class dataclass.tables.TableSeries

Inherits from:

pd.Series

Methods:

__init__()

rename()

Override rename to ensure TableSeries is returned with updated metadata

map(arg, na_action=None)

Map values of Series according to an input mapping or function.

This method preserves the TableSeries metadata when mapping values.

Returns

Any

TableSeries
    Series with mapped values, preserving metadata.

serialize() → dict

Serialize the TableSeries object to a dictionary.

This method converts the TableSeries object into a dictionary format that can be easily serialized to JSON or other formats. All metadata including field information, units, titles, and descriptions are preserved.

Returns

Any

dict
    A dictionary containing all TableSeries information:
    - 'data': Series data as a list (values)
    - 'index': Series index as a list
    - 'name': Series name
    - 'field_meta': Field metadata as a dictionary
    - 'dtype': Series data type for proper reconstruction
    - 'title_to_name': Mapping of this series' title to name (if applicable)

Examples

>>> series = TableSeries(...)
>>> serialized = series.serialize()
>>> # Can be saved to JSON
>>> import json
>>> json_str = json.dumps(serialized)

deserialize(cls, data_dict: dict) → TableSeries

Deserialize a TableSeries object from a dictionary.

This class method reconstructs a TableSeries object from a dictionary created by the serialize() method. All metadata and data types are properly restored.

Parameters

data_dictdict

Dictionary containing serialized TableSeries information, typically created by the serialize() method

Returns

Any

TableSeries
    Reconstructed TableSeries object with all metadata preserved

Examples

>>> # Load from serialized data
>>> series = TableSeries.deserialize(serialized_data)
>>>
>>> # Or from JSON
>>> import json
>>> data_dict = json.loads(json_str)
>>> series = TableSeries.deserialize(data_dict)

Properties:

field_meta

unit

description

class dataclass.tables.TableData

Inherits from:

pd.DataFrame

Methods:

__init__()

convert_to_field_names(fields: str | list[str] | tuple[str, Ellipsis] | None = None) → list[str]

Convert field titles, field names, or combination of both to field names.

convert_to_field_titles(fields: str | list[str] | tuple[str, Ellipsis] | None = None) → list[str]

Convert field titles, field names, or combination of both to field titles.

get_field_metadata(key: str) → FieldMetadata

Get field metadata by name or title

Parameters

keystr

The name or title of the field

Returns

Any

FieldMetadata
    The metadata of the field

update_fields_metadata(value: list[FieldMetadata] | list[dict[str, str]])

Update the fields metadata

update_field_metadata(field_name: str, title: str | None = None, unit: Units | None = None, description: str | None = None)

Update field metadata while preserving the name

get(key, default=None)

Get column(s) by name or title with a default return value.

Supports the same indexing as __getitem__:

• Single string: column name or field title

• List of strings: multiple column names/field titles

• Other pandas indexing types

Returns

Any

TableSeries, TableData, or default value
    Result of indexing or default if key not found

select_by_titles() → TableData

Select columns by their titles, returning a new TableData with those columns.

Parameters

*titlesstr

Field titles, field names, or combination of both to select

Returns

Any

TableData
    New TableData containing only the selected columns

rename_columns(mapper=None)

Rename columns while preserving field metadata.

Returns

Any

TableData or None
    Table with renamed columns if inplace=False, None if inplace=True

resolve_columns_map(mapper: dict[str, str] | None, target_lookup: dict[str, str]) → dict[str, str]

Build a ``{current_col_name → canonical_name}`` rename map for :meth:rename_columns.

This is a flexible helper that normalises both sides of a user-supplied
column mapping (or auto-detects it entirely) so callers never have to
deal with the name-vs-title ambiguity themselves.

````target_lookup```` contract

renamed to; the value is an alternative label (title, display name, …) that a user might supply instead of the canonical name.

Each source key is resolved to an actual column name in this table:

1. If the key is already a column name → use it directly.

2. Otherwise look it up in :attr:title_to_name (treat it as a column title).

3. If neither check succeeds, the entry is silently skipped.

Target value resolution (``mapper`` provided)

1. If the value is a key in target_lookup → already canonical, use it.

2. If the value matches an alias (a value in target_lookup) → use the corresponding canonical key.

3. Otherwise the value is used as-is.

Auto-detect mode (``mapper is None``)

1. If the canonical key is already a column name → skip.

2. If the alias is a column name → rename that column to the canonical key.

3. Otherwise look up the alias in :attr:title_to_name; if found and the resolved column is not itself another canonical key → rename it.

Only entries where source name ≠ target name are included.

Returns

Any

dict[str, str]
    Rename map ````{current_col_name → canonical_target_name}```` ready to
    be passed directly to :meth:``rename_columns``.

rename_columns_to_titles(inplace=True)

Rename all column names to match their titles.

This method renames the columns of the DataFrame to use their corresponding titles from field metadata, making the column names more human-readable. If a column doesn’t have a title different from its name, it will remain unchanged.

Returns

Any

TableData
    If inplace=True, returns self.
    If inplace=False, returns a new TableData with columns renamed to match their titles.

drop(labels=None, axis=0, index=None, columns=None)

Override drop to maintain metadata consistency

rename()

Override rename to update metadata

groupby(by=None, axis=0, level=None, as_index=True, sort=True, group_keys=True, observed=None, dropna=True)

Group DataFrame using a mapper or by a Series of columns, supporting field titles.

This method extends pandas DataFrame.groupby() to work with TableData objects, allowing the use of field titles as column identifiers.

Returns

Any

_TableDataGroupBy
    A grouped object that preserves metadata

value_counts(subset: str | list[str] | None = None, normalize: bool = False, sort: bool = True, ascending: bool = False, dropna: bool = True)

Returns

Any

TableSeries
    TableSeries containing the value counts with preserved metadata.
    The series name will be "count" or "proportion" (计数/比例) depending on normalize parameter.

export_doc_context(precision: int | dict[str, int | None] | None = None, datetime_format: str | dict[str, str | None] | None = None) → dict[str, Any]

Export the table data as a dictionary for document context.

Returns

Any

dict[str, Any]
    The context of the result.
    key "data" stores the table data.
    key "doc_keys_strcut" stores the structure of the keys for the result.

Examples

- "%Y-%m-%d": "2024-01-15"
    - "%Y年%m月%d日": "2024年01月15日"
    - "%Y/%m/%d %H:%M": "2024/01/15 14:30"

copy(deep=True)

Override copy to preserve metadata

merge(right, how = 'inner', on = None, left_on = None, right_on = None, left_index = False, right_index = False, sort = False, suffixes = <ast.Tuple object at 0x0000028E22066E90>, copy = True, indicator = False, validate = None, ignore_index = False)

Merge TableData with another DataFrame or TableData, preserving metadata.

This method performs a database-style join operation between DataFrames and ensures that metadata from both tables is properly handled in the result.

Parameters

rightDataFrame or TableData

Object to merge with how : str, default ‘inner’ Type of merge to be performed: ‘left’, ‘right’, ‘outer’, ‘inner’ on : label or list, optional Column(s) to join on. Must be found in both DataFrames. left_on : label or list, optional Column(s) from the left DataFrame to use as keys right_on : label or list, optional Column(s) from the right DataFrame to use as keys left_index : bool, default False Use the index from the left DataFrame as the join key right_index : bool, default False Use the index from the right DataFrame as the join key sort : bool, default False Sort the result DataFrame by the join keys suffixes : 2-tuple of str, default (‘_x’, ‘_y’) Suffix to apply to overlapping column names copy : bool, default True If False, avoid copying data when possible indicator : bool or str, default False Add a column to the output DataFrame indicating the source validate : str, optional Validation check on the merge operation: ‘one_to_one’, ‘one_to_many’, ‘many_to_one’, ‘many_to_many’ ignore_index : bool, default False If True, do not use the index values along the concatenation axis. The resulting axis will be labeled 0, 1, …, n - 1.

Returns

Any

TableData
    The merged TableData with preserved metadata

astype(dtype, copy=True, errors='raise')

Override astype to preserve metadata

sort_values(by: str | list[str], axis: int = 0, ascending: bool | list[bool] = True, inplace: bool = False, kind: Literal[quicksort, mergesort, heapsort, stable] = 'quicksort', na_position: Literal[first, last] = 'last', ignore_index: bool = False, key: Callable | None = None)

Sort DataFrame by values, preserving TableData metadata and allowing field titles as sort keys.

This method extends pandas DataFrame.sort_values() to work with TableData objects, preserving all metadata and allowing the use of field titles as column identifiers.

Parameters

bystr or list of str

Name(s) or title(s) of field(s) to sort by. Can be either column names or field titles. axis : {0 or ‘index’, 1 or ‘columns’}, default 0 Axis to be sorted. ascending : bool or list of bool, default True Sort ascending vs. descending. Specify list for multiple sort orders. inplace : bool, default False If True, perform operation in-place. kind : {‘quicksort’, ‘mergesort’, ‘heapsort’, ‘stable’}, default ‘quicksort’ Choice of sorting algorithm. na_position : {‘first’, ‘last’}, default ‘last’ Puts NaNs at the beginning if ‘first’; ‘last’ puts NaNs at the end. ignore_index : bool, default False If True, the resulting axis will be labeled 0, 1, …, n - 1. key : callable, optional Apply the key function to the values before sorting.

Returns

Any

TableData or None
    Sorted TableData object if inplace=False, None if inplace=True.

Examples

Sort by column name:
>>> table.sort_values('column_name')

Sort by field title:
>>> table.sort_values('Column Title')

Sort by multiple fields (mix of names and titles):
>>> table.sort_values(['column_name', 'Another Title'])

reset_index(level=None, drop=False, inplace=False, col_level=0, col_fill='', allow_duplicates=False, names=None)

Reset the index, preserving TableData metadata and creating metadata for new columns.

This method extends pandas DataFrame.reset_index() to work with TableData objects, preserving all metadata and creating appropriate metadata for any new columns created from the index.

Returns

Any

TableData or None
    DataFrame with the new index or None if inplace=True.

fillna(value=None, method=None, axis=None, inplace=False, limit=None, downcast=None) → TableData | None

Fill NA/NaN values using the specified method, preserving TableData metadata.

This method extends pandas DataFrame.fillna() to work with TableData objects, preserving all metadata and returning a TableData object instead of a regular DataFrame. Behavior is identical to pandas DataFrame.fillna().

Returns

Any

TableData or None
    TableData with NA entries filled if inplace=False, None if inplace=True.

Examples

Fill with a single value:
>>> table.fillna(0)

Fill with different values per column:
>>> table.fillna({'column1': 0, 'column2': 'missing'})

Forward fill:
>>> table.fillna(method='ffill')

coerce_to_gdim_metadata(table_metadata: GdimTableMetaData, inplace: bool = False) → TableData | None

Coerce column values to match GDIM widget types before validation or write.

See :func:~gdi.dataclass.gdimData.coerce_for_gdim_write for conversion rules.

Parameters

table_metadataGdimTableMetaData

GDIM table metadata describing target field widget types. inplace : bool, default False If True, modify this TableData in place and return None. If False, return a new TableData with coerced values.

Returns

Any

TableData or None
    Coerced TableData if ````inplace=False````, otherwise None.

prepare_for_json(inplace=False) → TableData | None

Prepare TableData for JSON serialization by replacing problematic values.

Replaces np.nan, np.inf, and -np.inf with None (which serializes to null in JSON). Converts datetime/Timestamp columns to ``"YYYY-MM-DD HH:mm:ss"`` strings so that the values remain compatible with GDIM’s expected date format on write-back. This method is specifically designed for JSON serialization purposes.

Returns

Any

TableData or None
    TableData with JSON-safe values if inplace=False, None if inplace=True.

Examples

Prepare for JSON serialization:
>>> json_ready_table = table.prepare_for_json()
>>> json_dict = json_ready_table.to_dict(orient="records")

In-place preparation:
>>> table.prepare_for_json(inplace=True)
>>> json_dict = table.to_dict(orient="records")

describe(percentiles=None, include=None, exclude=None) → TableData

Generate descriptive statistics while preserving TableData metadata.

This method extends pandas DataFrame.describe() to work with TableData objects, preserving field metadata and returning a TableData object instead of a regular DataFrame.

Returns

Any

TableData
    Summary statistics of the DataFrame with preserved metadata.

Examples

>>> table = TableData(...)
>>> described = table.describe()  # Returns TableData, not DataFrame
>>> print(type(described))  # <class 'TableData'>

drop_duplicates(subset=None, keep='first', inplace=False, ignore_index=False)

Remove duplicate rows, supporting field titles as column identifiers.

This method extends pandas DataFrame.drop_duplicates() to work with TableData objects, preserving all metadata and allowing the use of field titles as column identifiers.

Returns

Any

TableData or None
    TableData object with duplicates removed if inplace=False, None if inplace=True.

Examples

Drop duplicates using column name:
>>> table.drop_duplicates('column_name')

Drop duplicates using field title:
>>> table.drop_duplicates('Column Title')

Drop duplicates using multiple fields (mix of names and titles):
>>> table.drop_duplicates(['column_name', 'Another Title'])

duplicated(subset=None, keep='first')

Returns

Any

pd.Series
    Boolean series indicating whether each row is a duplicate.

Examples

Check duplicates using column name:
>>> duplicates = table.duplicated('column_name')

Check duplicates using field title:
>>> duplicates = table.duplicated('Column Title')

Check duplicates using multiple fields (mix of names and titles):
>>> duplicates = table.duplicated(['column_name', 'Another Title'])

serialize() → dict

Serialize the TableData object to a dictionary.

This method converts the TableData object into a dictionary format that can be easily serialized to JSON or other formats. All metadata including field information, units, titles, and descriptions are preserved.

Returns

Any

dict
    A dictionary containing all TableData information:
    - 'data': DataFrame data as records
    - 'name': Table name
    - 'title': Table title
    - 'description': Table description
    - 'fields_meta': Field metadata as dictionaries
    - 'dtypes': Column data types for proper reconstruction
    - 'title_to_name': Title to name mapping

Examples

>>> table = TableData(...)
>>> serialized = table.serialize()
>>> # Can be saved to JSON
>>> import json
>>> json_str = json.dumps(serialized)

deserialize(cls, data_dict: dict) → TableData

Deserialize a TableData object from a dictionary.

This class method reconstructs a TableData object from a dictionary created by the serialize() method. All metadata and data types are properly restored.

Parameters

data_dictdict

Dictionary containing serialized TableData information, typically created by the serialize() method

Returns

Any

TableData
    Reconstructed TableData object with all metadata preserved

Examples

>>> # Load from serialized data
>>> table = TableData.deserialize(serialized_data)
>>>
>>> # Or from JSON
>>> import json
>>> data_dict = json.loads(json_str)
>>> table = TableData.deserialize(data_dict)

append_table(other, ignore_index=True)

Append another TableData to this one, modifying this table in place.

This is an instance method that concatenates another TableData object to the current one, updating the current table in place.

Parameters

otherTableData

The TableData object to append to this one ignore_index : bool, default True If True, do not use the index values along the concatenation axis **kwargs Additional keyword arguments passed to pd.concat()

Returns

Any

None
    This method modifies the current TableData in place

Examples

>>> table1 = TableData(...)
>>> table2 = TableData(...)
>>> table1.append_table(table2)  # table1 now contains both datasets

concat(tables, ignore_index=True, name=None, title=None, description=None)

Concatenate TableData objects while preserving metadata.

This is a static method that provides a TableData-aware version of pd.concat(). It concatenates multiple TableData objects and merges their field metadata.

Parameters

tableslist of TableData or iterable of TableData

The TableData objects to concatenate ignore_index : bool, default True If True, do not use the index values along the concatenation axis name : str, optional Name for the resulting TableData. If None, defaults to “concatenated_table” title : str, optional Title for the resulting TableData. If None, defaults to “Concatenated Table” description : str, optional Description for the resulting TableData. If None, provides a default description **kwargs Additional keyword arguments passed to pd.concat()

Returns

Any

TableData
    A new TableData object containing the concatenated data with merged metadata

Examples

>>> table1 = TableData(...)
>>> table2 = TableData(...)
>>> result = TableData.concat([table1, table2])

>>> # From a TableCollection
>>> tables = TableCollection()
>>> result = TableData.concat(tables)

Properties:

title_to_name

Get the mapping of column titles to column names. Key is title, value is name.

name_to_title

Get the mapping of column names to column titles. Key is name, value is title.

field_titles

Get the list of field titles

field_names

Get the list of field names

fields_meta

Read-only access to fields metadata

iloc

Override iloc to maintain metadata

loc

Override loc to maintain metadata

class dataclass.tables.TableCollection

A class to manage multiple TableData objects

Methods:

__init__(name: str | None = None, title: str | None = None, description: str | None = None)

add_table(table: TableData, main_table: bool = False, primary_key: str | None = None, sub_table: bool = False, parent_table: str | None = None) → None

Add a TableData object to the collection.

Parameters

tableTableData

The TableData object to add main_table: bool, default False Whether this table should be set as the main table primary_key: str | dict[str, str] | None, default None The primary key for grouping operations sub_table: bool, default False Whether this table should be added to the sub_tables parent_table: str | None, default None When sub_table=True and multiple main tables exist, specify which main table this sub_table belongs to. If None and only one main table exists, uses that one.

Notes

The table can be retrieved either by its name or title.

get_table(key: str) → TableData | None

Retrieve a table by name or title.

Parameters

keystr

The name or title of the table to retrieve

Returns

Any

TableData or None
    TableData object if found, None if not found

remove_table(key: str) → None

Remove a table from the collection

Parameters

key : Name or title of the table to remove

Raises

KeyError

If table name/title doesn’t exist

derive_relationship_subset(kept_table_names: set[str]) → tuple[str | List[str] | None, List[str] | Dict[str, List[str]], str | Dict[str, str] | None]

Restrict ``main_table``, ``sub_tables``, and ``primary_key`` to tables

whose names are in ``kept_table_names``.

Returns

Any

``main_table`` is None, ``sub_tables`` is ``[]``, ``primary_key`` is None.

copy() → TableCollection

Create a deep copy of the TableCollection.

Returns

Any

TableCollection
    A new TableCollection with copies of all tables

rename_columns_to_titles()

Rename all column names to match their titles.

This method renames the columns of the DataFrame to use their corresponding titles from field metadata, making the column names more human-readable.

keys() → List[str]

Get list of all table names in the collection

values() → List[TableData]

Get list of all table objects in the collection

serialize() → dict

Serialize the TableCollection object to a dictionary.

This method converts the TableCollection object into a dictionary format that can be easily serialized to JSON or other formats. All metadata and contained TableData objects are preserved.

Returns

Any

dict
    A dictionary containing all TableCollection information:
    - 'name': Collection name
    - 'title': Collection title
    - 'description': Collection description
    - 'main_table': Name of the main table (or None)
    - 'sub_tables': List of sub-table names
    - 'primary_key': Primary key used for grouping (or None)
    - 'tables': Dictionary of serialized TableData objects keyed by table name

Examples

>>> collection = TableCollection(...)
>>> serialized = collection.serialize()
>>> # Can be saved to JSON
>>> import json
>>> json_str = json.dumps(serialized)

deserialize(cls, data_dict: dict) → TableCollection

Deserialize a TableCollection object from a dictionary.

This class method reconstructs a TableCollection object from a dictionary created by the serialize() method. All metadata and TableData objects are properly restored.

Parameters

data_dictdict

Dictionary containing serialized TableCollection information, typically created by the serialize() method

Returns

Any

TableCollection
    Reconstructed TableCollection object with all tables and metadata preserved

Examples

>>> # Load from serialized data
>>> collection = TableCollection.deserialize(serialized_data)
>>>
>>> # Or from JSON
>>> import json
>>> data_dict = json.loads(json_str)
>>> collection = TableCollection.deserialize(data_dict)

export_doc_context(precision: int | dict[str, int | None] | None = None, datetime_format: str | dict[str, str | None] | None = None, merge_strategy: Literal[auto, none, explicit] = 'auto', explicit_merges: list[dict[str, str | list[str]]] | None = None) → dict

Export the table collection as a dictionary for document context.

Returns

Any

dict
    Dictionary with keys:
    - "data": dict or list of dicts - The table data
             For "none" and "explicit": dict with multiple table results
             For "auto": dict with merged results for all predefined relationships
    - "doc_keys_struct": dict - Metadata describing the structure

Examples

{
            "main": "钻孔表",
            "subs": ["地层表", "标贯表"],
            "group_by": "钻孔编号",
            "sub_table_doc_key_name": "layers",
            "sub_table_doc_key_title": "地层数据"
        },
        {
            "main": "试验汇总",
            "subs": "试验详情"
        }
    ]

Notes

merge_strategy: Literal["auto", "none", "explicit"], default: "auto"
    Strategy for merging tables in the collection:
    - "auto": Use ALL predefined relationships (self.main_table, self.sub_tables, self.primary_key)
              - If relationships exist: merges related tables, treats others as independent
              - If no relationships: treats ALL tables as independent (same as "none")

to_dict(serializable: bool = False, orient: Literal[records, list, dict, index] = 'records') → dict

Convert the TableCollection object to a dictionary.

Parameters

serializablebool, default: False

If True, return the serialized dictionary which means all the np.nan, np.inf, -np.inf will be converted to None, and datetime objects will be converted to ISO format strings.

convert_to_verticalBores_data()

生成VerticalBores对象需要的bores_table、layers_table、materials_name

convert_to_drawApps_params(section_lines: Dict[str, list[str]] = None)

功能：导出gpro中生成剖面接口所需的参数

参数：
log_file: str型，错误日志的文件路径。
section_lines:Dict型， 剖面线字典
             示例： {'seciton1':['TJ1','TJ2','TJ3'],'section2':['ZK2','ZK3']}

get_table_by_index(index: int) → TableData

Retrieve a table by its index position.

Parameters

indexint

The index position of the table to retrieve (supports negative indexing)

Returns

Any

TableData
    The table at the specified index

get_main_tables() → list[str]

Get list of all main table names.

Returns

Any

list[str]
    List of main table names. Empty list if no main tables defined.

get_sub_tables(main_table_name: str | None = None) → list[str]

Get list of sub tables for a given main table.

Returns

Any

list[str]
    List of sub table names for the specified main table.

get_primary_key(main_table_name: str | None = None) → str | None

Get the primary key for a given main table.

Returns

Any

str | None
    The primary_key for the specified main table, or None if not set.

add_table_pair(main_table_name: str, sub_table_names: list[str], primary_key: str | None = None) → None

Add a main table and its sub tables relationship.

This is a convenience method to establish relationships between existing tables in the collection. The tables must already be added to the collection.

Parameters

main_table_namestr

Name of the main table

sub_table_nameslist[str]

List of sub table names associated with this main table primary_key: str | None, default None The primary key for grouping operations

Properties:

table_names

Get list of all table names in the collection

table_titles

Get list of all table titles in the collection