word-template-engine 0.1.0__tar.gz

word_template_engine-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: word-template-engine
+Version: 0.1.0
+Summary: A Word template engine similar to docx-template, implemented with python-docx and lxml.
+Project-URL: Homepage, https://github.com/yourname/word-template-engine
+Project-URL: Repository, https://github.com/yourname/word-template-engine
+Author-email: Your Name <you@example.com>
+License: MIT
+Requires-Python: >=3.8
+Requires-Dist: lxml>=4.9.0
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# Word模板引擎
+
+一个类似于docx-template的Word模板引擎，使用Python直接解析Word文档的XML结构实现，**完全保留所有样式信息**。
+
+## 功能特性
+
+1. **字符串文本替换**: `{{data.diagnose}}` - 替换为对应的数据值（**不需要结束标签**）
+
+2. **表格行循环**: `{{#data.mutationSiteZero}}` - 在表格头部标记，根据数据循环生成表格行，使用`[field_name]`作为字段占位符（**不需要结束标签**）
+
+3. **表格列循环**: `{{$data.mutationSiteZero}}` - 在表格头部标记，根据数据循环生成表格列（**不需要结束标签**）
+
+4. **条件区块**: `{{?data.field != null && data.field.size() > 0}}...{{/}}` - 根据条件显示或隐藏内容块（**需要结束标签 {{/}}**）
+
+5. **图片插入**: `{{@var}}` - 插入图片，var格式: `{'url': '', 'conf': {'w': '180px', 'h': '180px'}}`（**不需要结束标签**）
+
+6. **列表循环**: `{{*data.conclusion_C}}` - 循环显示列表项（**不需要结束标签**）
+
+## 标签说明
+
+### 有结束标签的标签
+
+- **区块**: `{{?condition}}...{{/}}`
+  - 只有区块需要结束标签
+  - 支持嵌套
+  - 示例：
+    ```
+    {{?data.conclusion_C == ''}}无{{/}}
+    {{?data.conclusion_C != ''}}
+    {{*data.conclusion_C}}
+    {{/}}
+    ```
+
+### 不需要结束标签的标签
+
+- **文本替换**: `{{data.field}}`
+- **表格行循环**: `{{#data.field}}` - 后面直接跟字段如`[gene_transcript]`
+- **表格列循环**: `{{$data.field}}`
+- **图片**: `{{@var}}`
+- **列表**: `{{*data.field}}`
+
+## 安装
+
+使用pip安装依赖：
+
+```bash
+pip install wps_temp_engine
+```
+
+**注意**: 本引擎直接解析Word文档的XML结构，这样可以完整保留所有样式信息。
+
+## 使用方法
+
+### 1. 创建Word模板
+
+在Word文档中使用以下占位符：
+
+#### 文本替换
+- `{{data.diagnose}}`
+
+#### 表格行循环
+在表格行的单元格中写入 `{{#data.mutationSiteZero}}`，其他单元格使用方括号占位符：
+- `[gene_transcript]`
+- `[value]`
+- `[description]`
+
+#### 表格列循环
+在表格列的第一个单元格写入 `{{$data.mutationSiteZero}}`
+
+#### 条件区块
+```text
+{{?data.mutationSiteZero.size() > 0}}
+这部分内容只有在条件为真时才会显示
+{{/}}
+```
+
+支持的条件：
+- `size() > 0`
+
+#### 图片
+方式1: 使用变量名
+```
+{{@data.image_config}}
+```
+
+方式2: 直接写JSON
+```
+{{@{'url':'path/to/image.jpg','conf':{'w':'180px','h':'180px'}}}}
+```
+
+支持的尺寸单位: px, cm, in, mm
+
+#### 列表
+```
+{{*data.conclusion_C}}
+```
+
+### 2. 使用Python代码渲染
+
+```python
+from word_template_engine import WordTemplateEngine
+
+# 创建引擎实例
+engine = WordTemplateEngine('template.docx')
+
+# 准备数据
+data = {
+    'data': {
+        'diagnose': '诊断结果',
+        'mutationSiteZero': [
+            {'gene_transcript': 'Gene1', 'value': 'Value1', 'description': 'Desc1'},
+            {'gene_transcript': 'Gene2', 'value': 'Value2', 'description': 'Desc2'},
+        ],
+        'conclusion_C': ['结论1', '结论2', '结论3'],
+    }
+}
+
+# 渲染并保存
+engine.render(data, 'output.docx')
+```
+
+## 详细说明
+
+### 1. 字符串文本替换
+
+模板中写入: `{{data.diagnose}}`
+
+数据中提供: `{'data': {'diagnose': '测试结果'}}`
+
+结果: 替换为 "测试结果"
+
+### 2. 表格行循环
+
+在表格的某一行的单元格中写入 `{{#data.mutationSiteZero}}`，该行将成为模板行。
+
+其他单元格使用方括号占位符，如 `[gene_transcript]`、`[value]`。
+
+根据 `data.mutationSiteZero` 数组的长度，会自动生成对应数量的表格行。
+
+**注意**: 表格行循环**不需要结束标签**，循环标记后直接跟字段占位符。
+
+### 3. 表格列循环
+
+在表格某一列的单元格中写入 `{{$data.mutationSiteZero}}`，该列将成为模板列。
+
+根据数据数组长度，会自动为所有行添加新列。
+
+### 4. 条件区块
+
+支持条件判断，**需要结束标签**：
+
+```text
+{{?data.conclusion_C == ''}}无{{/}}
+{{?data.conclusion_C != ''}}
+{{*data.conclusion_C}}
+{{/}}
+```
+
+支持的操作符：
+- `!= null` / `== null`
+- `== ''` / `!= ''`  （检查空字符串）
+- `size() > 0`
+- `&&` (AND)
+- `||` (OR)
+
+支持嵌套区块。
+
+### 5. 图片插入
+
+两种方式：
+
+方式1: 使用变量名
+```
+{{@data.image_config}}
+```
+其中 `data.image_config` 是字典格式的配置。
+
+方式2: 直接写JSON
+```
+{{@{'url':'https://example.com/image.jpg','conf':{'w':'180px','h':'180px'}}}}
+```
+
+支持的尺寸单位: px, cm, in, mm
+
+图片可以是HTTP/HTTPS链接或本地文件路径。
+
+### 6. 列表循环
+
+模板中写入: `{{*data.conclusion_C}}`
+
+数据中提供: `{'data': {'conclusion_C': ['项目1', '项目2', '项目3']}}`
+
+结果: 展开为多行文本，每行一个项目
+
+## 处理顺序
+
+引擎按以下顺序处理模板：
+
+1. **区块** - 先处理条件区块（因为它有结束标签，可能包含其他标签）
+2. **列表** - 处理列表循环
+3. **文本** - 处理文本占位符
+4. **图片** - 处理图片占位符
+5. **表格** - 最后处理表格（行循环和列循环）
+
+## 项目结构
+
+```
+.
+├── pyproject.toml           # 项目配置
+├── word_template_engine.py  # 主引擎类（XML版本）
+├── example.py               # 使用示例
+├── README.md                # 详细文档
+├── template.docx            # 模板文件
+└── utils/                   # 工具模块
+    ├── __init__.py
+    ├── xml_processor.py     # XML处理工具
+    ├── text_processor.py    # 文本处理
+    ├── table_processor.py   # 表格处理（保留兼容）
+    ├── block_processor.py   # 区块处理
+    ├── image_processor.py   # 图片处理
+    └── list_processor.py    # 列表处理
+```
+
+## 技术实现
+
+本引擎直接解析Word文档的XML结构（.docx文件实际上是一个ZIP压缩包，包含XML文件），这样可以：
+
+- **完全保留样式信息**：所有格式、字体、颜色、对齐等样式都会保留
+- **精确控制**：直接操作XML节点，可以精确处理复杂的文档结构
+- **高性能**：无需通过中间库转换，直接操作XML
+
+主要处理流程：
+1. 解压.docx文件（ZIP格式）
+2. 解析 `word/document.xml` 主文档
+3. 在XML层面进行占位符替换和循环处理
+4. 重新打包为.docx文件
+
+## 注意事项
+
+1. 模板文件必须是有效的.docx格式
+2. 表格行循环标记需要放在表格的单元格中
+3. 表格行循环**不需要结束标签**，直接在标记后使用`[field]`占位符
+4. 只有**区块**需要结束标签 `{{/}}`
+5. 图片URL可以是HTTP/HTTPS链接或本地文件路径（图片功能在XML版本中暂未完整实现）
+6. 条件表达式支持基本的逻辑运算
+7. 嵌套的字段访问使用点号，如 `data.sub_field.value`
+8. 支持嵌套的条件区块
+9. **所有样式都会完整保留**，包括字体、颜色、大小、对齐等，这是使用XML解析的最大优势

