modules.writers

Classes

class modules.writers.GdimSimpleTablesWriter

Write a TableCollection (multiple tables) to a simgle json formate for gdim rendering.

Inherits from:: PipeModule

Methods:

__init__(mname: str | None = None, auto_run: bool = True, tables: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, highlight_rows: PortTypeHint.TablesRowMask | None = None, name_type: Literal[name, title] = 'name', columns: list[str] | None = None, precision: dict[str, int | None] | None = None, table_name_type: Literal[name, title] = 'title', column_name_type: Literal[name, title] = 'title', highlight_rows_required: bool = False) → None

Initialize the GdimSimpleTablesWriter object.

Parameters

tablesTableCollection | TableData | None, default: None: The table collection to be converted. If it’s TableCollection, serveral table will be converted and keys are either table name or table title. If it’s TableData, only one table will be converted.
highlight_rowsPortTypeHint.TablesRowMask | None, default: None: A mask to mark the rows to be highlighted. Key is the name of the table. Value is mask which is a list of boolean values. name_type: Literal[“name”, “title”], default: “name” The type of the names used in column names selected, the key of precision and the name of the main table.
columnslist[str] | None, default: None: The columns to be converted. All tables in the TableCollection will use the same columns. If a column is not found in a table, it will be ignored. If None, all columns will be converted. If name_type is “name”, the columns should be the names of the columns. If name_type is “title”, the columns should be the titles of the columns. The table will be rendered in the same sequence of the columns. precision: dict[str, int] | None, default: None The precision of the table. Key is the name of the column. If name_type is “name”, the key is the name of the column. If name_type is “title”, the key is the title of the column. table_name_type: Literal[“name”, “title”], default: “title” The type of the names used for the table names in the output. column_name_type: Literal[“name”, “title”], default: “title” The type of the names used for the column names in the output.
highlight_rows_requiredbool, default: False: Whether the highlight rows are required. If it’s True, the InputHighlightRows cannot be None, or None will be returned after execution.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.SimpleJsonTables | None

Properties:

InputTables

InputHighlightRows

OutputRenderTables

class modules.writers.GdimRenderTableWriter

Convert a TableData, TableCollection or SingleResult to a json format so that it can be rendered on Gdim.

Only one table can be generated.

Inherits from:: PipeModule

Methods:

Initialize the GdimRenderTableWriter object.

Parameters

dataTableData | TableCollection | SingleResult | None, default: None: The data to be converted. If it’s TableCollection, the tables will be merged into a single table by columns. name_type: Literal[“name”, “title”], default: “name” The type of the names used in column names selected, the key of precision and the name of the main table.
columnslist[str] | None, default: None: The columns to be converted. If None, all columns will be converted. If name_type is “name”, the columns should be the names of the columns. If name_type is “title”, the columns should be the titles of the columns. precision: dict[str, int] | None, default: None The precision of the table. Key is the name of the column. If name_type is “name”, the key is the name of the column. If name_type is “title”, the key is the title of the column.
group_bystr | None, default: None: The column name to be grouped by. It’s used when the table_data is a TableCollection. If None, the “group_by” will be the first column with the same name in all tables. If the name_type is “title”, the group_by should be the title of the column. If the name_type is “name”, the group_by should be the name of the column.
main_tablestr | None, default: None: The name of the main table. It’s used when the table_data is a TableCollection. If None, the table with the least number of rows will be used as the main table. If the name_type is “title”, the main_table should be the title of the main table. If the name_type is “name”, the main_table should be the name of the main table.
sub_tableslist[str] | None, default: None: The names of the sub tables. It’s used when the table_data is a TableCollection. If None, all tables except the main table will be used as sub tables.

set_cal_params(reset: bool = True) → dict[str, RangeModel]

execute() → PortTypeHint.GdimJsonTable | None

Properties:

InputData

OutputRenderTable

class modules.writers.DocDataWriter

Write all kinds of result to a data format that can be used to generate a .docx document.

Inherits from:: PipeModule

Methods:

Initialize the DocDataWriter object.

Parameters

The data to be written to a format that can be used for .docx document. For multiple data items, use TableCollection (for tables) or compose multiple DocDataWriter modules with MergeDocData. precision: int | dict[str, int | None] | None, default: None The precision of numeric values for formatting. Controls the number of decimal places for numeric data when exported to document format.

int: Apply the same precision to ALL numeric columns/values (convenient)

Examples

- latex_to_unicode_keys="model_expression"  # Single root key
    - latex_to_unicode_keys=["model_expression", "formula"]  # Multiple root keys
    - latex_to_unicode_keys={"table1": "column1"}  # Single table column
    - latex_to_unicode_keys={"table1": ["col1", "col2"]}  # Multiple columns in table
    - latex_to_unicode_keys={"__root__": ["key1"], "table1": ["col1"]}  # Mixed

Notes

Keys can be either field names or field titles.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.DocData | None

get_doc_keys(file_path: str | None = None) → dict | None: Export the doc keys to a json file.

get_doc_data(file_path: str | None = None) → dict | None: Export the doc data to a json file.

Attributes:

InputData: PortReference[PortTypeHint.SingleResult | PortTypeHint.ResultModel | PortTypeHint.TableData | PortTypeHint.TableCollection | PortTypeHint.FilePath | PortTypeHint.FilesPath]

OutputDocData: PortReference[PortTypeHint.DocData]

