modules.writers 模块帮助

本章节包含 modules.writers 包中常用「数据写入 / 导出」模块的使用说明和示例，例如：

• 写入 GDIM 表格、文件服务器或本地文件的模块

• 导出 Word / Excel 报告的模块

DocDataWriter

模块简介与适用场景

• DocDataWriter 用于将多种输入数据（ SingleResult / TableData / TableCollection / 文件路径）转换为统一的 DocData``（端口： ``OutputDocData），供 :class:`gdisdk.modules.writers.DocPrinter`（Word）或 :class:`gdisdk.modules.writers.ExcelPrinter`（Excel）基于模板渲染输出。

• 典型适用场景：

  • 将计算模块输出的 SingleResult 转为报告变量（如数值指标、结论文本等）；

  • 将 TableData / TableCollection 转为可用于模板渲染的 “表格数据 + 表头结构”；

  • 将图片文件（ .png/.jpg/...）或子文档（ .docx/.xlsx）路径写入 DocData，在模板中插入图片或子文档；

  • 通过 export_keys_to_json 导出模板变量结构（doc keys），用于配置 Word/Excel 模板；

  • 通过 export_data_to_json 导出实际打印数据，用于核对报告里会写入的内容。

Hint

DocData``（``data / doc_keys_struct）结构与导出方法说明，见 DocData：报告打印的数据容器（模板 keys 与渲染数据）。

端口说明

• 输入端口 - InputData：输入数据（SingleResult / TableData / TableCollection / FilePath / FilesPath）

• 输出端口 - OutputDocData：输出文档数据（DocData，可直接用于 DocPrinter / ExcelPrinter 渲染）

快速上手示例：将 GDIM 表格转换为 DocData，并导出模板变量结构

from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import DocDataWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="GenerateDocKeys", app_title="导出模板变量结构示例")
pipeline.workspace = "test"

read_table = GdimTableReader(mname="ReadTable")
read_table.table_fields = ["钻孔一览表"]

doc_data = DocDataWriter(mname="DocData")
doc_data.precision = 2  # 所有数值保留 2 位小数

links = read_table.OutputTables >> doc_data.InputData
pipeline.add_links(links)
pipeline.run()

# 导出模板变量结构（用于模板中 {{key}} / 表格循环等配置）
doc_data.OutputDocData.data.export_keys_to_json("bore_table_doc_keys.json")

# （可选）导出打印数据（用于检查最终会写进报告的内容）
doc_data.OutputDocData.data.export_data_to_json("bore_table_doc_data.json")

参数说明

DocDataWriter 参数一览

参数名	类型	默认值	说明
precision	int | dict[str, int | None] | None	None	数值格式化小数位数；支持统一 int 或按 “字段名/字段标题（SingleResult 也支持 result 名/标题）” 分别配置。
datetime_format	str | dict[str, str | None] | None	None	日期时间格式化（strftime）；支持统一 str 或按字段分别配置。
merge_strategy	"auto" | "none" | "explicit"	"auto"	仅对 TableCollection 生效：是否按主子表关系合并（auto）、完全不合并（none）、或按 explicit_merges 指定合并规则（explicit）。
explicit_merges	list[dict[str, str | list[str]]] | None	None	仅 merge_strategy="explicit" 时生效；指定 main/subs/group_by 等合并规则。
table_doc_key_name	str | None	None	仅对 TableData 或 “只含 1 张表的 TableCollection” 生效：表格在 DocData 中的 key；未设置时默认使用 ``TableData.name``（若 name 为空会报错）。
table_doc_key_title	str | None	None	仅对 TableData 或 “只含 1 张表的 TableCollection”生效：表格在 doc keys 中展示的标题；未设置时默认使用 TableData.title。
joiner	str	,	仅对 SingleResult 生效：当某个 result 的值是 list 时，使用 joiner 拼接为字符串。
files_path_to_list	str | None	None	仅对 “文件列表输入” （FilesPath/list[str|Path]）生效：将整个列表写入一个 key（并自动判断是图片列表或子文档列表）。
files_path	list[str] | list[Path] | None	None	若设置则忽略 InputData，直接将 files_path 作为输入（常用于将若干子文档合并/插入到主模板数据中）。
latex_to_unicode_keys	str | list[str] | dict[str, str | list[str]] | None	None	将指定 key 的字符串值从 LaTeX 转为 Unicode（例如 \\alpha→α ， H_{2}O→H₂O ），便于直接打印模型公式等；支持根级 key、表格列 key 以及混合模式（"__root__"）。

