pdfwright 0.2.2__tar.gz → 0.3.0__tar.gz

{pdfwright-0.2.2 → pdfwright-0.3.0}/.gitignore

@@ -31,3 +31,5 @@ pdfwright/examples/output/
 
 # 本地发布凭据（scripts/publish.sh --config 默认读它）
 .publish.env
+
+runtime/

{pdfwright-0.2.2 → pdfwright-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pdfwright
-Version: 0.2.2
+Version: 0.3.0
 Summary: 配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。
 License: Proprietary
 Requires-Python: >=3.12
@@ -11,6 +11,7 @@ Requires-Dist: jsonschema>=4.23
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: pikepdf>=8.0
 Requires-Dist: pillow>=10.0
+Requires-Dist: pypdf>=4.0
 Requires-Dist: python-barcode>=0.16.1
 Requires-Dist: python-docx>=1.1
 Requires-Dist: reportlab<6,>=5.0

{pdfwright-0.2.2 → pdfwright-0.3.0}/examples/cooperation_contract.json

@@ -791,12 +791,12 @@
   "data": {
     "party_a": {
       "name": "xxx公司",
-      "address": "北京市海淀区中关村大街1号",
+      "address": "北京市海淀区某某大街 1 号",
       "representative": "xxx"
     },
     "party_b": {
       "name": "yyy公司",
-      "address": "上海市浦东新区张江高科技园区",
+      "address": "上海市浦东新区某某高科技园区",
       "representative": "yyy"
     }
   }

{pdfwright-0.2.2 → pdfwright-0.3.0}/examples/daily_report.json

@@ -827,7 +827,7 @@
     "keywords": "工程日报, 施工, 人员, 设备, 材料"
   },
   "data": {
-    "project_name": "城东污水处理厂扩建工程",
+    "project_name": "某某污水处理厂扩建工程",
     "date": "2026-09-19",
     "person": [
       {

{pdfwright-0.2.2 → pdfwright-0.3.0}/examples/service_contract.json

@@ -532,12 +532,12 @@
     },
     "party_a": {
       "name": "xxx公司",
-      "address": "北京市海淀区中关村大街1号",
+      "address": "北京市海淀区某某大街 1 号",
       "representative": "xxx"
     },
     "party_b": {
       "name": "yyy公司",
-      "address": "上海市浦东新区张江高科技园区",
+      "address": "上海市浦东新区某某高科技园区",
       "representative": "yyy"
     },
     "clauses": [

{pdfwright-0.2.2 → pdfwright-0.3.0}/examples/staff_form.json

@@ -25,7 +25,7 @@
         { "label": "Vue", "value": "Vue" }, { "label": "Kubernetes", "value": "Kubernetes" }
       ]}},
     { "name": "emergency", "type": "string", "label": "紧急联系人", "default": "xxx（父亲）138-1111-2222" },
-    { "name": "address", "type": "textarea", "label": "现居住地址", "default": "浙江省杭州市余杭区文一西路 969 号" },
+    { "name": "address", "type": "textarea", "label": "现居住地址", "default": "浙江省杭州市余杭区某某路 1 号" },
     { "name": "photo", "type": "image", "label": "证件照" },
     { "name": "signature", "type": "image", "label": "本人签名", "empty": "blank" }
   ],

{pdfwright-0.2.2 → pdfwright-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdfwright"
-version = "0.2.2"
+version = "0.3.0"
 description = "配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -17,6 +17,8 @@ dependencies = [
     "pillow>=10.0",
     "segno>=1.6.6",
     "python-barcode>=0.16.1",
+    # BSD-3，纯 Python：读回产物做「一致性指纹」（跨平台比对版式与字体，见 postprocess/fingerprint.py）
+    "pypdf>=4.0",
 ]
 
 [build-system]
@@ -81,6 +83,11 @@ check_untyped_defs = true
 [tool.basedpyright]
 typeCheckingMode = "basic"
 include = ["src"]
+# 显式指向 **工作区根** 的 venv：basedpyright 默认会优先用同目录下的 ``.venv``，
+# 而子项目里可能存在空壳/过期的 ``.venv``（本地遗留），于是纯 Python 依赖
+# （pypdf / segno / openpyxl…）解析不到 → 检查结果取决于本机残留目录，不可复现。
+venvPath = ".."
+venv = ".venv"
 # basedpyright 的 ``ignore`` 只接受「文件/目录 glob」，不支持「每模块忽略哪些规则」
 # （旧写法 [{module, codes}] 会让 basedpyright 报配置错并以退出码 3 结束，等于从未生效）。
 # 这三个解析器大量使用第三方库动态属性，规则级豁免无法表达，故整体不纳入 basedpyright；

{pdfwright-0.2.2 → pdfwright-0.3.0}/src/pdfwright/__init__.py