word_template_engine-0.1.0/README.md

@@ -0,0 +1,248 @@
+# Word模板引擎
+
+一个类似于docx-template的Word模板引擎，使用Python直接解析Word文档的XML结构实现，**完全保留所有样式信息**。
+
+## 功能特性
+
+1. **字符串文本替换**: `{{data.diagnose}}` - 替换为对应的数据值（**不需要结束标签**）
+
+2. **表格行循环**: `{{#data.mutationSiteZero}}` - 在表格头部标记，根据数据循环生成表格行，使用`[field_name]`作为字段占位符（**不需要结束标签**）
+
+3. **表格列循环**: `{{$data.mutationSiteZero}}` - 在表格头部标记，根据数据循环生成表格列（**不需要结束标签**）
+
+4. **条件区块**: `{{?data.field != null && data.field.size() > 0}}...{{/}}` - 根据条件显示或隐藏内容块（**需要结束标签 {{/}}**）
+
+5. **图片插入**: `{{@var}}` - 插入图片，var格式: `{'url': '', 'conf': {'w': '180px', 'h': '180px'}}`（**不需要结束标签**）
+
+6. **列表循环**: `{{*data.conclusion_C}}` - 循环显示列表项（**不需要结束标签**）
+
+## 标签说明
+
+### 有结束标签的标签
+
+- **区块**: `{{?condition}}...{{/}}`
+  - 只有区块需要结束标签
+  - 支持嵌套
+  - 示例：
+    ```
+    {{?data.conclusion_C == ''}}无{{/}}
+    {{?data.conclusion_C != ''}}
+    {{*data.conclusion_C}}
+    {{/}}
+    ```
+
+### 不需要结束标签的标签
+
+- **文本替换**: `{{data.field}}`
+- **表格行循环**: `{{#data.field}}` - 后面直接跟字段如`[gene_transcript]`
+- **表格列循环**: `{{$data.field}}`
+- **图片**: `{{@var}}`
+- **列表**: `{{*data.field}}`
+
+## 安装
+
+使用pip安装依赖：
+
+```bash
+pip install wps_temp_engine
+```
+
+**注意**: 本引擎直接解析Word文档的XML结构，这样可以完整保留所有样式信息。
+
+## 使用方法
+
+### 1. 创建Word模板
+
+在Word文档中使用以下占位符：
+
+#### 文本替换
+- `{{data.diagnose}}`
+
+#### 表格行循环
+在表格行的单元格中写入 `{{#data.mutationSiteZero}}`，其他单元格使用方括号占位符：
+- `[gene_transcript]`
+- `[value]`
+- `[description]`
+
+#### 表格列循环
+在表格列的第一个单元格写入 `{{$data.mutationSiteZero}}`
+
+#### 条件区块
+```text
+{{?data.mutationSiteZero.size() > 0}}
+这部分内容只有在条件为真时才会显示
+{{/}}
+```
+
+支持的条件：
+- `size() > 0`
+
+#### 图片
+方式1: 使用变量名
+```
+{{@data.image_config}}
+```
+
+方式2: 直接写JSON
+```
+{{@{'url':'path/to/image.jpg','conf':{'w':'180px','h':'180px'}}}}
+```
+
+支持的尺寸单位: px, cm, in, mm
+
+#### 列表
+```
+{{*data.conclusion_C}}
+```
+
+### 2. 使用Python代码渲染
+
+```python
+from word_template_engine import WordTemplateEngine
+
+# 创建引擎实例
+engine = WordTemplateEngine('template.docx')
+
+# 准备数据
+data = {
+    'data': {
+        'diagnose': '诊断结果',
+        'mutationSiteZero': [
+            {'gene_transcript': 'Gene1', 'value': 'Value1', 'description': 'Desc1'},
+            {'gene_transcript': 'Gene2', 'value': 'Value2', 'description': 'Desc2'},
+        ],
+        'conclusion_C': ['结论1', '结论2', '结论3'],
+    }
+}
+
+# 渲染并保存
+engine.render(data, 'output.docx')
+```
+
+## 详细说明
+
+### 1. 字符串文本替换
+
+模板中写入: `{{data.diagnose}}`
+
+数据中提供: `{'data': {'diagnose': '测试结果'}}`
+
+结果: 替换为 "测试结果"
+
+### 2. 表格行循环
+
+在表格的某一行的单元格中写入 `{{#data.mutationSiteZero}}`，该行将成为模板行。
+
+其他单元格使用方括号占位符，如 `[gene_transcript]`、`[value]`。
+
+根据 `data.mutationSiteZero` 数组的长度，会自动生成对应数量的表格行。
+
+**注意**: 表格行循环**不需要结束标签**，循环标记后直接跟字段占位符。
+
+### 3. 表格列循环
+
+在表格某一列的单元格中写入 `{{$data.mutationSiteZero}}`，该列将成为模板列。
+
+根据数据数组长度，会自动为所有行添加新列。
+
+### 4. 条件区块
+
+支持条件判断，**需要结束标签**：
+
+```text
+{{?data.conclusion_C == ''}}无{{/}}
+{{?data.conclusion_C != ''}}
+{{*data.conclusion_C}}
+{{/}}
+```
+
+支持的操作符：
+- `!= null` / `== null`
+- `== ''` / `!= ''`  （检查空字符串）
+- `size() > 0`
+- `&&` (AND)
+- `||` (OR)
+
+支持嵌套区块。
+
+### 5. 图片插入
+
+两种方式：
+
+方式1: 使用变量名
+```
+{{@data.image_config}}
+```
+其中 `data.image_config` 是字典格式的配置。
+
+方式2: 直接写JSON
+```
+{{@{'url':'https://example.com/image.jpg','conf':{'w':'180px','h':'180px'}}}}
+```
+
+支持的尺寸单位: px, cm, in, mm
+
+图片可以是HTTP/HTTPS链接或本地文件路径。
+
+### 6. 列表循环
+
+模板中写入: `{{*data.conclusion_C}}`
+
+数据中提供: `{'data': {'conclusion_C': ['项目1', '项目2', '项目3']}}`
+
+结果: 展开为多行文本，每行一个项目
+
+## 处理顺序
+
+引擎按以下顺序处理模板：
+
+1. **区块** - 先处理条件区块（因为它有结束标签，可能包含其他标签）
+2. **列表** - 处理列表循环
+3. **文本** - 处理文本占位符
+4. **图片** - 处理图片占位符
+5. **表格** - 最后处理表格（行循环和列循环）
+
+## 项目结构
+
+```
+.
+├── pyproject.toml           # 项目配置
+├── word_template_engine.py  # 主引擎类（XML版本）
+├── example.py               # 使用示例
+├── README.md                # 详细文档
+├── template.docx            # 模板文件
+└── utils/                   # 工具模块
+    ├── __init__.py
+    ├── xml_processor.py     # XML处理工具
+    ├── text_processor.py    # 文本处理
+    ├── table_processor.py   # 表格处理（保留兼容）
+    ├── block_processor.py   # 区块处理
+    ├── image_processor.py   # 图片处理
+    └── list_processor.py    # 列表处理
+```
+
+## 技术实现
+
+本引擎直接解析Word文档的XML结构（.docx文件实际上是一个ZIP压缩包，包含XML文件），这样可以：
+
+- **完全保留样式信息**：所有格式、字体、颜色、对齐等样式都会保留
+- **精确控制**：直接操作XML节点，可以精确处理复杂的文档结构
+- **高性能**：无需通过中间库转换，直接操作XML
+
+主要处理流程：
+1. 解压.docx文件（ZIP格式）
+2. 解析 `word/document.xml` 主文档
+3. 在XML层面进行占位符替换和循环处理
+4. 重新打包为.docx文件
+
+## 注意事项
+
+1. 模板文件必须是有效的.docx格式
+2. 表格行循环标记需要放在表格的单元格中
+3. 表格行循环**不需要结束标签**，直接在标记后使用`[field]`占位符
+4. 只有**区块**需要结束标签 `{{/}}`
+5. 图片URL可以是HTTP/HTTPS链接或本地文件路径（图片功能在XML版本中暂未完整实现）
+6. 条件表达式支持基本的逻辑运算
+7. 嵌套的字段访问使用点号，如 `data.sub_field.value`
+8. 支持嵌套的条件区块
+9. **所有样式都会完整保留**，包括字体、颜色、大小、对齐等，这是使用XML解析的最大优势