latex_to_unicode_keys 用法示例

# 1) 根级 key（单个 / 多个）
doc = DocDataWriter("Doc")
doc.latex_to_unicode_keys = "model_expression"
# 或
doc.latex_to_unicode_keys = ["model_expression", "formula"]

# 2) 表格列 key（dict 模式）
doc.latex_to_unicode_keys = {"table1": "column1"}
# 或
doc.latex_to_unicode_keys = {"table1": ["col1", "col2"]}

# 3) 混合模式（dict + "__root__"）
doc.latex_to_unicode_keys = {"__root__": ["key1"], "table1": ["col1"]}

说明：

• key 支持使用 字段名 或 **字段标题**（会按 doc keys 结构自动映射）

• 仅对 字符串值 生效，非字符串值保持不变

• 支持常见 LaTeX 语法（希腊字母、分数、根号、上下标、无穷大等）

在 pipeline 中的使用方式：组合多个 DocDataWriter 并合并

当报告需要同时写入多份数据（例如：指标结果 + 图像 + 多张表格），常见做法是 “多个 DocDataWriter + MergeDocData 合并后再打印”：

from gdisdk.modules.writers import DocDataWriter, MergeDocData

data_doc = DocDataWriter("DataDoc")   # 例如：TableCollection / TableData
image_doc = DocDataWriter("ImageDoc") # 例如：图片路径（OutputImageFile）

merge_doc = MergeDocData("MergeDoc")
merge_doc.add_dynamic_ports_in("InputDataDocData")
merge_doc.add_dynamic_ports_in("InputImageDocData")

links = data_doc.OutputDocData >> merge_doc.InputDataDocData | image_doc.OutputDocData >> merge_doc.InputImageDocData

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）

TextWriter

模块简介与适用场景

• TextWriter 用于将纯文本字符串、JSON 对象或 ResultModel 写入本地文本文件。

• 适合将 Markdown、提示词、LLM 输出、结构化结果模型、配置 JSON、调试文本等结果落盘，便于下载、归档或继续传给下游系统。

• 支持自定义输出后缀名（如 txt / md / json / csv），并可在需要时上传到 GDIM 文件服务器。

端口说明

• 输入端口 - InputText：输入文本、JSON 对象或 ResultModel``（会通过 ``to_plain_text 转为纯文本后再写入） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；若未提供则可从 pipeline.gdim_state 获取

• 输出端口 - OutputFile：输出文件（本地保存时为 FilePath，上传 GDIM 时为 GdimFile）

快速上手示例：写出 Markdown 文件

from gdisdk.modules.writers import TextWriter

writer = TextWriter(
    text="# 结果摘要\n\n- 项目：示例项目\n- 结论：可行",
    output_dir="workspace",
    output_name="summary",
    suffix="md",
)
output_file = writer.execute()
print(output_file)

快速上手示例：写出 JSON 文件

from gdisdk.modules.writers import TextWriter

writer = TextWriter(
    text={"project": "Demo", "score": 95, "passed": True},
    output_name="result",
    suffix="json",
    json_indent=2,
)
output_file = writer.execute()
print(output_file)

参数说明

TextWriter 参数一览

