📓接口参考

API 参考文档

strict_word_filler 引擎所有公开 API 详细说明

1. 模块索引

模块 文件 功能
pipeline strict_word_filler/pipeline.py CLI 参数解析与执行入口
loader strict_word_filler/loader.py JSON 解析与 BuildPlan 构建
docx_ops strict_word_filler/docx_ops.py Word 文档操作
models strict_word_filler/models.py 不可变数据模型
errors strict_word_filler/errors.py 异常类型定义

2. pipeline 模块

main

CLI 主入口。

1
def main(argv: list[str] | None = None) -> int

参数

参数 类型 说明
argv list[str] | None 命令行参数，默认使用 sys.argv

返回值

类型 说明
int 0 表示成功

CLI 参数

参数 说明 必需
--template Word 模板文件路径 是
--config config.json 文件路径 是
--project project.json 文件路径 是
--output 输出 .docx 文件路径 是

示例

1
2
3
4
5
python main.py \
  --template "[10][SRS] 软件需求规格说明-438C-2021.docx" \
  --config "config.json" \
  --project "project.json" \
  --output "output/SRS-filled.docx"

3. loader 模块

load_json

加载 JSON 文件。

1
def load_json(path: Path) -> dict

参数

参数 类型 说明
path Path JSON 文件路径

返回值

类型 说明
dict 解析后的字典

异常

异常 说明
FileNotFoundError 文件不存在
json.JSONDecodeError JSON 格式错误

build_plan

从配置数据构建不可变的 BuildPlan。

1
def build_plan(config_data: dict, project_data: dict) -> BuildPlan

参数

参数 类型 说明
config_data dict config.json 内容
project_data dict project.json 内容

返回值

类型 说明
BuildPlan 包含所有替换规则的不可变构建计划

异常

异常 说明
StrictDataError JSON 缺少必填字段或字段为空

说明

处理流程：

  1. 从 config_data 提取封面字段 → 生成 ExactReplaceRule
  2. 遍历 project_data["structure"] → 生成各章节 Rule
  3. 遇到 placeholders 中含 subsections 的动态章节 → DynamicSectionRule
  4. 遇到 tables → TableFillRule
  5. [11] 遇到 cscis → CSCISectionRule

4. docx_ops 模块

apply_plan

总入口，按顺序执行 BuildPlan 中所有规则。

1
def apply_plan(doc: DocumentObject, plan: BuildPlan) -> None

参数

参数 类型 说明
doc DocumentObject python-docx Document 对象
plan BuildPlan 构建计划

执行顺序

  1. exact_replacements — 精确替换
  2. dynamic_sections — 动态章节
  3. paragraph_replacements — 段落替换
  4. csci_sections — CSCI 章节（仅 [11]）
  5. tables — 表格填充
  6. 图表编号
  7. TOC 标记

apply_exact_replacement

精确匹配段落文本并替换。

1
2
3
4
def apply_exact_replacement(
    doc: DocumentObject, old_text: str, new_text: str,
    expected_matches: int, key: str
) -> None

参数

参数 类型 说明
doc DocumentObject 文档对象
old_text str 待替换的精确文本
new_text str 替换后文本
expected_matches int 期望命中的段落数量
key str 规则标识（用于错误信息）

异常

异常 说明
StrictTemplateError 命中数量不等于 expected_matches

apply_paragraph_replacement

包含匹配段落文本并替换，支持多行展开。

1
2
3
4
def apply_paragraph_replacement(
    doc: DocumentObject, anchor_text: str, new_text: str,
    expected_matches: int, key: str
) -> None

参数

参数 类型 说明
doc DocumentObject 文档对象
anchor_text str 锚点文本（包含匹配）
new_text str 替换后文本（支持 \n 分行）
expected_matches int 期望命中数量（默认 1）
key str 规则标识

apply_dynamic_section

克隆原型段落生成可变数量子章节。

1
def apply_dynamic_section(doc: DocumentObject, rule: DynamicSectionRule) -> None

说明

  1. 定位父标题、摘要段落、结束锚点、原型标题/正文段落
  2. 删除清理锚点之间的模板内容
  3. 为每个 DynamicSectionItem 克隆原型段落并设置标题和正文
  4. 按反向顺序删除被替换的模板段落

apply_csci_sections

[11] 专属。克隆整个 CSCI 原型块。

1
def apply_csci_sections(doc: DocumentObject, rule: CSCISectionRule) -> None

说明

  1. 定位 13 个锚点段落（原型标题、概述、部件、执行、接口等）
  2. 提取从原型标题到结束锚点之间的所有段落作为原型范围
  3. 删除原型范围
  4. 为每个 CSCISectionItem 克隆整个原型范围，逐段修改标题和内容