@@ -26,7 +26,7 @@ from pdfwright.postprocess import verify_pdfa
 from pdfwright.render.html import render_html
 from pdfwright.render.pdf import PdfRenderer, render_pdf, render_pdf_to_file
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 __all__ = [
     "BatchItem",

pdfwright-0.3.0/src/pdfwright/commands.py

@@ -0,0 +1,197 @@
+"""文本命令标签：在 Word 正文里用 ``{{ ... }}`` 描述**非文本元素**。
+
+作者不必用开发工具/内容控件/书签，直接打字即可（导入时转成对应元素）：
+
+.. list-table::
+   :header-rows: 1
+
+   * - 标签
+     - 转成
+   * - ``{{__TOC__}}`` / ``{{__TOC__:3}}``
+     - ``toc``（可选层级数）
+   * - ``{{__pageBreak__}}``
+     - ``pageBreak``
+   * - ``{{hiddenText:SEAL_PARTY_A}}``
+     - ``hiddenText``（不可见、可抽取，供签章系统定位）
+   * - ``{{img:photo}}`` / ``{{img:logo.png,mxw_120,mxh_80,dx_3mm,dy_1mm}}``
+     - ``image``（``photo`` 视为数据键；带 ``/``/``.``/``:`` 的视为路径或 URL）
+   * - ``{{sign:签字人[,数据键][,mxw_…][,mxh_…][,dx_…][,dy_…]}}``
+     - ``sign``（第一个位置参数是签章人 = 隐藏文本锚点 + 字段名；第二个当本地签字图的数据键）
+   * - ``{{anchor:sec1}}``
+     - ``anchor``（命名跳转目标）
+
+**与数据表达式的区分**（`{{ }}` 同时是 Jinja 插值语法）：
+
+- 无参数的单名命令必须写成 ``__名字__``（如 ``__TOC__``），避免与同名数据变量冲突；
+- 带参数的命令用冒号分隔（``img:`` / ``sign:`` / ``hiddenText:`` / ``anchor:``），
+  ``{{ img:… }}`` 本身不是合法 Jinja 表达式，所以 ``__`` 可省（写成 ``__img:…__`` 也收）；
+- 都匹配不上时**按普通数据表达式处理**，本文档的解析完全不改变既有行为。
+
+渲染端还有一层兜底：万一有命令标签没被导入阶段消费（手写的 JSON、写错的名字），
+按「空 + 告警」处理，绝不让一个笔误把整篇渲染炸掉（``strip_commands``）。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+#: ``{{ ... }}`` 片段（非贪婪，跨行安全）
+TAG_RE = re.compile(r"\{\{(.*?)\}\}", re.DOTALL)
+#: 无参数命令（必须写 ``__名字__``）
+NO_ARG_COMMANDS = frozenset({"toc", "pagebreak"})
+#: 带参数命令（``名字:参数,参数``）
+ARG_COMMANDS = frozenset({"hiddentext", "img", "sign", "anchor"})
+ALL_COMMANDS = NO_ARG_COMMANDS | ARG_COMMANDS
+
+#: 尺寸参数名 → schema 的 style 键（``mxw_120`` / ``mxw=120`` / ``w_120`` 都收）。
+#: ``mxw/mxh`` 是作者常用的「最大宽/高」写法；当前实现里等价于 image 的
+#: ``style.width``/``style.height``（绘制尺寸，超版心时再等比缩）。
+SIZE_ARGS: dict[str, str] = {
+    "mxw": "width",
+    "w": "width",
+    "mxh": "height",
+    "h": "height",
+}
+
+#: 相对偏移参数名 → 元素字段（``dx_6mm`` / ``dy_2mm``，也收 ``dx=6mm``）。
+#: **右为正 / 上为正**，与第三方签章服务的 ``leftOrRight`` / ``upOrDown`` 同符号；
+#: 只挪绘制位置、不改变占位尺寸（注意与 ``position:"absolute"`` 的 ``y`` 方向相反）。
+OFFSET_ARGS: dict[str, str] = {
+    "dx": "offsetX",
+    "dy": "offsetY",
+}
+
+_SIZE_RE = re.compile(r"(?i)^(mxw|mxh|w|h)[_=](.+)$")
+_OFFSET_RE = re.compile(r"(?i)^(dx|dy)[_=](.+)$")
+
+
+@dataclass(frozen=True)
+class Command:
+    """解析出的命令标签（不依赖 schema；由调用方转成元素）。"""
+
+    name: str
+    args: tuple[str, ...]
+    body: str
+
+    def arg(self, index: int) -> str | None:
+        """第 ``index`` 个位置参数（无则 None）。"""
+        return self.args[index] if index < len(self.args) else None
+
+    def sizes(self) -> dict[str, str]:
+        """``mxw_120,mxh_80`` → ``{"width": "120", "height": "80"}``。"""
+        out: dict[str, str] = {}
+        for part in self.args:
+            match = _SIZE_RE.match(part)
+            if match:
+                out[SIZE_ARGS[match.group(1).casefold()]] = match.group(2).strip()
+        return out
+
+    def offsets(self) -> dict[str, str]:
+        """``dx_6mm,dy_2mm`` → ``{"offsetX": "6mm", "offsetY": "2mm"}``。"""
+        out: dict[str, str] = {}
+        for part in self.args:
+            match = _OFFSET_RE.match(part)
+            if match:
+                out[OFFSET_ARGS[match.group(1).casefold()]] = match.group(2).strip()
+        return out
+
+    def rest_args(self) -> tuple[str, ...]:
+        """既不是尺寸、也不是偏移的位置参数（``img:photo,mxw_120`` → ``("photo",)``）。"""
+        return tuple(
+            part for part in self.args if not _SIZE_RE.match(part) and not _OFFSET_RE.match(part)
+        )
+
+
+def parse_command(body: str) -> Command | None:
+    """``{{ ... }}`` 内部文本 → 命令；不是命令时返回 ``None``（按数据表达式处理）。"""
+    text = body.strip()
+    if not text:
+        return None
+    name, _separator, rest = text.partition(":")
+    stripped = name.strip()
+    key = stripped.strip("_").casefold()
+    if key not in ALL_COMMANDS:
+        return None
+    dunder = stripped.startswith("_") and stripped.endswith("_")
+    args = tuple(part.strip() for part in rest.split(",") if part.strip())
+    if key in NO_ARG_COMMANDS:
+        # 单名命令要求 ``__名字__``：否则 ``{{ toc }}`` 这种数据变量会被误认
+        return Command(key, args, text) if dunder else None
+    return Command(key, args, text) if args else None
+
+
+def iter_tags(text: str) -> list[tuple[int, int, str]]:
+    """扫出 ``{{ … }}`` 片段 ``(start, end, body)``，**支持嵌套**。
+
+    用花括号配对而不是正则：``{{img:{{ item.image }}}}`` 里的内层 ``{{ }}``
+    必须一起算进来，否则非贪婪正则会在内层 ``}}`` 提前截断（实测把模板切成
+    ``{{ item.image`` + 一个孤零零的 ``}}``）。
+    """
+    found: list[tuple[int, int, str]] = []
+    index = 0
+    length = len(text)
+    while True:
+        start = text.find("{{", index)
+        if start < 0:
+            return found
+        depth = 1
+        cursor = start + 2
+        while cursor < length and depth:
+            if text.startswith("{{", cursor):
+                depth += 1
+                cursor += 2
+            elif text.startswith("}}", cursor):
+                depth -= 1
+                cursor += 2
+            else:
+                cursor += 1
+        if depth:
+            return found  # 未闭合：后面不再是标签
+        found.append((start, cursor, text[start + 2 : cursor - 2]))
+        index = cursor
+
+
+def looks_like_command(body: str) -> bool:
+    """``{{ … }}`` 内部是否**看起来**是命令标签（首段是已知命令名）。
+
+    渲染端兜底用：即使参数写错（如 ``{{img:}}``、``{{__TOC__:x}}``）也当命令处理
+    （空 + 告警），而不是丢给 Jinja 报 ``chunk after expression`` 把整篇炸掉。
+    """
+    name = body.strip().partition(":")[0].strip().strip("_").casefold()
+    return name in ALL_COMMANDS
+
+
+def iter_commands(text: str) -> list[tuple[int, int, Command]]:
+    """文本里所有**合法**命令标签的 ``(start, end, command)``（按出现顺序）。"""
+    if "{{" not in text:
+        return []
+    found: list[tuple[int, int, Command]] = []
+    for start, end, body in iter_tags(text):
+        command = parse_command(body)
+        if command is not None:
+            found.append((start, end, command))
+    return found
+
+
+def strip_commands(text: str) -> tuple[str, list[str]]:
+    """去掉命令标签（渲染端兜底）：返回 ``(剩余文本, 遇到的命令标签原文)``。
+
+    导入阶段会把命令标签转成元素；万一还有残留（手写 JSON、参数写错的命令），
+    这里把它们当空处理并回报，让渲染端告警而不是抛 Jinja 语法错误。
+    """
+    if "{{" not in text:
+        return text, []
+    out: list[str] = []
+    names: list[str] = []
+    position = 0
+    for start, end, body in iter_tags(text):
+        if not looks_like_command(body):
+            continue
+        out.append(text[position:start])
+        names.append(body.strip())
+        position = end
+    if not names:
+        return text, []
+    out.append(text[position:])
+    return "".join(out), names