参数名	类型	默认值	说明
result_model_keys	list[str] | None	None	当 InputText 为 ResultModel 时，仅按给定顺序写出这些字段（字段名或展示标题）；为 None 时写出模块逻辑允许的各字段（定义顺序）。
result_model_value_separator	str	"\n\n"	当 InputText 为 ResultModel 时，用于连接字段值序列中的条目以及相邻字段渲染结果（参见 ResultModel.to_plain_text）。
output_dir	str | None	None	输出目录；若 pipeline 设置了 workspace，则优先使用 workspace；两者都为空时使用当前工作目录。
output_name	str	"output"	输出文件名（不含扩展名）。
suffix	str	"txt"	输出文件后缀名（不含前导点），例如 "md"、"json"、"csv"。
encoding	str	"utf-8"	写文件时使用的文本编码。
save_to_gdim	bool	False	是否将文件同时上传到 GDIM 文件服务器；为 True 时需要可用的 token/proj_id/host。
token	str | None	None	GDIM 用户 token；通常更推荐通过 pipeline.update_gdim_state(...) 统一设置。
proj_id	int | str | None	None	GDIM 项目 ID；可通过 InputToken 或 pipeline.gdim_state 提供。
host	str | None	None	GDIM 平台地址；通常沿用 pipeline 中的 GDIM 状态即可。
json_indent	int | None	2	当输入为 dict / list 时，序列化为 JSON 字符串的缩进；为 None 时输出紧凑 JSON。当输入为 ResultModel 时，传给 to_plain_text，亦用于字段内嵌 dict 等值的 JSON 格式化。

上传 GDIM 前检查

• 是否需要特别处理：当文本文件需要在 GDIM 中留存、回传或提供给后续节点下载时，是。

• 必须检查：

  • 将 save_to_gdim 设为 True，否则结果只会保存在本地路径。

• 建议检查：

  • suffix 设为明确的业务格式，如 md、json、csv，方便下游识。

• 若遗漏，常见现象：

  • 本地运行能生成文件，但上传 GDIM 后拿不到期望的 GdimFile 输出；

  • 下游系统拿到文件后无法按预期格式解析，例如把 Markdown 当成普通 txt。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import TableToMarkdown
from gdisdk.modules.writers import TextWriter

pipeline = PipeLine(app_name="WriteMarkdownDemo", app_title="写出Markdown文件")
pipeline.workspace = "workspace"

to_md = TableToMarkdown("ToMarkdown")
writer = TextWriter("WriteMarkdown", output_name="table_result", suffix="md")

# links = upstream.OutputTable >> to_md.InputTable | to_md.OutputMarkdown >> writer.InputText
# pipeline.add_links(links)
# pipeline.run()

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）

ExportGdimTables

模块简介与适用场景

• ExportGdimTables 用于将 GDIM 表格数据导出为 .gtb 或 .xlsx 文件（端口：OutputFile）。

• 该模块适合在 “读出项目表格后，打包给外部系统 / 人工下载 / 二次导入” 的场景中使用。

• 两种导出格式的区别：

  • gtb：导出为 GDIM 兼容的压缩包，内部包含各表 CSV 文件和 metadata 文件；

  • xlsx：导出为 Excel 文件，第一个工作表为 metadata，后续每个工作表对应一张表。

• 导出文件会同时保留表/字段的 title 与 name 信息：

  • 每张表的 CSV 文件名 / Excel 工作表名优先使用表标题，元数据中同时记录内部名、标题和工作表名；

  • 每张表的第 1 行写字段标题，第 2 行写字段内部名，数据从第 3 行开始。

• 输出支持保存到本地或上传 GDIM 文件服务器（save_to_gdim=True）。

端口说明

• 输入端口 - InputTables：待导出的表格数据（TableCollection 或 TableData） - InputTemplateId：项目资料中的模板信息（ResultModel，需包含 dataTemplateId） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取

• 输出端口 - OutputFile：导出结果；本地保存时为 FilePath，上传 GDIM 时为 GdimFile

快速上手示例：导出 GDIM 表格为 Excel