class modules.writers.MergeDocData

Merge the data from multiple DocData objects into a single DocData object.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeDocData', auto_run: bool = True, all_ports_required: bool = True) → None

Initialize the MergeDocData object.

Parameters

all_ports_requiredbool, default: True: If True, the execution will be blocked until all the dynamic ports are connected with valid data.

execute() → PortTypeHint.DocData | None

get_doc_keys(file_path: str | None = None) → dict | None: Export the doc keys to a json file.

get_doc_data(file_path: str | None = None) → dict | None: Export the doc data to a json file.

Attributes:

OutputDocData: PortReference[PortTypeHint.DocData]

class modules.writers.DocPrinter

Write the doc data to a .docx document.

Inherits from:: PipeModule

Methods:

Initialize the DocPrinter object.

Parameters

doc_dataPortTypeHint.DocData | None

The doc data to be printed.

The template file or files used for printing. If None, the module will not be executed. If str or Path, the template file path should be specified. If list[str | Path], the template files should be specified. If dict, it will be converted to a GdimMinIOFile object to get the template from minIO server. If list[dict], it will be converted to a list of GdimMinIOFile objects to get the template from minIO server.

output_dirstr | Path | None, default: None

The directory to save the generated document.

‘workspace’ of pipeline has priority over the ‘output_dir’.
If both ‘output_dir’ and ‘workspace’ are None, the current working directory will be used.

output_namestr | list[str] | None

The name of the generated document. If list[str], the DocPrinter will try to print all the with all the doc templates with corresponding output names. If None, the name of the ‘template’ with a suffix ‘_printed’ will be used. image_size_type: Literal[“width”, “height”] | dict[str, Literal[“width”, “height”]], default: “width” The type of the image size. If “width”, the image size will be set to the width of the image. If “height”, the image size will be set to the height of the image. If dict, different key can use different type of image size. If the key is not found, width will be used as default. image_size: float | int | dict[str, float | int] | dict[str, list[float | int]] | None, default: None The size of the image in mm. If float | int, all images will use this size. If dict[str, float | int], key is the key in the doc_data and the value is the size of the image. If dict[str, list[float | int]], key is the key in the doc_data and the value is the size for each image in the list. If None, the image size will be as same as its original size.

save_to_gdimbool, default: False

If True, the generated document will also be saved to the gdim file server. Requires a valid token and either proj_id or proj_name.

tokenstr | None

The token of the user. Must be provided when save_to_gdim is True.

proj_idint | str | None

The id of the gdim project. Must be provided when save_to_gdim is True, unless proj_name is set. When set, proj_name is ignored.

proj_namestr | None, default: None

Exact project name. Used when proj_id is None and save_to_gdim is True, and it overrides the pipeline project. Archived projects are not searched. personal_space=False and space_name=None use the logged-in space.

personal_spacebool, default: False

Whether proj_name is looked up in a personal space.

space_namestr | None, default: None

Exact space name for proj_name. None uses the current space.

hoststr | None

The host of the gdim platform. Ports

InputDocDataPortReference[PortTypeHint.DocData]

The doc data to be printed.

InputTokenPortReference[PortTypeHint.Token]

The token of the user.

OutputFilePortReference[PortTypeHint.FilePath | PortTypeHint.FilesPath | PortTypeHint.GdimFile | PortTypeHint.GdimFiles]

The files of the generated document.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.FilePath | PortTypeHint.FilesPath | PortTypeHint.GdimFile | PortTypeHint.GdimFiles | None

Attributes:

InputDocData: PortReference[PortTypeHint.DocData]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.FilesPath | PortTypeHint.GdimFile | PortTypeHint.GdimFiles]

class modules.writers.ExcelPrinter

Write the doc data to a .xlsx document.

Inherits from:: PipeModule

Methods:

Initialize the ExcelPrinter object.

Parameters

doc_dataPortTypeHint.DocData | None

The doc data to be printed.

The template file or files used for printing. If None, the module will not be executed. If str or Path, the template file path should be specified. If list[str | Path], the template files should be specified. If dict, it will be converted to a GdimMinIOFile object to get the template from minIO server. If list[dict], it will be converted to a list of GdimMinIOFile objects to get the template from minIO server.

output_dirstr | None

The directory to save the generated document.

‘workspace’ of pipeline has priority over the ‘output_dir’.
If both ‘output_dir’ and ‘workspace’ are None, the current working directory will be used.

output_namestr | list[str] | None

The name of the generated document. If list[str], the ExcelPrinter will try to print all the with all the Excel templates with corresponding output names. If None, the name of the ‘template’ with a suffix ‘_printed’ will be used.

include_table_titlesbool, default: False

If True, table headers will be automatically generated from doc_keys_struct. If False, headers are assumed to be already in the template.

apply_table_bordersbool, default: False

If True, apply outer borders to all table regions.

border_stylestr, default: “thin”

Border style for tables - “thin”, “medium”, “thick”, “double”, “dashed”, “dashDot”, “dashDotDot”, “hair”, “mediumDashed”, “mediumDashDot”, “mediumDashDotDot”, “slantDashDot” etc. image_size_type: str | dict[str, str], default: “width” The type of the image size. If “width”, the image size will be set to the width of the image (height calculated to maintain aspect ratio). If “height”, the image size will be set to the height of the image (width calculated to maintain aspect ratio). If dict, different key can use different type of image size. If the key is not found, “width” will be used as default. image_size: dict[str, float] | dict[str, list[float]] | None, default: None The size of the image in mm. If dict[str, float], key is the key in the doc_data and the value is the size of the image in mm. If dict[str, list[float]], key is the key in the doc_data and the value is the size for each image in the list in mm. If None, the image size will be as same as its original size.