word_template_engine-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "word-template-engine"
+version = "0.1.0"
+description = "A Word template engine similar to docx-template, implemented with python-docx and lxml."
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    { name = "Your Name", email = "you@example.com" },
+]
+license = { text = "MIT" }
+dependencies = [
+    "requests>=2.28.0",
+    "python-docx>=1.1.0",
+    "lxml>=4.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourname/word-template-engine"
+Repository = "https://github.com/yourname/word-template-engine"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["word_template_engine.py", "utils", "README.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+

word_template_engine-0.1.0/utils/__init__.py

@@ -0,0 +1,16 @@
+"""
+Utils package for word-template-engine.
+
+This package contains the internal processors used by `WordTemplateEngine`:
+- text_processor: text and block placeholders
+- table_processor: table loops
+- image_processor: image placeholders
+"""
+
+__all__ = [
+    "text_processor",
+    "table_processor",
+    "image_processor",
+    "block_processor",
+    "list_processor",
+]

word_template_engine-0.1.0/utils/common.py

@@ -0,0 +1,153 @@
+"""
+Common utilities: nested value lookup and condition evaluation.
+"""
+import re
+import ast
+import copy
+from typing import Any, Dict
+
+
+def get_nested_value(data: Dict[str, Any], path: str) -> Any:
+    """Get nested value from dict/list using dot path."""
+    if not path:
+        return None
+    copy_data = copy.deepcopy(data)
+    # dot_data = DotDict(data)
+    keys = path.split('.')
+    if not keys:
+        return copy_data[keys]
+    for i in range(len(keys)):
+        copy_data = copy_data.get(keys[i])
+
+    # value = dot_data.get_path(path)
+    # keys = path.split(".")
+    # value: Any = data
+    # for key in keys:
+    #     if isinstance(value, dict):
+    #         value = value.get(key)
+    #     elif isinstance(value, list) and key.isdigit():
+    #         idx = int(key)
+    #         value = value[idx] if idx < len(value) else None
+    #     else:
+    #         return None
+    #     if value is None:
+    #         return None
+    return copy_data
+
+
+def _value_len(val: Any) -> int:
+    if hasattr(val, "__len__"):
+        try:
+            return len(val)  # type: ignore[arg-type]
+        except Exception:
+            return 0
+    return 0
+
+def safe_eval(expr, variables=None):
+    if variables is None:
+        variables = {}
+    
+    # 检查AST是否包含危险节点（如函数调用、属性访问）
+    tree = ast.parse(expr, mode='eval')
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Call, ast.Attribute)):
+            raise ValueError("Unsafe expression")
+    
+    # 编译并执行
+    code = compile(tree, '<string>', 'eval')
+    return eval(code, {'__builtins__': {}}, variables)
+
+def evaluate_condition(condition: str, data: Dict[str, Any]) -> bool:
+    """
+    Evaluate simple condition expressions used in templates.
+
+    Supported:
+    - == null / != null
+    - == '' / != ''
+    - size() > 0
+    - && / ||
+    - truthy check of a field
+    """
+    condition = condition.strip()
+    if not condition:
+        return False
+
+    # Logical AND / OR
+    if "&&" in condition:
+        return all(evaluate_condition(part, data) for part in condition.split("&&"))
+    if "||" in condition:
+        return any(evaluate_condition(part, data) for part in condition.split("||"))
+
+    # size() > 0
+    size_match = re.match(r"(.+)\.size(.*?)$", condition)
+    if size_match:
+        field = size_match.group(1).strip()
+        field2 = size_match.group(2).strip()
+        val = get_nested_value(data, field)
+        return safe_eval(f"{_value_len(val)}{field2}") 
+
+    # == '' / != ''
+    empty_eq = re.match(r"(.+)==\s*['\"]\s*['\"]", condition)
+    if empty_eq:
+        field = empty_eq.group(1).strip()
+        val = get_nested_value(data, field)
+        return val == "" or val is None
+
+    empty_neq = re.match(r"(.+)!=\s*['\"]\s*['\"]", condition)
+    if empty_neq:
+        field = empty_neq.group(1).strip()
+        val = get_nested_value(data, field)
+        return val not in ("", None)
+
+    # == null / != null
+    null_eq = re.match(r"(.+)==\s*null", condition, re.IGNORECASE)
+    if null_eq:
+        field = null_eq.group(1).strip()
+        val = get_nested_value(data, field)
+        return val is None
+
+    null_neq = re.match(r"(.+)!=( )?null", condition, re.IGNORECASE)
+    if null_neq:
+        field = null_neq.group(1).strip()
+        val = get_nested_value(data, field)
+        return val is not None
+
+    # Direct truthy check
+    val = get_nested_value(data, condition)
+    return bool(val)
+
+
+def process_block(text: str, data: Dict[str, Any]) -> str:
+    """
+    Process conditional blocks {{?condition}}...{{/}}.
+    Removes blocks when condition is False; strips tags when True.
+    """
+    start_pat = r"\{\{\?([^}]+)\}\}"
+    end_pat = r"\{\{/\}\}"
+
+    def find_blocks(s: str):
+        starts = list(re.finditer(start_pat, s))
+        ends = list(re.finditer(end_pat, s))
+        return starts, ends
+
+    result = text
+    while True:
+        starts, ends = find_blocks(result)
+        if not starts or not ends:
+            break
+        # pair first start with nearest end after it (no deep nesting handling)
+        start = starts[0]
+        end_candidates = [e for e in ends if e.start() > start.end()]
+        if not end_candidates:
+            break
+        end = end_candidates[0]
+        inner = result[start.end(): end.start()]
+        cond = start.group(1).strip()
+        if evaluate_condition(cond, data):
+            # keep inner, drop tags
+            replacement = inner
+        else:
+            replacement = ""
+        result = result[: start.start()] + replacement + result[end.end():]
+    return result
+