from gdisdk.connectors import log_in
from gdisdk.modules.readers import GdimAppProjectInfoReader, GdimTableReader
from gdisdk.modules.writers import ExportGdimTables
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="ExportGdimTablesDemo", app_title="导出GDIM表格示例")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_tables = GdimTableReader("ReadTables")
read_tables.table_fields = ["钻孔一览表", "地层信息表"]

read_project_info = GdimAppProjectInfoReader("ReadProjectInfo")

export_tables = ExportGdimTables("ExportTables")
export_tables.format = "xlsx"
export_tables.output_name = "项目表格导出"

links = (
    read_tables.OutputTables >> export_tables.InputTables
    | read_project_info.OutputProjectInfo >> export_tables.InputTemplateId
)
pipeline.add_links(links)

pipeline.run()
print(export_tables.OutputFile.data)

参数说明

ExportGdimTables 参数一览

参数名	类型	默认值	说明
format	"gtb" | "xlsx"	"gtb"	导出格式。gtb 适合 GDIM 兼容交换；xlsx 适合人工查看和通用 Excel 流程。
output_dir	str | None	None	输出目录；若 pipeline 设置了 workspace，则优先使用 workspace。
output_name	str	"gdim_tables"	导出文件名（不含扩展名）。
save_to_gdim	bool	False	是否将导出结果上传到 GDIM 文件服务器；为 True 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

• 是否需要特别处理：当导出的表格文件需要在 GDIM 中回传、下载或被后续流程消费时，是。

• 必须检查：

  • 将 save_to_gdim 设为 True，否则结果只会保存在本地路径；

• 建议检查：

  • output_name 设为清晰稳定的文件名，便于在 GDIM 文件列表中识别。

• 若遗漏，常见现象：

  • 本地运行能生成文件，但上传 GDIM 后拿不到期望的 GdimFile 输出；

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）

GdimTableWriter

模块简介与适用场景

• GdimTableWriter 用于将 ResultModel、TableData、TableCollection、GeneralTable 或 NumberTable 写入 GDIM 项目的业务表。

• 典型适用场景：

  • 将本地整理后的表格数据回写到指定 GDIM 表；

  • 将 ResultModel 形式的结果数据写入项目资料表，供后续流程或前端界面继续使用；

  • 配合 GdimTableReader(keep_gdim_id=True) 和 MergeGdimTables，对 GDIM 中已有记录执行“更新而不是新增”。

Hint

如果数据里包含 gdim_id 列，模块会在写入时自动将其转换回 GDIM 识别的 id 字段：

1. 从 GDIM 读取已有数据时，将 GdimTableReader.keep_gdim_id 设为 True；

2. 若是“新数据 + 旧数据”混合回写，建议先通过 MergeGdimTables 为已有记录补齐 gdim_id；

3. 带 gdim_id 的记录会被更新，不带 gdim_id 的记录会作为新记录插入。

端口说明

• 输入端口 - InputData：待写入的数据（ResultModel / TableData / TableCollection / GeneralTable / NumberTable） - InputToken：鉴权与项目定位信息 (token, proj_id, host)。若 pipeline 已通过 update_gdim_state(token=..., proj_id=...) 配置 gdim_state，可从pipeline自动取得 token，该端口可不连接；否则需提供 token。若构造函数里已经设置 proj_id，则该值优先级高于 InputToken 或 pipeline.gdim_state 中的项目 ID。

• 输出端口 - 无专门输出端口；execute 在全部写入成功（write_table_data 返回空错误字典）时返回 True。缺少 token、InputData 为空、或无法取得项目 ID（构造参数 proj_id、InputToken、pipeline gdim_state 均无有效 proj_id）时返回 None。raise_error=True 时，校验失败或接口错误通常直接抛错；raise_error=False 时失败信息以 warning 形式汇总，若仍有部分数据成功写入则可能返回 True，全部失败则可能返回 None。

