word-template-engine 0.1.0__py3-none-any.whl

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解析的最大优势

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解析的最大优势

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 = ["."]
+

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",
+]

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
+