word_template_engine-0.1.0/utils/image_processor.py

@@ -0,0 +1,98 @@
+"""
+Image placeholder processing: {{@var}}
+"""
+import os
+import re
+from typing import Any, Dict
+from io import BytesIO
+import requests
+from docx.shared import Inches, Cm
+from docx.text.paragraph import Paragraph
+
+from .common import get_nested_value
+
+
+IMAGE_PATTERN = re.compile(r"\{\{@([\s\S]+?)\}\}", re.DOTALL)
+
+
+def _parse_size(value: str):
+    """Parse size string into a python-docx length (Inches/Cm)."""
+    if not value:
+        return None
+    value = value.lower().strip()
+    if value.endswith("px"):
+        num = float(value[:-2])
+        return Inches(num / 96.0)  # assume 96 DPI
+    if value.endswith("cm"):
+        num = float(value[:-2])
+        return Cm(num)
+    if value.endswith("mm"):
+        num = float(value[:-2])
+        return Cm(num / 10.0)
+    if value.endswith("in") or value.endswith("inch"):
+        num = float(value[:-2]) if value.endswith("in") else float(value[:-4])
+        return Inches(num)
+    # no unit: treat as inches
+    try:
+        num = float(value)
+        return Inches(num)
+    except Exception:
+        return None
+
+
+def _fetch_image(url: str) -> BytesIO:
+    if url.startswith("http://") or url.startswith("https://"):
+        resp = requests.get(url, timeout=10)
+        resp.raise_for_status()
+        return BytesIO(resp.content)
+    with open(url, "rb") as f:
+        return BytesIO(f.read())
+
+
+def process_paragraph_images(paragraph: Paragraph, data: Dict[str, Any]) -> None:
+    """Replace {{@var}} with image, tolerant of line breaks across runs, and append image name."""
+    full_text = "".join(run.text or "" for run in paragraph.runs)
+    if not full_text:
+        return
+    matches = list(IMAGE_PATTERN.finditer(full_text))
+    if not matches:
+        return
+
+    cleaned_text = full_text
+    image_configs = []
+
+    for match in matches:
+        placeholder = match.group(0)
+        raw_path = match.group(1)
+        var_path = "".join(raw_path.split())
+        cfg = get_nested_value(data, var_path)
+        image_configs.append((placeholder, cfg))
+
+    # Remove placeholders from text first (to keep layout consistent)
+    for placeholder, cfg in image_configs:
+        cleaned_text = cleaned_text.replace(placeholder, "", 1)
+
+    # Rewrite paragraph text without placeholders
+    for run in paragraph.runs:
+        run.text = ""
+    if paragraph.runs:
+        paragraph.runs[0].text = cleaned_text
+    else:
+        paragraph.add_run(cleaned_text)
+
+    # Append images (and their file names) at the end in order of appearance
+    for placeholder, cfg in image_configs:
+        if not isinstance(cfg, dict):
+            continue
+        url = cfg.get("url", "")
+        conf = cfg.get("conf", {}) or {}
+        width = _parse_size(conf.get("w", "12cm"))
+        height = _parse_size(conf.get("h", "8cm"))
+        try:
+            img_stream = _fetch_image(url)
+            pic_run = paragraph.add_run()
+            pic_run.add_picture(img_stream, width=width, height=height)
+            # append image file name after picture
+        except Exception as exc:
+            error_run = paragraph.add_run(f"[Image Error: {exc}]")
+