快速上手示例：将表格数据写入 GDIM 指定表

from gdisdk.connectors import log_in
from gdisdk.dataclass import TableData
from gdisdk.modules.writers import GdimTableWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="GdimTableWriterDemo", app_title="写入GDIM表示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

table = TableData(
    data={
        "钻孔编号": ["ZK-001", "ZK-002"],
        "孔口高程": [12.35, 14.10],
    },
    name="borehole_summary",
    title="钻孔一览表",
)

writer = GdimTableWriter("WriteTable")
writer.InputData = table
writer.table_names = "钻孔一览表"

pipeline.run()

快速上手示例：更新 GDIM 中已有记录

from gdisdk.connectors import log_in
from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import GdimTableWriter
from gdisdk.pipeline import PipeLine

pipeline = PipeLine(app_name="UpdateGdimTableDemo", app_title="更新GDIM记录示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)

read_table = GdimTableReader("ReadTable")
read_table.table_fields = ["钻孔一览表"]
read_table.keep_gdim_id = True

writer = GdimTableWriter("WriteBack")
writer.table_names = "钻孔一览表"

# 实际使用时，通常会在两者之间插入清洗、计算或合并模块
links = read_table.OutputTableData >> writer.InputData
pipeline.add_links(links)

pipeline.run()

参数说明

GdimTableWriter 参数一览

参数名	类型	默认值	说明
table_names	str | list[str] | None	None	目标表名或表标题（会先按表名匹配，再按表标题）。为 None 时，TableData / TableCollection 使用数据对象自带的表名/标识；非 None 时，对 TableData / TableCollection 会忽略数据内部自带的表名，以本参数为准。若传入 list，要求输入为 TableCollection 且与集合长度一一对应。
fields_mapping	dict[str, str] | dict[str, dict[str, str]] | None	None	源字段到 GDIM 字段的映射。键和值都可使用字段名或字段标题；也支持按表分别配置字段映射。为 None 时，不做显式字段映射，直接使用数据中的原字段名或字段标题进行写入匹配。
raise_error	bool	True	写入任一表失败时是否直接抛错。设为 False 时，会尽量继续写后续表，并通过 warning 提示失败信息。
strict_datetime_validation	bool	True	时间类字段校验策略。True：正则结合日期时间解析（较慢、更准确）；False：仅用正则（较快、略宽松）。
validation_level	"fast" | "full"	"full"	写入前的数据校验级别。fast 偏性能，full 偏完整性校验。
token	str | None	None	GDIM 用户 token。一般更推荐通过 pipeline.update_gdim_state(...) 统一设置。
proj_id	int | str | None	None	GDIM 项目 ID。若构造函数中显式设置，该值优先级高于 InputToken 或 pipeline.gdim_state.proj_id。
host	str | None	None	GDIM 平台地址；通常沿用 pipeline 中的 GDIM 状态即可。

上传 GDIM 前检查

• 是否需要特别处理：当 pipeline 要在 GDIM 平台中运行，并直接把结果写回项目表时，是。

• 必须检查：

  • 若目标是更新已有记录而非新增，必须确保写入数据里保留了 gdim_id；

• 建议检查：

  • 对日期时间类字段较多的数据，优先保持 strict_datetime_validation=True 和 validation_level="full"，先保证数据质量再考虑提速。

• 若遗漏，常见现象：

  • 看起来模块运行成功，但数据没有写入预期的 GDIM 表；

  • 原本希望覆盖旧记录，结果在表中新增了重复记录；

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）

MergeDocData

模块简介与适用场景

• MergeDocData 用于将多个 DocData 合并为一个 DocData （端口：OutputDocData）。

• 该模块使用 动态输入端口：你需要通过 add_dynamic_ports_in("InputXXX") 预先声明要合并的输入端口，然后在 pipeline 中将多个上游 DocDataWriter.OutputDocData 分别连到这些端口。

• 合并时若出现重复 key，会自动在后续重复项上追加 _1, _2 等后缀，并给出 warning，避免覆盖已有数据。

Hint

合并后的 DocData 同样可以通过 export_keys_to_json / export_data_to_json 导出查看（见 DocData：报告打印的数据容器（模板 keys 与渲染数据）），便于排查 “合并后 key 是否冲突 / 数据是否符合预期”。

端口说明

• 输入端口 - 动态输入端口：通过 add_dynamic_ports_in("InputXXX") 添加；每个动态端口的数据类型均为 DocData``（通常接 ``DocDataWriter.OutputDocData）

• 输出端口 - OutputDocData：输出合并后的文档数据（DocData）

快速上手示例：合并两份 DocData

from gdisdk.modules.writers import DocDataWriter, MergeDocData

doc_a = DocDataWriter("DocA")
doc_b = DocDataWriter("DocB")

merge_doc = MergeDocData("MergeDoc")
merge_doc.add_dynamic_ports_in("InputA")
merge_doc.add_dynamic_ports_in("InputB")

links = doc_a.OutputDocData >> merge_doc.InputA | doc_b.OutputDocData >> merge_doc.InputB

参数说明

MergeDocData 参数一览

参数名	类型	默认值	说明
all_ports_required	bool	True	为 True 时：只有当所有动态输入端口都有数据（不为 None）时才输出合并结果；任一端口为 None 则输出 None（常用于阻塞式等待所有分支完成）。

Hint

DocDataWriter 在输入数据 “为空但不为 None” （例如空表/空结果）时，会输出一个空的 DocData(data={}, doc_keys_struct={})，这通常有助于在 all_ports_required=True 时避免因为 “空数据” 而阻塞合并。

在 pipeline 中的使用方式

from gdisdk.pipeline import PipeLine
from gdisdk.modules.writers import DocDataWriter, MergeDocData, DocPrinter

pipeline = PipeLine(app_name="MergeDocDataDemo", app_title="合并文档数据示例")
pipeline.workspace = "test"

doc1 = DocDataWriter("Doc1")
doc2 = DocDataWriter("Doc2")

merge_doc = MergeDocData("MergeDoc")
merge_doc.add_dynamic_ports_in("InputDoc1")
merge_doc.add_dynamic_ports_in("InputDoc2")

printer = DocPrinter("PrintDoc")
printer.template = "test/template.docx"
printer.output_name = "merged.docx"

links = (
    doc1.OutputDocData >> merge_doc.InputDoc1
    | doc2.OutputDocData >> merge_doc.InputDoc2
    | merge_doc.OutputDocData >> printer.InputDocData
)
pipeline.add_links(links)
pipeline.run()

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）

DocPrinter

模块简介与适用场景

• DocPrinter 用于将 DocData 渲染为 .docx 文档（端口：OutputFile），常用于生成自动报告。

• 模板来源支持：

  • 本地文件路径（str | Path）；

  • GDIM文件服务器上的文件描述（dict，内部会下载到工作目录后再渲染）。

• 输出支持保存到本地或上传 GDIM 文件服务器（save_to_gdim=True）。

• 额外能力：

  • 按 doc_keys_struct 的 description 识别并处理 ImagePath / FilesPath / FilePath：模板中可插入图片或子文档；

  • 对图片可通过 image_size_type 与 image_size 控制缩放（单位：mm）。

端口说明

• 输入端口 - InputDocData：输入文档数据（DocData） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取

• 输出端口 - OutputFile：输出文件（本地保存时为 FilePath/FilesPath；上传 GDIM 时为 GdimFile/GdimFiles）

快速上手示例：打印 Word 报告

from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.writers import DocDataWriter, DocPrinter
from gdisdk.pipeline import PipeLine
from gdisdk.connectors import log_in

pipeline = PipeLine(app_name="GenerateDoc", app_title="生成报告示例")
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)
pipeline.workspace = "test"