Notes

process_sheets: str |  list[str]  | Literal["active", "all"], default: "active"
    Specifies which sheets to process in the Excel template:
    - "active": Process only the active sheet (default, backward compatible)
    - "all": Process all sheets in the workbook
    - str: Process a specific sheet by name
    - list[str]: Process specific sheets by their names

save_to_gdim: bool, default: False
    If True, the generated document will also be saved to the gdim file server.
    Requires a valid token and either ``proj_id`` or ``proj_name``.

token: str | None
    The token of the user.
    Must be provided when ``save_to_gdim`` is True.

proj_id: int |  str  | None
    The id of the gdim project.
    Must be provided when ``save_to_gdim`` is True, unless ``proj_name`` is set.
    When set, ``proj_name`` is ignored.

proj_name: str | None, default: None
    Exact project name. Used when ``proj_id`` is None and ``save_to_gdim`` is True,
    and it overrides the pipeline project. Archived projects are not searched.
    ``personal_space=False`` and ``space_name=None`` use the logged-in space.

personal_space: bool, default: False
    Whether ``proj_name`` is looked up in a personal space.

space_name: str | None, default: None
    Exact space name for ``proj_name``. None uses the current space.

host: str | None
    The host of the gdim platform.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.FilePath | PortTypeHint.FilesPath | PortTypeHint.GdimFile | PortTypeHint.GdimFiles | None

Attributes:

InputDocData: PortReference[PortTypeHint.DocData]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.FilesPath | PortTypeHint.GdimFile | PortTypeHint.GdimFiles]

class modules.writers.CreateGdimProject

Create one GDIM project in the current space.

Inherits from:: PipeModule

Methods:

Initialize the CreateGdimProject object.

Parameters

project_namestr | None, default: None: Name of the project to create. Required at run time. A non-empty value here overrides projectName in fields.
template_idstr | None, default: None: Id of the digital model. Required when template_name is omitted. A non-empty value here overrides a template id or name in fields.
template_namestr | None, default: None: Exact name of the digital model. Used when template_id is omitted. If more than one model has this name, creation fails and the template id must be used instead. fields: dict[str, Any] | None, default: None Other project-information values. Keys are field names. A field title is accepted when it does not collide with a field name. Which of these are required depends on the selected digital model. Address values can be a projectAddress object, or the flat keys projectAddressProvince, projectAddressCity, projectAddressDistrict, projectAddressDetail, and projectAddressCenter.
tokenstr | None: The token of the user.
hoststr | None: The host of the gdim platform. Ports
InputTokenPortTypeHint.Token: The token of the user.
OutputProjectInfoPortTypeHint.SingleResult: The created project.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.SingleResult | None: Create one project and return its information.

Attributes:

InputToken: PortReference[PortTypeHint.Token]

OutputProjectInfo: PortReference[PortTypeHint.SingleResult]

class modules.writers.CreateGdimProjects

Create new gdim projects.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'CreateGdimProjects', auto_run: bool = True, project_infos: PortTypeHint.SingleResult | PortTypeHint.TableData | None = None, raise_error: bool = True, token: str | None = None, host: str | None = None) → None

Initialize the CreateGdimProjects object.

Parameters

project_infosPortTypeHint.SingleResult | PortTypeHint.TableData | None, default: None: The project info of the projects to be created. Can be a SingleResult or a TableData.

Raises

token: str | None The token of the user.
host: str | None The host of the gdim platform. Ports
InputToken: PortTypeHint.Token The token of the user.
InputProjectInfos: PortTypeHint.SingleResult | PortTypeHint.TableData The project info of the projects to be created. Can be a SingleResult or a TableData.
OutputSingleResultDict: PortTypeHint.SingleResultDict The project info of the created projects in SingleResultDict format.
OutputTableData: PortTypeHint.TableData The table data of the created projects in TableData format.

execute() → PortTypeHint.SingleResult | PortTypeHint.SingleResultDict | None

Execute the CreateGdimProjects module.

Returns

Any

PortTypeHint.SingleResult |  PortTypeHint.SingleResultDict  | None
    If only one project is created, returns a SingleResult.
    If multiple projects are created, returns a SingleResultDict with project IDs as keys.

Attributes:

InputToken: PortReference[PortTypeHint.Token]

InputProjectInfos: PortReference[PortTypeHint.SingleResult | PortTypeHint.TableData]

OutputSingleResultDict: PortReference[PortTypeHint.SingleResult | PortTypeHint.SingleResultDict]

OutputTableData: PortReference[PortTypeHint.TableData]

class modules.writers.GdimTableWriter

Write the data of serveral tables in a GDIM project.

Notes

**Insert / update / delete:**
The same table may contain insert, update, and delete rows. Rows deleted by
id (``delete_table_data``) are not field-validated; tombstones kept for partial
update are validated like other write rows.

- Insert: rows without ``gdim_id`` are created as new GDIM records.
- Update: rows with ``gdim_id`` and at least one non-empty business field are
  written with partial update (``gdim_id`` renamed to ``id``).