word_template_engine-0.1.0/utils/table_processor.py

@@ -0,0 +1,217 @@
+"""
+Table row loop processing.
+"""
+import re
+import copy
+import re
+from typing import Any, Dict, List
+from docx.table import _Row, Table
+
+from .common import get_nested_value
+from .text_processor import render_text
+
+
+def _rewrite_paragraph_text(paragraph, new_text: str) -> None:
+    """Rewrite paragraph runs sequentially to preserve styles as much as possible."""
+    runs = paragraph.runs
+    remaining = new_text
+    for run in runs:
+        if not remaining:
+            run.text = ""
+            continue
+        run_len = len(run.text or "")
+        if run_len == 0:
+            run.text = remaining
+            remaining = ""
+        else:
+            run.text = remaining[:run_len]
+            remaining = remaining[run_len:]
+    if remaining and runs:
+        # append to last run
+        runs[-1].text = (runs[-1].text or "") + remaining
+
+
+def _strip_loop_marker_in_cell(cell) -> None:
+    """Remove {{#...}} marker from a cell while keeping existing run styles (handles split runs)."""
+    pattern = re.compile(r"\{\{#([^}]+)\}\}")
+    for p in cell.paragraphs:
+        full_text = "".join(r.text or "" for r in p.runs)
+        new_text = pattern.sub("", full_text)
+        if new_text != full_text:
+            _rewrite_paragraph_text(p, new_text)
+
+
+def _clone_row(table: Table, row_idx: int):
+    """Clone a row preserving styling."""
+    template_row = table.rows[row_idx]
+    new_row = template_row._element.clone()
+    table._tbl.insert(row_idx + 1, new_row)
+    return table.rows[row_idx + 1]
+
+
+def process_table(table: Table, data: Dict[str, Any]) -> None:
+    """
+    表格行循环处理：
+    1. 表头：{{#mydata}} - 遍历 input_data['mydata']
+       - 如果 mydata 是 list: input_data['mydata'] = [{...}, {...}]
+       - 如果 mydata 是 dict: input_data['mydata'] = {'data1': [...], 'data2': [...]}
+    
+    2. 表体行：
+       - 如果第一个单元格有 {{+data1}}[name]，第二列是 [age]，找到这行中的 {{/data1}}
+         数据来源：input_data['mydata']['data1'] = [{name:1, age:2}, ...]
+       - 如果第一个单元格没有 {{+}}，数据来源：input_data['mydata'] = [{name:1, age:2}, ...]
+    """
+    rows = list(table.rows)
+    if not rows:
+        return
+
+    # 1) 解析表头 {{#mydata}}
+    loop_match = None
+    for cell in rows[0].cells:
+        m = re.search(r"\{\{#([^}]+)\}\}", cell.text)
+        if m:
+            loop_match = m
+            break
+    if not loop_match:
+        return
+
+    field_path = loop_match.group(1).strip()
+    main_obj = get_nested_value(data, field_path)
+
+    # 去掉表头标记
+    for cell in rows[0].cells:
+        _strip_loop_marker_in_cell(cell)
+
+    # 2) 处理表体行：扫描每一行，识别是否有 {{+xxx}}...{{/xxx}}
+    nested_start_pat = re.compile(r"\{\{\+([^}]+)\}\}")
+    nested_end_pat = re.compile(r"\{\{/([^}]+)\}\}")
+
+    # 保存每行的模板和嵌套字段信息
+    body_templates: List[tuple[Any, str | None]] = []
+    for i in range(1, len(rows)):
+        row = rows[i]
+        first_cell_text = row.cells[0].text if row.cells else ""
+        nested_match = nested_start_pat.search(first_cell_text)
+        nested_field = nested_match.group(1).strip() if nested_match else None
+        body_templates.append((copy.deepcopy(row._element), nested_field))
+
+    # 3) 删除所有表体行
+    while len(table.rows) > 1:
+        table._tbl.remove(table.rows[1]._tr)
+
+    # 4) 处理 main_obj：可能是 list 或 dict
+    if isinstance(main_obj, dict):
+        # detectionResult 这种情况：{'data1': [...], 'data2': [...]}
+        # 遍历每一行模板，根据 {{+xxx}} 从 main_obj 中获取对应的数据列表
+        for template_el, nested_field in body_templates:
+            if nested_field:
+                # 这行有 {{+nested_field}}，从 main_obj[nested_field] 获取数据
+                nested_items = main_obj.get(nested_field)
+                if not isinstance(nested_items, list):
+                    nested_items = []
+                
+                for nested_item in nested_items:
+                    new_el = copy.deepcopy(template_el)
+                    table._tbl.append(new_el)
+                    new_row = table.rows[-1]
+                    
+                    for cell in new_row.cells:
+                        cell_text = cell.text
+                        # 移除 {{+nested_field}} 和 {{/nested_field}} 标记
+                        escaped = re.escape(nested_field)
+                        cell_text = re.sub(rf"{{{{\+{escaped}}}}}", "", cell_text)
+                        cell_text = re.sub(rf"{{{{/{escaped}}}}}", "", cell_text)
+                        
+                        # 替换 [field] 占位符
+                        if isinstance(nested_item, dict):
+                            for k, v in nested_item.items():
+                                placeholder = f"[{k}]"
+                                cell_text = cell_text.replace(placeholder, "" if v is None else str(v))
+                        
+                        cell_text = render_text(cell_text, data)
+                        
+                        # 更新单元格文本
+                        for p in cell.paragraphs:
+                            for r in p.runs:
+                                r.text = ""
+                            if p.runs:
+                                p.runs[0].text = cell_text
+                            else:
+                                p.add_run(cell_text)
+            else:
+                # 没有 {{+}} 的行，跳过（因为 main_obj 是 dict，没有直接数据）
+                pass
+    elif isinstance(main_obj, list):
+        # 普通 list 情况：input_data['mydata'] = [{...}, {...}]
+        for main_item in main_obj:
+            for template_el, nested_field in body_templates:
+                if nested_field:
+                    # 嵌套循环：从 main_item[nested_field] 获取数据
+                    nested_items = main_item.get(nested_field) if isinstance(main_item, dict) else None
+                    if not isinstance(nested_items, list):
+                        nested_items = []
+                    
+                    for nested_item in nested_items:
+                        new_el = copy.deepcopy(template_el)
+                        table._tbl.append(new_el)
+                        new_row = table.rows[-1]
+                        
+                        for cell in new_row.cells:
+                            cell_text = cell.text
+                            # 移除 {{+nested_field}} 和 {{/nested_field}} 标记
+                            escaped = re.escape(nested_field)
+                            cell_text = re.sub(rf"{{{{\+{escaped}}}}}", "", cell_text)
+                            cell_text = re.sub(rf"{{{{/{escaped}}}}}", "", cell_text)
+                            
+                            # 替换 [field] 占位符（优先使用 nested_item）
+                            if isinstance(nested_item, dict):
+                                for k, v in nested_item.items():
+                                    placeholder = f"[{k}]"
+                                    cell_text = cell_text.replace(placeholder, "" if v is None else str(v))
+                            
+                            # 如果 nested_item 中没有，尝试从 main_item 获取
+                            if isinstance(main_item, dict):
+                                for k, v in main_item.items():
+                                    placeholder = f"[{k}]"
+                                    if placeholder in cell_text:
+                                        cell_text = cell_text.replace(placeholder, "" if v is None else str(v))
+                            
+                            cell_text = render_text(cell_text, data)
+                            
+                            # 更新单元格文本
+                            for p in cell.paragraphs:
+                                for r in p.runs:
+                                    r.text = ""
+                                if p.runs:
+                                    p.runs[0].text = cell_text
+                                else:
+                                    p.add_run(cell_text)
+                else:
+                    # 没有 {{+}} 的行，直接使用 main_item
+                    new_el = copy.deepcopy(template_el)
+                    table._tbl.append(new_el)
+                    new_row = table.rows[-1]
+                    
+                    for cell in new_row.cells:
+                        cell_text = cell.text
+                        
+                        # 替换 [field] 占位符
+                        if isinstance(main_item, dict):
+                            for k, v in main_item.items():
+                                placeholder = f"[{k}]"
+                                cell_text = cell_text.replace(placeholder, "" if v is None else str(v))
+                        
+                        cell_text = render_text(cell_text, data)
+                        
+                        # 更新单元格文本
+                        for p in cell.paragraphs:
+                            for r in p.runs:
+                                r.text = ""
+                            if p.runs:
+                                p.runs[0].text = cell_text
+                            else:
+                                p.add_run(cell_text)
+    else:
+        # main_obj 既不是 list 也不是 dict，删除所有表体行
+        pass
+