read_table = GdimTableReader(mname="ReadTable")
read_table.table_fields = ["钻孔一览表"]

doc_data = DocDataWriter(mname="DocData")
doc_data.precision = 2

print_doc = DocPrinter(mname="PrintDoc")
print_doc.template = "test/钻孔一览表模板.docx"
print_doc.output_name = "钻孔一览表.docx"

links = (
    read_table.OutputTables >> doc_data.InputData
    | doc_data.OutputDocData >> print_doc.InputDocData
)
pipeline.add_links(links)
pipeline.run()

print(print_doc.OutputFile.data)

参数说明

DocPrinter 参数一览

参数名	类型	默认值	说明
template	str | Path | dict | list[str | Path | dict] | None	None	Word 模板（单个或多个）；为 None 时模块不执行并输出 None。
output_name	str | list[str] | None	None	输出文件名；为 None 时默认使用 {template_stem}_printed.docx。
output_dir	str | Path | None	None	输出目录；若 pipeline 设置了 workspace，则优先使用 workspace。
image_size_type	"width" | "height" | dict[str, "width" | "height"]	"width"	图片缩放按宽或按高；也可按 key 分别配置。
image_size	float | int | dict[str, float | int] | dict[str, list[float | int]] | None	None	图片大小（mm）；可统一、按 key 配置，或按 key 为 “图片列表” 逐张配置。
save_to_gdim	bool	False	是否将生成的文档上传到 GDIM 文件服务器；为 True 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