- Tombstone: rows with ``gdim_id`` and all other payload fields empty. Strict
  subset payloads always partial-update tombstones. Full-schema payloads delete
  via ``delete_table_data`` when ``delete_tombstone_rows`` is True, otherwise
  partial-update. Full-schema delete tombstones should include every GDIM field
  (empty). Tables with only ``gdim_id`` are skipped with a warning.

To keep ``gdim_id`` when updating or deleting:
#. Set ``GdimTableReader.keep_gdim_id=True`` when reading from GDIM.
#. Use ``MergeGdimTables`` to attach ``gdim_id`` or emit 1:N tombstones.

Inherits from:: PipeModule

Methods:

__init__(mname: str | None = 'GdimTableWriter', auto_run: bool = True, data: PortTypeHint.ResultModel | PortTypeHint.TableData | PortTypeHint.TableCollection | PortTypeHint.GeneralTable | PortTypeHint.NumberTable | None = None, table_names: str | list[str] | None = None, fields_mapping: dict[str, str] | dict[str, dict[str, str]] | None = None, raise_error: bool = True, empty_warning_type: Literal[warning, gdi_warning] = 'warning', strict_datetime_validation: bool = True, validation_level: Literal[fast, full] = 'full', auto_convert: bool = False, delete_tombstone_rows: bool = True, token: str | None = None, proj_id: str | None = None, proj_name: str | None = None, personal_space: bool = False, space_name: str | None = None, host: str | None = None) → None

Initialize the GdimTableWriter object.

Parameters

dataPortTypeHint.ResultModel | PortTypeHint.TableData | PortTypeHint.TableCollection | PortTypeHint.GeneralTable | PortTypeHint.NumberTable | None: The data to be written to the gdim tables.
table_namesstr | list[str] | None, default: None: The name or title of the table to be written to. table name will be checked at first, if not found, the title will be checked. If None, for TableData and TableCollection, the name of the table in the table data will used. Otherwise, the table name is neccessary. If not None, for TableData and TableCollection, the table name in the data will be ignored. If list, the data should be TableCollection and has the same length as the data. fields_mapping: dict[str, str] | dict[str, dict[str, str]] | None, default: None The mapping of the fields in the data to the fields in the gdim tables. If dict[str, str], the key can be either the column name or field title in the source data, and the value can be either the field name or field title in the GDIM tables. If dict[str, dict[str, str]], the key is the table name or title, the value is the corresponding field mapping where keys can be source column names or field titles, and values can be GDIM field names or field titles. If the mapping for a field in the data is not defined, the original field name or title will be used. If None, the fields in the data will be written to the gdim tables without any mapping using the original field names or titles.

Raises

empty_warning_type: Literal[“warning”, “gdi_warning”], default: “warning” The type of warning when a table has no rows that can be written to GDIM. If warning, a UserWarning is printed in the console only. If gdi_warning, a GDIDataQualityWarning is raised and shown in GDIM.
strict_datetime_validation: bool, default: True If True, use regex + datetime parsing validation (slower, more accurate). If False, use regex-only validation (faster, slightly less accurate). Default is True for data quality.
validation_level: Literal[“fast”, “full”], default: “full”

Validation 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.

auto_convert: bool, default: False If True, coerce column values to match GDIM widget types before validation. This performs safe conversions such as numeric scalars to strings for text fields, datetime values to formatted strings for dateTime fields, and numeric strings to numbers for number fields. Default is False to preserve strict validation behavior.
delete_tombstone_rows: bool, default: True When the payload includes every GDIM field, tombstone rows are deleted by id via delete_table_data. If False, they are partial-updated instead. Strict subset payloads always partial-update tombstones (this flag does not apply).
token: str | None The token of the user.
proj_id: str | None The id of the gdim project. If self.proj_id is not None, the proj_id in InputToken or pipeline’s gdim_proj_id will be ignored. proj_name is ignored.
proj_name: str | None, default: None Exact project name. Used when proj_id is None, and it overrides the pipeline project. Archived projects are not searched. personal_space=False and space_name=None use the logged-in space.
personal_space: bool, default: False Whether proj_name is looked up in a personal space.
space_name: str | None, default: None Exact space name for proj_name. None uses the current space.
host: str | None The host of the gdim platform. Ports
InputToken: PortTypeHint.Token The token of the user.
InputData: PortTypeHint.ResultModel | PortTypeHint.TableData | PortTypeHint.TableCollection | PortTypeHint.GeneralTable | PortTypeHint.NumberTable The data to be written to the gdim tables.

Examples

- {"source_col_name": "target_field_name"}  # Column name to field name
    - {"Source Title": "Target Title"}          # Field title to field title
    - {"source_col": "Target Title"}            # Column name to field title
    - {"Source Title": "target_field"}          # Field title to field name

Notes

- If you want to change the ``proj_id`` by InputToken, DO NOT set ``proj_id`` in the constructor or assign value to ``proj_id``,
    as the ``self.proj_id`` has the highest priority. ``proj_name`` is used only when ``proj_id`` is None,
    and then it overrides the pipeline project.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → None | bool

Attributes:

InputToken: PortReference[PortTypeHint.Token]

InputData: PortReference[PortTypeHint.ResultModel | PortTypeHint.TableData | PortTypeHint.TableCollection | PortTypeHint.GeneralTable | PortTypeHint.NumberTable]

