pdfwright 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pdfwright
-Version: 0.3.0
+Version: 0.4.0
 Summary: 配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。
 License: Proprietary
 Requires-Python: >=3.12

{pdfwright-0.3.0 → pdfwright-0.4.0}/examples/generate_all.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 
 from pdfwright import DocumentConfig
+from pdfwright.fonts.registry import has_embeddable_cjk_font
 from pdfwright.render.html import render_html
 from pdfwright.render.pdf import render_pdf
 from pdfwright.validate import validate_document
@@ -26,6 +27,12 @@ def main() -> int:
     if not check_only:
         OUTPUT_DIR.mkdir(exist_ok=True)
 
+    # 渲染中文需要可嵌入的中文字体；缺字体时只跳过渲染，校验照跑 ——
+    # validate_document 不碰字体，整个脚本提前 return 会让这道关卡空转。
+    can_render = has_embeddable_cjk_font()
+    if not can_render:
+        print("⚠️  本机没有可嵌入的中文字体（ReportLab 只支持 TrueType/glyf）：只校验、不渲染")
+
     files = sorted(EXAMPLES_DIR.glob("*.json"))
     files = [f for f in files if f.parent == EXAMPLES_DIR]
     if not files:
@@ -45,6 +52,10 @@ def main() -> int:
                 print(f"    [{issue.path}] {issue.message}")
             continue
 
+        if not can_render:
+            print(f"{path.stem:<22}{'✓':<8}{'—':<6}{'（无字体，未渲染）':<20}")
+            continue
+
         document = DocumentConfig.from_dict(config)
         data = config.get("data")
         try:
@@ -67,7 +78,8 @@ def main() -> int:
     if failures:
         print(f"❌ {failures} 个示例未通过")
         return 1
-    print(f"✅ {len(files)} 个示例全部通过" + ("" if check_only else f"；产物在 {OUTPUT_DIR}"))
+    suffix = "" if can_render else "（无字体，仅校验）"
+    print(f"✅ {len(files)} 个示例全部通过{suffix}" + ("" if check_only else f"；产物在 {OUTPUT_DIR}"))
     return 0
 
 
@@ -78,4 +90,4 @@ def _page_count(pdf_bytes: bytes) -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

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

@@ -1,6 +1,6 @@
 [project]
 name = "pdfwright"
-version = "0.3.0"
+version = "0.4.0"
 description = "配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -37,6 +37,10 @@ exclude = ["examples/output"]
 addopts = "-ra --strict-markers"
 testpaths = ["tests"]
 pythonpath = ["src"]
+markers = [
+    # 需要本机装**可嵌入中文字体**的用例（无字体的容器里自动跳过，见 tests/conftest.py）
+    "needs_cjk: 用例前提是本机存在可嵌入的中文字面（ReportLab 只支持 TrueType/glyf）",
+]
 
 [tool.ruff]
 line-length = 100
@@ -90,10 +94,16 @@ venvPath = ".."
 venv = ".venv"
 # basedpyright 的 ``ignore`` 只接受「文件/目录 glob」，不支持「每模块忽略哪些规则」
 # （旧写法 [{module, codes}] 会让 basedpyright 报配置错并以退出码 3 结束，等于从未生效）。
-# 这三个解析器大量使用第三方库动态属性，规则级豁免无法表达，故整体不纳入 basedpyright；
-# 它们仍由 mypy 检查。
+# 下列模块大量使用第三方库动态属性（python-docx / reportlab / fontTools 的属性在
+# 类型存根里查不到），规则级豁免无法表达，故整体不纳入 basedpyright；仍由 mypy 检查。
+# 逐个列「真实报错」的模块，不是「docx 目录全列」—— docx_helpers / docx_state 目前
+# 干净，未列；新增模块请先单独跑一次 basedpyright 再决定要不要加进来。
 ignore = [
   "src/pdfwright/converters/docx.py",
+  "src/pdfwright/converters/docx_block.py",
+  "src/pdfwright/converters/docx_common.py",
+  "src/pdfwright/converters/docx_run.py",
+  "src/pdfwright/converters/docx_table.py",
   "src/pdfwright/converters/xlsx.py",
   "src/pdfwright/fonts/scanner.py",
 ]