• 是否需要特别处理：当该模块的输出文件需要在 GDIM 中留存、回传或被后续流程消费时，是。

• 必须检查：

  • 将 save_to_gdim 设为 True，否则结果通常只会保存在本地路径；

  • 不要依赖模块里单独写死的运行时 GDIM 参数；

  • 模板建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。

• 建议检查：

  • output_name 设为清晰、稳定的文件名，便于结果识别；

  • 若仍保留本地模板路径写法，应明确这是本地调试用配置；上传时以前端传入的文件描述为准。

• 若遗漏，常见现象：

  • 本地运行能生成 .docx 文件，但上传 GDIM 后，拿不到期望的 GdimFile / GdimFiles 输出。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.writers import DocDataWriter, DocPrinter

pipe = PipeLine(app_name="DocPrinterDemo", app_title="打印 Word 示例")
# pipe.update_gdim_state(token="...", proj_id="...")
pipe.workspace = "test"

doc_data = DocDataWriter("DocData")
printer = DocPrinter("PrintDoc")
printer.template = "test/template.docx"
printer.output_name = "output.docx"
# printer.save_to_gdim = True

# links = doc_data.OutputDocData >> printer.InputDocData
# pipe.add_links(links)
# pipe.run()

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）

ExcelPrinter

模块简介与适用场景

• ExcelPrinter 用于将 DocData 渲染为 .xlsx 文档（端口：OutputFile），常用于 “按固定 Excel 模板导出业务表格/第三方格式（如 GEO5）”。

• 模板来源支持本地路径（str | Path）或 GDIM文件服务器上的文件描述（dict，内部会下载到工作目录后再渲染）。

• 输出支持保存到本地或上传 GDIM 文件服务器（save_to_gdim=True）。

端口说明

• 输入端口 - InputDocData：输入文档数据（DocData） - InputToken：鉴权与项目定位信息 (token, proj_id, host)；仅当 save_to_gdim=True 时需要；若未提供则从 pipeline.gdim_state.token / pipeline.gdim_state.proj_id / pipeline.gdim_state.host 获取

• 输出端口 - OutputFile：输出文件（本地保存时为 FilePath/FilesPath；上传 GDIM 时为 GdimFile/GdimFiles）

快速上手示例：按模板导出 Excel（GEO5 示例）

from gdisdk.modules.readers import GdimTableReader
from gdisdk.modules.widgets import PythonCoder
from gdisdk.modules.writers import DocDataWriter, ExcelPrinter
from gdisdk.pipeline import PipeLine
from gdisdk.connectors import log_in