word_template_engine-0.1.0/utils/text_processor.py

@@ -0,0 +1,216 @@
+"""
+Text placeholder processing.
+"""
+import re
+from copy import deepcopy
+from typing import Any, Dict, List
+from docx.text.paragraph import Paragraph
+
+from .common import get_nested_value, process_block, evaluate_condition
+
+
+PLACEHOLDER_PATTERN = re.compile(r"\{\{([^@#?/$*}]+)\}\}")
+
+
+def _rewrite_paragraph_text(paragraph: Paragraph, new_text: str) -> None:
+    """Rewrite text into existing runs to preserve styles as much as possible."""
+    runs = paragraph.runs
+    remaining = new_text
+    for run in runs:
+        orig_len = len(run.text or "")
+        if not remaining:
+            run.text = ""
+            continue
+        if orig_len > 0:
+            run.text = remaining[:orig_len]
+            remaining = remaining[orig_len:]
+        else:
+            run.text = ""
+    if remaining:
+        # append using last run's style if available
+        base = runs[-1] if runs else paragraph.add_run()
+        new_run = paragraph.add_run(remaining)
+        if runs:
+            new_run.style = base.style
+            new_run.bold = base.bold
+            new_run.italic = base.italic
+            new_run.underline = base.underline
+            new_run.font.size = base.font.size
+            new_run.font.color.rgb = base.font.color.rgb
+            new_run.font.name = base.font.name
+    # ensure no None texts
+    for run in runs:
+        if run.text is None:
+            run.text = ""
+
+
+def _paragraph_text(paragraph: Paragraph) -> str:
+    return "".join(run.text or "" for run in paragraph.runs)
+
+
+def _replace_bracket_placeholders(text: str, item: Any) -> str:
+    if isinstance(item, dict):
+        for k, v in item.items():
+            text = text.replace(f"[{k}]", "" if v is None else str(v))
+    else:
+        text = re.sub(r"\[text\]", "" if item is None else str(item), text)
+    return text
+
+
+def process_paragraph_loops(paragraphs: List[Paragraph], data: Dict[str, Any]) -> None:
+    """
+    Handle non-table loops:
+    {{#data.list}}
+    [field] ...
+    If marker paragraph has no [ ], use the next paragraph with [ ] as template.
+    """
+    loop_pat = re.compile(r"\{\{#([^}]+)\}\}")
+    bracket_pat = re.compile(r"\[[^\]]+\]")
+    idx = 0
+    while idx < len(paragraphs):
+        para = paragraphs[idx]
+        full_text = _paragraph_text(para)
+        m = loop_pat.search(full_text)
+        if not m:
+            idx += 1
+            continue
+        field_path = m.group(1).strip()
+        items = get_nested_value(data, field_path)
+        parent = para._element.getparent()
+
+        # choose template: marker line if it contains [ ], else next line with [ ]
+        template_el = para._element
+        template_idx = idx
+        if not bracket_pat.search(full_text):
+            look = idx + 1
+            while look < len(paragraphs):
+                cand_text = _paragraph_text(paragraphs[look])
+                if bracket_pat.search(cand_text):
+                    template_el = paragraphs[look]._element
+                    template_idx = look
+                    break
+                if loop_pat.search(cand_text):
+                    break
+                look += 1
+
+        # remove marker paragraph
+        parent.remove(para._element)
+        paragraphs.pop(idx)
+
+        # if template is different and still present, remove it too (after marker removal, index shifts)
+        if template_idx != idx and template_idx < len(paragraphs) + 1:
+            parent.remove(template_el)
+            paragraphs.pop(idx)
+
+        if not isinstance(items, list) or len(items) == 0:
+            continue
+
+        new_paras: List[Paragraph] = []
+        insert_pos = idx
+        for item in items:
+            new_el = deepcopy(template_el)
+            parent.insert(insert_pos, new_el)
+            new_para = Paragraph(new_el, para._parent)
+            new_text = loop_pat.sub("", _paragraph_text(new_para))
+            new_text = _replace_bracket_placeholders(new_text, item)
+            _rewrite_paragraph_text(new_para, new_text)
+            new_paras.append(new_para)
+            insert_pos += 1
+
+        paragraphs[idx:idx] = new_paras
+        idx += len(new_paras)
+
+
+def process_paragraph_blocks(paragraphs: list[Paragraph], data: Dict[str, Any]) -> None:
+    """
+    Handle block tags that may span multiple paragraphs:
+    {{?cond}}
+    ...
+    {{/}}
+    If condition false, clear text in range; if true, remove only the tags.
+    """
+    start_pat = re.compile(r"\{\{\?([^}]+)\}\}")
+    end_pat = re.compile(r"\{\{/\}\}")
+
+    i = 0
+    while i < len(paragraphs):
+        text = _paragraph_text(paragraphs[i])
+        start_match = start_pat.search(text)
+        if not start_match:
+            i += 1
+            continue
+
+        cond = start_match.group(1).strip()
+        depth = 1
+        j = i + 1
+        end_idx = None
+        while j < len(paragraphs):
+            t = _paragraph_text(paragraphs[j])
+            if start_pat.search(t):
+                depth += 1
+            if end_pat.search(t):
+                depth -= 1
+                if depth == 0:
+                    end_idx = j
+                    break
+            j += 1
+
+        if end_idx is None:
+            # no matching end; skip
+            i += 1
+            continue
+
+        if evaluate_condition(cond, data):
+            # condition true: remove tags; if tag-only paragraphs, delete them
+            new_start = start_pat.sub("", text)
+            new_end = end_pat.sub("", _paragraph_text(paragraphs[end_idx]))
+
+            to_delete = []
+            if new_start.strip() == "":
+                to_delete.append(i)
+            else:
+                _rewrite_paragraph_text(paragraphs[i], new_start)
+
+            if new_end.strip() == "":
+                to_delete.append(end_idx)
+            elif end_idx not in to_delete:
+                _rewrite_paragraph_text(paragraphs[end_idx], new_end)
+
+            # delete paragraphs marked (from end to start to keep indices valid)
+            for idx_del in sorted(to_delete, reverse=True):
+                p_el = paragraphs[idx_del]._element
+                p_el.getparent().remove(p_el)
+                paragraphs.pop(idx_del)
+
+            # adjust end_idx if paragraphs were removed
+            i = max(i, 0)
+        else:
+            # condition false: remove entire block paragraphs
+            for k in range(end_idx, i - 1, -1):
+                p_el = paragraphs[k]._element
+                p_el.getparent().remove(p_el)
+                paragraphs.pop(k)
+            # i remains the same position (now next paragraph)
+        # continue from current index
+        i = max(i, 0)
+
+
+def render_text(text: str, data: Dict[str, Any]) -> str:
+    """Process blocks then replace {{path}} placeholders."""
+    text = process_block(text, data)
+
+    def repl(match: re.Match):
+        path = match.group(1).strip()
+        val = get_nested_value(data, path)
+        return "" if val is None else str(val)
+
+    return PLACEHOLDER_PATTERN.sub(repl, text)
+
+
+def process_paragraph(paragraph: Paragraph, data: Dict[str, Any]) -> None:
+    """Render placeholders in a paragraph while preserving run styles."""
+    full_text = "".join(run.text for run in paragraph.runs)
+    rendered = render_text(full_text, data)
+
+    _rewrite_paragraph_text(paragraph, rendered)
+