{pdfwright-0.3.0 → pdfwright-0.4.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.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "BatchItem",

{pdfwright-0.3.0 → pdfwright-0.4.0}/src/pdfwright/converters/__init__.py

@@ -5,6 +5,7 @@ from pdfwright.converters.docx import (
     DocxField,
     DocxParseResult,
     docx_to_schema,
+    semantic_family,
 )
 from pdfwright.converters.html import (
     HtmlField,
@@ -23,6 +24,7 @@ __all__ = [
     "XlsxConverter",
     "docx_to_schema",
     "html_to_schema",
+    "semantic_family",
     "strip_html_tags",
     "xlsx_to_schema",
 ]

pdfwright-0.4.0/src/pdfwright/converters/docx.py

@@ -0,0 +1,123 @@
+"""DOCX 转换器：python-docx 解析 Word 文档 → pdfwright schema（高保真 + 模板标签 + 自动字段 key）。
+
+保真原则：**只翻译 docx 里真实存在的信息，不发明样式**。
+
+- 段落 = **一个元素**，`text` 是**富文本标记**（``<b>`` / ``<i>`` / ``<u>`` /
+  ``<font color= size= face=>``），``{{ 变量 }}`` **保持内联**——不再把
+  「``{{project_name}}日报``」拆成 input + 段落两个区域；
+- **逐 run** 取字体/字号/颜色/粗斜体（Word 的混排段落不会丢格式），但**样式已经表达过的
+  格式不重复写进 `text`**：整段同格式 → `text` 是纯文本（字体/字号/粗细在元素 `style`
+  上）；混排段落也只有与样式不同的片段才带标记。样式没有的位（下划线/高亮/上下标/字符间距）
+  留在内联标记里 —— 见 ``_baseline_fmt`` / ``_trim_fmt``；
+- 字体名**原样保留**（文档写 ``宋体`` 就存 ``宋体``、写 ``SimSun`` 就存 ``SimSun``、
+  写 ``华文中宋`` 就存 ``华文中宋``）——导入不替用户挑语义族，跨平台解析交给
+  fonts.registry（本机有该字面就精确命中真身，没有才按名字里的风格回退）；
+- 表格边框读 ``w:tblBorders`` / ``w:tcBorders``，底纹读 ``w:shd`` ——
+  **docx 没有底纹就不画底纹**（早前版本硬编码灰色表头，属于发明）；
+- 列宽读 ``w:gridCol`` / ``w:tcW``，垂直对齐读 ``w:vAlign``；
+- 图片提取为 image 元素（base64 data URL）；分页符 → pageBreak；
+- 字段识别：Word 内容控件（w:sdt）与**循环外**的 ``{{ 变量 }}`` → 可填字段；
+  **循环内**的 ``{{ 变量 }}`` → 保留为模板插值（渲染时按数据求值）；
+- 模板标签：``{% for x in y %}`` / ``{% endfor %}`` 可出现在段落或表格单元格中，
+  按出现顺序配对，循环体可跨多行（如「人员明细行 + 合计行」共享一个外层循环）。
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any
+
+from docx import Document
+
+from pdfwright.converters.docx_block import _DocxBlockMixin
+
+# ``DocxField`` 只在这里再导出（公开 API：``converters/__init__.py`` 从本模块取），
+# 本模块自己不用它 —— 故显式标注 F401。（noqa 只能跟规则码，说明写在独立注释行。）
+from pdfwright.converters.docx_common import (
+    DocxField,  # noqa: F401
+    DocxParseResult,
+)
+
+# 拆模块后本文件只剩「组合 + 入口」。`font_name` / `scan_jinja_tags` /
+# `strip_jinja_tags` 曾在这里带 F401 抑制注释再导出，但兄弟模块一律**直接**从
+# ``docx_common`` 导入，全仓（含测试与 pdfwright-web）无人从 ``converters.docx``
+# 取这三个名字 —— 那是纯死代码，还会让人误以为这里是它们的公开入口，故移除。
+# ``_format_number`` / ``semantic_family`` 相反：确实有人从这里导入，作为**向后兼容的
+# 公开入口**保留（本模块自己不用），并显式标注 F401。
+# （noqa 指令只能跟规则码，中文说明必须写在独立注释行。）
+from pdfwright.converters.docx_helpers import (  # noqa: F401
+    _format_number,  # 既有测试从这里导入
+    semantic_family,  # deprecated shim，见 docx_helpers.semantic_family
+)
+from pdfwright.converters.docx_run import _DocxRunMixin
+from pdfwright.converters.docx_table import _DocxTableMixin
+from pdfwright.errors import ConversionError
+from pdfwright.models import (
+    Element,
+)
+
+
+# 方法按职责拆到这些 mixin（共享状态在 ``docx_state.DocxConverterState`` 声明）：
+# 段落与 run → ``docx_run``，表格 → ``docx_table``，块结构与文档级信息 → ``docx_block``。
+class DocxConverter(_DocxRunMixin, _DocxTableMixin, _DocxBlockMixin):
+    """DOCX → DocumentConfig 转换器。"""
+
+    def __init__(self, auto_field: bool = True, inline_commands: bool = False) -> None:
+        self.auto_field = auto_field
+        #: 同一段落里的「文字 + 内联命令标签」是否**排在同一行**（见
+        #: ``_append_paragraph_content``）。默认 ``False`` = **块级**：文字与图片/签章位
+        #: 各自独立成块（导入结果与旧版逐字节一致，可自由拖拽、重排）；
+        #: 置 ``True`` 才包一层按内容的 ``row`` 保留 Word 的同行排版。
+        self.inline_commands = inline_commands
+        self._used_keys: set[str] = set()
+        self._part: Any = None
+        self._doc_defaults: Any = None
+        self._doc_sections: list[Any] = []
+        self._section_index = 0
+        self._table_margins: Any = None
+        # 列表编号：numId → {ilvl: (numFmt, start, lvlText)}；计数器随文档顺序累加
+        self._numbering: dict[str, dict[int, tuple[str, int, str]]] = {}
+        self._number_counters: dict[tuple[str, int], int] = {}
+        # 块栈：栈顶是当前打开的容器（``for`` / ``if``），其 children（if 在 else 时为
+        # else_children）收后续元素。元素为 ``(kind, node, in_else, chain_start)``；
+        # ``chain_start`` 标记 if 链起点（``{% elif %}`` 会在 else 分支里再开一个嵌套 if，
+        # 因此 ``{% endif %}`` 要把整条链一起关掉）。
+        self._block_stack: list[tuple[str, Element, bool, bool]] = []
+        # 内容插入目标覆盖：表格单元格必须写入自己的 td，而不是当前循环体
+        self._target_override: list[Element] | None = None
+        # 文档水印（浮动图片，``wp:anchor/@behindDoc=1``）
+        self._watermark: dict[str, Any] | None = None
+        # 文档默认字体（→ page.fontFamily；仅当文档自己声明了才下发，不按语言猜）
+        self._document_font_family: str | None = None
+
+    # ------------------------------------------------------------------ 入口
+    def convert(self, source: str | bytes | io.BytesIO) -> DocxParseResult:
+        try:
+            if isinstance(source, bytes):
+                document = Document(io.BytesIO(source))  # pyright: ignore[reportCallIssue]
+            elif isinstance(source, io.BytesIO):
+                document = Document(source)  # pyright: ignore[reportCallIssue]
+            else:
+                document = Document(source)  # pyright: ignore[reportCallIssue]
+        except Exception as exc:
+            # python-docx 只认 OOXML（.docx/.docm）；旧版二进制 .doc 会报
+            # PackageNotFoundError → 这里统一转成 ConversionError（HTTP 400 + 可读提示），
+            # 否则会以未处理异常冒到 500。
+            raise ConversionError(
+                message="不是有效的 .docx 文件（旧版二进制 .doc 需先转换为 .docx）",
+                detail={"reason": type(exc).__name__},
+                cause=exc,
+            ) from exc
+        self._part = document.part
+        return self._convert_doc(document)
+
+
+def docx_to_schema(
+    source: str | bytes | io.BytesIO, auto_field: bool = True, inline_commands: bool = False
+) -> DocxParseResult:
+    """一行调用：DOCX → DocumentConfig + 字段列表。
+
+    ``inline_commands``：同一段落里的「文字 + 内联命令标签」（``记录人：{{sign:…}}``）
+    是否排在**同一行**（默认 ``False`` = 块级，各自独立成块）。
+    """
+    return DocxConverter(auto_field=auto_field, inline_commands=inline_commands).convert(source)