class modules.writers.MdbWriter

Write the data into a .mdb file.

Inherits from:: PipeModule

Methods:

Initialize the MdbWriter object.

Parameters

dataPortTypeHint.TableCollection | None: The data to be written to the mdb.
mdb_template_filestr | dict | None: The mdb template file. If it is a dict, it will be converted to a GdimMinIOFile object. If it is a str, it will be used as the path to the mdb template file.
tokenstr | None: The token of the user.
proj_idint | str | None: The id of the gdim project. When set, proj_name is ignored. Used when InputTables is one project, and when a local mdb template is uploaded.
proj_namestr | None, default: None: Exact project name. Used when proj_id is None, and it overrides the pipeline project. Archived projects are not searched. personal_space=False and space_name=None use the logged-in space. A multi-project write still uses proj_ids.
personal_spacebool, default: False: Whether proj_name is looked up in a personal space.
space_namestr | None, default: None: Exact space name for proj_name. None uses the current space.
hoststr | None: The host of the gdim platform.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → None | PortTypeHint.GdimFile

Attributes:

InputToken: PortReference[PortTypeHint.Token]

InputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableCollectionDict]

OutputGdimFile: PortReference[PortTypeHint.GdimFile]

class modules.writers.TextWriter

Write a plain-text string or JSON object or ResultModel to a file with an arbitrary extension.

The data received on InputText is written to disk as a UTF-8 file. When the input is a JsonObject (dict or list) it is automatically serialised to a JSON string before writing. When the input is a ResultModel, text is built via ResultModel.to_plain_text (see that method for result_model_keys and result_model_value_separator behaviour). The file extension defaults to "txt" but can be set to anything (e.g. "md", "json", "csv"). When save_to_gdim is True the file is also uploaded to the GDIM MinIO file server.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'TextWriter', auto_run: bool = True, text: PortTypeHint.Text | PortTypeHint.JsonObject | ResultModel | None = None, output_dir: str | None = None, output_name: str = 'output', suffix: str = 'txt', encoding: str = 'utf-8', save_to_gdim: bool = False, token: str | None = None, proj_id: int | str | None = None, proj_name: str | None = None, personal_space: bool = False, space_name: str | None = None, host: str | None = None, json_indent: int | None = 2, result_model_keys: list[str] | None = None, result_model_value_separator: str = '\n\n') → None

Initialise a TextWriter module.

Parameters

textstr | dict | list | ResultModel | None: The text content (or JSON-serialisable object, or :class:ResultModel) to write supplied via the ``InputText`` port.
output_dirstr | None: Directory in which to create the file. The pipeline’s ``workspace`` takes priority. Falls back to the current working directory when both are ``None``.
output_namestr, default: ``"output"``: Base name of the output file (without extension).
suffixstr, default: ``"txt"``: File extension without the leading dot, e.g. ``"txt"``, ``"md"``, ``"json"``.
encodingstr, default: ``"utf-8"``: Text encoding used when writing the file.
save_to_gdimbool, default: ``False``: When ``True``, the file is also uploaded to the GDIM MinIO file server. Requires a valid token and either ``proj_id`` or ``proj_name`` (from this module, the ``InputToken`` port, or the pipeline’s ``gdim_state``).
tokenstr | None: User token. Can also be supplied via the pipeline’s ``gdim_state``.
proj_idint | str | None: GDIM project id. Can also be supplied via the pipeline’s ``gdim_state``. When set, ``proj_name`` is ignored.
proj_namestr | None, default: ``None``: Exact project name. Used when ``proj_id`` is None and ``save_to_gdim`` is True, and it overrides the pipeline project. Archived projects are not searched. ``personal_space=False`` and ``space_name=None`` use the logged-in space.
personal_spacebool, default: ``False``: Whether ``proj_name`` is looked up in a personal space.
space_namestr | None, default: ``None``: Exact space name for ``proj_name``. None uses the current space.
hoststr | None: GDIM platform host. Can also be obtained from the pipeline.
json_indentint | None, default: ``2``: Indentation level used when serialising a ``JsonObject`` input to a JSON string. Pass ``None`` for compact (no indentation) output. Also applied when embedding ``dict`` values inside a :class:ResultModel field.
result_model_keyslist[str] | None, default: ``None``: When ``InputText`` is a :class:ResultModel, only these field names or display titles are written, in this order. When ``None``, every field whose value is JSON-serialisable (see module logic) is included in model definition order.
result_model_value_separatorstr, default: ``"\n\n"``: When ``InputText`` is a :class:ResultModel, used to join (1) items when a field value is a sequence and (2) the rendered strings of successive fields. Ports
InputTextPortTypeHint.Text | PortTypeHint.JsonObject | PortTypeHint.ResultModel: The text content, JSON-serialisable object, or structured result to write. When a ``JsonObject`` (``dict`` or ``list``) is received it is serialised to a JSON string. When a :class:ResultModel is received it is flattened to plain text as described above.
InputTokenPortTypeHint.Token: User token (optional — see parameter description above).
OutputFilePortTypeHint.FilePath | PortTypeHint.GdimFile: The saved file path, or the GDIM file object when ``save_to_gdim`` is ``True``.

execute() → PortTypeHint.FilePath | PortTypeHint.GdimFile | None: Write the input text to a file and optionally upload it to GDIM.