word_template_engine-0.1.0/word_template_engine.py

@@ -0,0 +1,102 @@
+"""
+Word template engine implemented with python-docx + lxml helpers.
+Features:
+- Text placeholders {{data.field}}
+- Table row loops {{#data.list}} with [field] inside row
+- Conditional blocks {{?cond}}...{{/}}
+- Image placeholders {{@var}}
+"""
+import tempfile
+import shutil
+from typing import Any, Dict
+from docx import Document
+
+from utils.text_processor import (
+    process_paragraph,
+    process_paragraph_blocks,
+    process_paragraph_loops,
+)
+from utils.table_processor import process_table
+from utils.image_processor import process_paragraph_images
+
+
+class WordTemplateEngine:
+    def __init__(self, template_path: str):
+        self.template_path = template_path
+
+    def render(self, data: Dict[str, Any], output_path: str) -> None:
+        # work in temp copy to avoid mutating original
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".docx") as tmp:
+            shutil.copyfile(self.template_path, tmp.name)
+            tmp_path = tmp.name
+
+        doc = Document(tmp_path)
+
+        # process tables (row loops + inner placeholders)
+        for table in doc.tables:
+            process_table(table, data)
+            for row in table.rows:
+                for cell in row.cells:
+                    # handle paragraph-level loops and blocks in cells
+                    process_paragraph_loops(cell.paragraphs, data)
+                    process_paragraph_blocks(cell.paragraphs, data)
+                    for para in cell.paragraphs:
+                        process_paragraph(para, data)
+                        process_paragraph_images(para, data)
+
+        # process body paragraphs: loops -> blocks -> placeholders/images
+        process_paragraph_loops(doc.paragraphs, data)
+        process_paragraph_blocks(doc.paragraphs, data)
+        for para in doc.paragraphs:
+            process_paragraph(para, data)
+            process_paragraph_images(para, data)
+
+        doc.save(output_path)
+
+
+def main():
+    sample_data = {
+        "data": {
+            "diagnose": "测试诊断结果",
+            "mutationSiteZero": [
+                {"gene_transcript": "BRCA1", "value": "c.1234A>G"},
+                {"gene_transcript": "TP53", "value": "c.5678C>T"},
+            ],
+            "conclusion_A": "",
+            "image_config": {
+                "url": "123.png",
+                
+            },
+            "detectionResult":{
+                'data1':[
+                {
+                "gene":"gene1",
+                'rate':'rate1',
+                'age':'age1',
+                'symptoms':'symptoms1'
+            },
+            {
+                "gene":"gene2",
+                'rate':'rate1',
+                'age':'age2',
+                'symptoms':'symptoms1'
+            }
+            ],'data2':[
+                {
+                "gene":"gene3",
+                'rate':'rate3',
+                'age':'age3',
+                'symptoms':'symptoms3'
+            }
+            ]
+            }
+        }
+    }
+    engine = WordTemplateEngine("template.docx")
+    engine.render(sample_data, "output.docx")
+    print("done")
+
+
+if __name__ == "__main__":
+    main()
+