apply_table_fill

按 locator_rows 定位表格并填充数据。

1
def apply_table_fill(doc: DocumentObject, rule: TableFillRule) -> None

说明

  1. 遍历所有表格，匹配 locator_rows（头部行精确匹配）
  2. 若数据行不足，克隆最后一行数据行原型
  3. 逐行逐格写入内容
  4. [11] 版本额外清除多余数据行并处理合并单元格

apply_caption_numbering

自动编号图表标题。

1
def apply_caption_numbering(doc: DocumentObject) -> None

说明

匹配格式 表X-X / 图X-X 的占位符，按章号递增编号。正则：^(表|图)(\d+|X)-X(.*)$

mark_toc_for_update

设置 Word 文档的 updateFields 标记。

1
def mark_toc_for_update(doc: DocumentObject) -> None

遍历辅助函数

函数 签名 说明
iter_all_paragraphs (doc) -> Generator[Paragraph] 遍历所有段落（含页眉页脚、表格内嵌）
iter_body_non_toc_paragraphs (doc) -> Generator[Paragraph] 遍历正文段落，跳过 TOC 样式
iter_container_paragraphs (container) -> Generator[Paragraph] 遍历容器段落（递归处理表格）
find_single_body_paragraph (doc, text, *, exact) -> Paragraph 查找唯一匹配的正文段落
paragraph_index (doc, paragraph) -> int 获取段落在正文中的索引
set_paragraph_text (paragraph, text) -> None 保留首个 run 格式设置文本
set_paragraphs_from_text (paragraph, text) -> None 多行文本展开为新段落（克隆原型格式）
delete_paragraph (paragraph) -> None 删除段落 XML 节点

5. models 模块

通用模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@dataclass(frozen=True)
class ExactReplaceRule:
    key: str                    # 规则标识
    old_text: str               # 待替换的精确文本
    new_text: str               # 替换后文本
    expected_matches: int       # 期望命中数量

@dataclass(frozen=True)
class ParagraphReplaceRule:
    key: str
    anchor_text: str            # 锚点文本（包含匹配）
    new_text: str               # 替换后文本（支持多行）
    expected_matches: int = 1

@dataclass(frozen=True)
class DynamicSectionItem:
    section_id: str             # 子节编号（如 "3.2.1"）
    title: str                  # 子节标题
    body: str                   # 子节正文

@dataclass(frozen=True)
class DynamicSectionRule:
    parent_id: str
    parent_title: str
    summary_anchor: str
    end_before_title: str
    prototype_title_anchor: str
    prototype_body_anchor: str
    cleanup_anchors: tuple[str, ...]
    cleanup_to_end: bool
    items: tuple[DynamicSectionItem, ...]
    summary_text: str

@dataclass(frozen=True)
class TableFillRule:
    key: str
    locator_rows: tuple[tuple[str, ...], ...]   # 表头行文本
    columns: tuple[str, ...]                     # 列名
    rows: tuple[tuple[str, ...], ...]            # 数据行
    data_start_row: int                          # 数据起始行索引
    preserve_tail_rows: int                      # 保留的尾部行数

@dataclass(frozen=True)
class BuildPlan:
    exact_replacements: tuple[ExactReplaceRule, ...]
    paragraph_replacements: tuple[ParagraphReplaceRule, ...]
    dynamic_sections: tuple[DynamicSectionRule, ...]
    tables: tuple[TableFillRule, ...]

[11] 专属模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@dataclass(frozen=True)
class CSCISectionItem:
    section_id: str
    title: str
    overview: str
    component_title: str
    component_design: str
    execution_plan: str
    interface_overview: str
    interface_identification: str
    interface_detail_title: str
    interface_details: str

@dataclass(frozen=True)
class CSCISectionRule:
    key: str
    summary_anchor: str
    end_before_title: str
    prototype_title_anchor: str
    overview_heading_anchor: str
    component_section_heading_anchor: str
    component_item_heading_anchor: str
    component_body_anchor: str
    execution_heading_anchor: str
    execution_body_anchor: str
    interface_heading_anchor: str
    interface_id_heading_anchor: str
    interface_id_body_anchor: str
    interface_detail_heading_anchor: str
    interface_detail_body_anchor: str
    items: tuple[CSCISectionItem, ...]

# [11] BuildPlan 额外包含:
#   csci_sections: tuple[CSCISectionRule, ...]

6. errors 模块

1
2
3
4
5
class StrictTemplateError(RuntimeError):
    """模板结构与预期不匹配时抛出。"""

class StrictDataError(RuntimeError):
    """输入 JSON 数据不完整或非法时抛出。"""