Attributes:

InputText: PortReference[PortTypeHint.Text | PortTypeHint.JsonObject | PortTypeHint.ResultModel]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.GdimFile]

class modules.writers.ExportGdimTables

Export all tables’ data of a gdim project in a specified format.

The exported file always contains both the human-readable title and the internal
name for every table and field:

- **Table identification**: each table's CSV file / Excel sheet is named after its
  *title* (truncated to 31 characters for Excel).  The metadata entry records both
  the ``name`` and ``title`` so readers can always recover the full title even when
  the sheet name was truncated.
- **Field headers**: row 1 contains field *titles*, row 2 contains field *names*,
  row 3 contains field *units* (for ``input`` and ``number`` fields; use ``-`` when
  no unit applies), and data rows start at row 4.  When
  ``export_fields_description=True``, row 4 contains field descriptions
  (data type in plain language and format hints) and data starts at row 5.
- **Metadata**: a ``metadata`` file / sheet stores ``dataTemplateId``, a ``tables``
  mapping (keyed by internal name), a ``tableRelations`` mapping (keyed by
  internal name), a ``coordinateSystem`` object with the project's coordinate
  system settings (when a GDIM token is available), and a ``templateInstruction``
  describing the header layout.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'ExportGdimTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, template_id: PortTypeHint.ResultModel | None = None, format: Literal[gtb, xlsx] = 'gtb', output_dir: str | None = None, output_name: str = 'gdim_tables', save_to_gdim: bool = False, export_fields_description: bool = False, token: str | None = None, proj_id: int | str | None = None, proj_name: str | None = None, personal_space: bool = False, space_name: str | None = None, host: str | None = None) → None

Initialize the ExportGdimTables object.

Parameters

output_dirstr | None: The directory to save the generated document. The pipeline’s workspace takes priority over this value. If both are None, the current working directory is used.
output_namestr, default: “gdim_tables”: Base name of the output file (without extension).
save_to_gdimbool, default: False: When True, the generated file is also uploaded to the GDIM file server. Requires a valid token and either proj_id or proj_name.
export_fields_descriptionbool, default: False: When True, row 4 of each table sheet contains field descriptions (data type in plain language, with format hints for number / dateTime). Data rows then start at row 5. The flag is stored in file metadata so ReadGtbFile can parse it back.
tokenstr | None: The user token. Can also be supplied via the pipeline’s gdim_state.
proj_idint | str | None: The GDIM project id. Can also be supplied via the pipeline’s gdim_state. When set, proj_name is ignored.
proj_namestr | None, default: None: Exact project name. Used when proj_id is None, and it overrides the pipeline project. Archived projects are not searched. personal_space=False and space_name=None use the logged-in space. The resolved id is used for table relations, the coordinate system, and save_to_gdim.
personal_spacebool, default: False: Whether proj_name is looked up in a personal space.
space_namestr | None, default: None: Exact space name for proj_name. None uses the current space.
hoststr | None: The host of the gdim platform. Can be get from the pipeline. Ports
InputTablesPortTypeHint.TableCollection | PortTypeHint.TableData: The tables to be saved.
InputTemplateIdPortTypeHint.ResultModel: The template id stored in the project information.
InputTokenPortTypeHint.Token: The user token. Optional — see parameter description above.
OutputFilePortTypeHint.FilePath | PortTypeHint.GdimFile: The saved file path or GDIM file object.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.FilePath | PortTypeHint.GdimFile | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

InputTemplateId: PortReference[PortTypeHint.ResultModel]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.GdimFile]

class modules.writers.UpdateGdimAppProjectInfo

Update the data of Project Information APP.

Inherits from:: PipeModule

Methods:

Initialize the UpdateGdimAppProjectInfo object.

Parameters

update_dataPortTypeHint.SingleResult | PortTypeHint.ResultModel | PortTypeHint.CoordinateSystem | None

The data of the project information to update. Coordinate system information can also be supplied as a :class:~gdi.dataclass.results.CoordinateSystem object or included in the update_data ResultModel / SingleResult fields. If key of a field is not in the data, the value of the field will be kept unchanged. For projectAddress, here are the keys:

projectAddressProvince
projectAddressCity
projectAddressDistrict
projectAddressDetail
projectAddressCenter

tokenstr | None

The token of the user.

proj_idint | str | None

The id of the project. When set, proj_name is ignored.

proj_namestr | None, default: None

Exact project name. Used when proj_id is None, and it overrides the pipeline project. Archived projects are not searched. personal_space=False and space_name=None use the logged-in space.

personal_spacebool, default: False

Whether proj_name is looked up in a personal space.

space_namestr | None, default: None

Exact space name for proj_name. None uses the current space.

hoststr | None

The host of the gdim platform.

Notes

For cutomer fields in the project information, both field name or field title is accepted.

execute() → PortTypeHint.ResultModel | None

Attributes:

InputToken: PortReference[PortTypeHint.Token]

InputResultModel: PortReference[PortTypeHint.SingleResult | PortTypeHint.ResultModel | PortTypeHint.CoordinateSystem]

OutputResultModel: PortReference[PortTypeHint.ResultModel]

class modules.writers.BorePlanDrawWriter

Write the input table collection to a .gsc file which can be used for bores plan drawing in KCAD.

Inherits from:: PipeModule

Methods:

__init__(mname: str | None = 'ConvertToBorePlanForCad', auto_run: bool = True, tables: PortTypeHint.TableCollection | None = None, proj_info: PortTypeHint.ResultModel | None = None, coordinate_system: PortTypeHint.SingleResult | None = None, name_maps: dict[str, dict[str, str]] | None = None, bore_types_map: dict[str, BoreTypes] | None = None, proj_info_name_map: dict[str, str] | None = None, output_dir: str | Path | None = None, gsc_file_name: str = 'bore_plan_for_cad_draw.gsc', save_to_gdim: bool = False, token: str | None = None, proj_id: int | str | None = None, proj_name: str | None = None, personal_space: bool = False, space_name: str | None = None, host: str | None = None) → None

Initialize a ConvertToBorePlanForCad object.

Parameters

tablesPortTypeHint.TableCollection | None, default: None: The input table collection containing bore and section line data. Here are the table names:

bore_table : 钻孔一览表

section_lines_table : 剖面线表

proj_infoPortTypeHint.ResultModel | None, default: None: The input ResultModel containing project info data. name_maps: dict[str, dict[str, str]] | None, default: None Optional override when input tables do not use GDIM reserved names. Leave as None when tables already use reserved names (bore_table, bore_number, x_coordinate, bore_top, section_lines_table, section_number, bore_numbers, etc.). table_names maps a reserved table name to the actual table name or title; field_names maps reserved field names to actual field names or titles, grouped by reserved table name.

Examples

{
            "table_names": {
                "bore_table": "exploration_points",
                "section_lines_table": "fence_lines",
            },
            "field_names": {
                "bore_table": {
                    "bore_number": "hole_id",
                    "x_coordinate": "east",
                    "y_coordinate": "north",
                    "bore_type": "hole_type",
                    "bore_top": "collar_elev",
                    "steady_ground_water_depth": "gwt",
                },
                "section_lines_table": {
                    "section_number": "line_name",
                    "bore_numbers": "holes",
                },
            },
        }

bore_types_map: dict[str, BoreTypes] | None, default: None
    Mapping from string bore type names to BoreTypes enum.
    For example: {"鉴别孔": BoreTypes.IdentificationBore, "取土试样钻孔": BoreTypes.SoilSamplingBore}
    If the map is not specified, will try to compare to the names and titles of BoreTypes automatically.

proj_info_name_map: dict[str, str] | None, default: None
    The mapping of the field_name of the ``geoProfiles.ProjectInfo`` and field_name or field_title of the result model.
    The key is the field_name in ``geoProfiles.ProjectInfo``.
    The value is the field_name or field_title from the result model,
    If the mapping of a key is not provided,
    the function will try to find the field_name of the result model which is same as the ``geoProfiles.ProjectInfo`` field_name automatically.

output_dir: str |  Path  | None, default: None
    The directory to save the output gsc file.
    - 'workspace' of pipeline has priority over the 'output_dir'.
    - If both 'output_dir' and 'workspace' are None, the current working directory will be used.

gsc_file_name: str, default: "bore_plan_for_cad_draw.gsc"
    The name of the gsc file. If None, the gsc file will not be saved.

save_to_gdim: bool, default: False
    If True, the generated .gsc file will also be saved to the gdim file server.
    Requires a valid token and either ``proj_id`` or ``proj_name``.

token: str | None
    The token of the user.
    Must be provided when ``save_to_gdim`` is True.

proj_id: int |  str  | None
    The id of the gdim project.
    Must be provided when ``save_to_gdim`` is True, unless ``proj_name`` is set.
    When set, ``proj_name`` is ignored.

proj_name: str | None, default: None
    Exact project name. Used when ``proj_id`` is None and ``save_to_gdim`` is True,
    and it overrides the pipeline project. Archived projects are not searched.
    ``personal_space=False`` and ``space_name=None`` use the logged-in space.

personal_space: bool, default: False
    Whether ``proj_name`` is looked up in a personal space.

space_name: str | None, default: None
    Exact space name for ``proj_name``. None uses the current space.

host: str | None
    The host of the gdim platform.

Ports
InputTables: PortTypeHint.TableCollection
    The input table collection containing bore and section line data.

InputSectionLines: PortTypeHint.TableData
    Optional cross-section table from GdimCrossSectionReader.OutputTable.

InputProjectInfo: PortTypeHint.ResultModel
    The input project info.

InputCoordinateSystem: PortTypeHint.CoordinateSystem
    The input coordinate system.

InputToken: PortTypeHint.Token
    The token of the user.

OutputFile: PortTypeHint.FilePath | PortTypeHint.GdimFile
    The output gsc file.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.FilePath | PortTypeHint.GdimFile | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection]

InputSectionLines: PortReference[PortTypeHint.TableData]

InputProjectInfo: PortReference[PortTypeHint.ResultModel]

InputCoordinateSystem: PortReference[PortTypeHint.CoordinateSystem]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.GdimFile]

class modules.writers.BoreLogDrawWriter

Write the input table collection to a .gsc file which can be used for bores log drawing in KCAD.

Inherits from:: PipeModule

Methods:

Initialize a ConvertToBoreForCadDraw object.

Parameters

tablesPortTypeHint.TableCollection | None, default: None: The input table collection containing bore, layer, and test data etc. Here are the table names:

bore_table : 钻孔一览表

layer_table : 地层表

standard_layer_table : 标准地层表