pipeline = PipeLine(app_name="GenerateGeo5Tables", app_title="导出GEO5格式Excel")
pipeline.workspace = "test"
pipeline.update_gdim_state(
    token=log_in(user_name="你的GDIM用户名", password="你的GDIM密码"),
    proj_id="你的GDIM项目ID",
)
pipeline.local_functions_path = "pipelineImages/gdim/appDataExchange/GenerateGeo5Tables.py"

reader = GdimTableReader(mname="Reader")
reader.table_fields = ["bore_table", "layer_table"]

generate_geo5_tables = PythonCoder(mname="GenerateGeo5Tables")
generate_geo5_tables.add_dynamic_ports_in("InputTables")
generate_geo5_tables.add_dynamic_ports_out("OutputTables")
generate_geo5_tables.local_function_name = "GenerateGeo5Tables"

excel_writer = DocDataWriter(mname="ExcelWriter")

print_excel = ExcelPrinter(mname="PrintExcel")
print_excel.template = "test/GEO5三维地质建模模板.xlsx"
print_excel.output_name = "导出GEO5.xlsx"

links = (
    reader.OutputTables >> generate_geo5_tables.InputTables
    | generate_geo5_tables.OutputTables >> excel_writer.InputData
    | excel_writer.OutputDocData >> print_excel.InputDocData
)
pipeline.add_links(links)

result = pipeline.run()

参数说明

ExcelPrinter 参数一览

参数名	类型	默认值	说明
template	str | Path | dict | list[str | Path | dict] | None	None	Excel 模板（单个或多个）；为 None 时模块不执行并输出 None。
output_name	str | list[str] | None	None	输出文件名；为 None 时默认使用 {template_stem}_printed.xlsx。
process_sheets	str | list[str] | "active" | "all"	"all"	指定处理哪些 sheet："all" 处理全部；"active" 仅处理活动 sheet；也可指定 sheet 名或列表。
include_table_titles	bool	False	为 True 时会从 doc_keys_struct 自动生成表头；为 False 时假设模板中已包含表头。
apply_table_borders	bool	False	是否为表格区域应用外边框。
border_style	str	"thin"	边框样式（如 thin/medium/thick/double/dashed 等，具体取值依赖 Excel 边框样式集合）。
image_size_type	"width" | "height" | dict[str, "width" | "height"]	"width"	图片缩放按宽或按高；也可按 key 分别配置（保持纵横比）。
image_size	dict[str, float] | dict[str, list[float]] | None	None	图片大小（单位：mm）；可按 key 配置单张或多张图片的目标尺寸（保持纵横比）。
save_to_gdim	bool	False	是否上传到 GDIM 文件服务器；为 True 时需要可用的 token/proj_id/host（可从 pipeline 获取）。

上传 GDIM 前检查

• 是否需要特别处理：当导出的 Excel 文件需要在 GDIM 中留存、回传或交给后续环节下载时，是。

• 必须检查：

  • 将 save_to_gdim 设为 True，否则结果通常只会保存在本地路径；

  • 不要依赖模块里单独写死的运行时 GDIM 参数；

  • 模板建议通过 pipeline attribute + 前端传入的 GDIM 文件描述（``dict``） 提供，这是上传后的推荐方式。

• 建议检查：

  • output_name 设为稳定、可识别的导出文件名；

  • 若仍保留本地模板路径写法，应明确这是本地调试用配置；上传时以前端传入的文件描述为准。

  • 若使用 PythonCoder 等前置模块生成 DocData，一并确认这些模块本身也满足上传 GDIM 的脚本序列化要求。

• 若遗漏，常见现象：

  • 本地运行能生成 .xlsx 文件，但上传 GDIM 后，拿不到期望的 GdimFile / GdimFiles 输出。

更多信息

• API 参考 - modules 包

• 完整类定义与参数说明（writers）