spt_table : 标贯表

cpt_table : 双桥静力触探表

dpt_table : 动探表

sonic_logging_table : 声波测井表

sampling_log_table : 取样表

soil_test_table常规试验表。场地工程勘察的湿陷系数、自重湿陷系数在此表；: 若仍提供 loess_collapsibility_table，则优先使用该表。

loess_collapsibility_table : 黄土湿陷性表（旧模板，可选）

proposed_geotechnical_parameters_table : 岩土参数建议值表

proj_infoPortTypeHint.ResultModel | None, default: None: The input ResultModel containing project info data. name_maps: dict[str, dict[str, str]] | None, default: None Optional override when input tables do not use GDIM reserved names. Leave as None when tables already use reserved names (bore_table, standard_layer_table, layer_table, spt_table, dpt_table, cpt_table, sonic_logging_table, sampling_log_table, soil_test_table, loess_collapsibility_table, proposed_geotechnical_parameters_table). table_names maps a reserved table name to the actual table name or title; field_names maps reserved field names to actual field names or titles, grouped by reserved table name.

Examples

{
            "table_names": {
                "bore_table": "exploration_points",
                "layer_table": "strata",
                "standard_layer_table": "std_strata",
            },
            "field_names": {
                "bore_table": {
                    "bore_number": "hole_id",
                    "x_coordinate": "east",
                    "y_coordinate": "north",
                    "bore_top": "collar_elev",
                },
                "layer_table": {
                    "bore_number": "hole_id",
                    "layer_bottom_depth": "bottom",
                    "layer_number": "stratum",
                },
            },
        }

selected_bores: list[str] | None, default: None
    List of bores (input bore numbers) to convert. If None, all bores will be converted.

drawing_scales: dict[str, int] |  int  | None, default: None
    Drawing scales for bores.
    If int, it will be used for all bores.
    If dict, the key is bore number, the value is drawing scale.
    If list, use the following format -
        ``[{"bore_number": "num_1", "drawing_scales": 200}, {"bore_number": "num_2", "drawing_scales": 300}]``

proj_info_name_map: dict[str, str] | None, default: None
    The mapping of the field_name of the ``geoProfiles.ProjectInfo`` and field_name or field_title of the result model.
    The key is the field_name in ``geoProfiles.ProjectInfo``.
    The value is the field_name or field_title from the result model,
    If the mapping of a key is not provided,
    the function will try to find the field_name of the result model which is same as the ``geoProfiles.ProjectInfo`` field_name automatically.

sample_types_map: dict[str, int] | None, default: None
    Optional exact mapping from sample type name to integer code.
    When ``None``, names are coded by substring: 「原状」→ 0,
    「扰动」→ 1, 「岩」→ 2, 「水」→ 3; anything else → -1.
    When set, listed names use the map; unlisted names still use the
    substring rule. Original names are stored in
    ``SamplingLog.sample_type_name``.

output_dir: str |  Path  | None, default: None
    The directory to save the output gsc file.
    - 'workspace' of pipeline has priority over the 'output_dir'.
    - If both 'output_dir' and 'workspace' are None, the current working directory will be used.

gsc_file_name: str, default: "bore_for_cad_draw.gsc"
    The name of the gsc file.

save_to_gdim: bool, default: False
    If True, the generated document will also be saved to the gdim file server.
    Requires a valid token and either ``proj_id`` or ``proj_name``.

token: str | None
    The token of the user.
    Must be provided when ``save_to_gdim`` is True.

proj_id: int |  str  | None
    The id of the gdim project.
    Must be provided when ``save_to_gdim`` is True, unless ``proj_name`` is set.
    When set, ``proj_name`` is ignored.

proj_name: str | None, default: None
    Exact project name. Used when ``proj_id`` is None and ``save_to_gdim`` is True,
    and it overrides the pipeline project. Archived projects are not searched.
    ``personal_space=False`` and ``space_name=None`` use the logged-in space.

personal_space: bool, default: False
    Whether ``proj_name`` is looked up in a personal space.

space_name: str | None, default: None
    Exact space name for ``proj_name``. None uses the current space.

host: str | None
    The host of the gdim platform.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.FilePath | PortTypeHint.GdimFile | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection]

InputProjectInfo: PortReference[PortTypeHint.ResultModel]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.GdimFile]

class modules.writers.GeoSectionsWriter

Write geo sections to a .gsc file which can be used for geological section drawing in KCAD.

The geo sections are generated by the ExportGeoSectionsByBores module.

Inherits from:: PipeModule

Methods:

Initialize the GeoSectionsWriter object.

Parameters

proj_idint | str | None: The id of the gdim project. Must be provided when save_to_gdim is True, unless proj_name is set. When set, proj_name is ignored.
proj_namestr | None, default: None: Exact project name. Used when proj_id is None and save_to_gdim is True, and it overrides the pipeline project. Archived projects are not searched. personal_space=False and space_name=None use the logged-in space.
personal_spacebool, default: False: Whether proj_name is looked up in a personal space.
space_namestr | None, default: None: Exact space name for proj_name. None uses the current space.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.FilePath | PortTypeHint.GdimFile | None

Attributes:

InputGeoSections: PortReference[PortTypeHint.GeoSections]

InputToken: PortReference[PortTypeHint.Token]

OutputFile: PortReference[PortTypeHint.FilePath | PortTypeHint.GdimFile]