pdfwright 0.2.1__tar.gz → 0.2.2__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "pdfwright"
-version = "0.2.1"
+version = "0.2.2"
 description = "配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。"
 readme = "README.md"
 requires-python = ">=3.12"

{pdfwright-0.2.1 → pdfwright-0.2.2}/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.1"
+__version__ = "0.2.2"
 
 __all__ = [
     "BatchItem",

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/converters/docx.py

@@ -238,10 +238,15 @@ class DocxField:
 
 @dataclass
 class DocxParseResult:
-    """DOCX 解析结果。"""
+    """DOCX 解析结果。
+
+    ``data`` 是自动生成的**示例数据**（让导入后立刻能看到渲染效果）—— 它与配置分离，
+    不由 ``DocumentConfig`` 携带，调用方自行按需传给 ``render_pdf``。
+    """
 
     document: DocumentConfig
     fields: list[DocxField] = field(default_factory=list)
+    data: dict[str, Any] | None = None
 
 
 class DocxConverter:
@@ -347,8 +352,9 @@ class DocxConverter:
         ]
         mock = self._build_mock_data(body, fields)
         return DocxParseResult(
-            document=DocumentConfig(page=page, body=body, variables=variables, data=mock or None),
+            document=DocumentConfig(page=page, body=body, variables=variables),
             fields=fields,
+            data=mock or None,
         )
 
     def _page_config(self, section: Any, previous: dict[str, Any] | None = None) -> dict[str, Any]:

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/converters/html.py

@@ -153,10 +153,14 @@ class HtmlField:
 
 @dataclass
 class HtmlParseResult:
-    """HTML 解析结果。"""
+    """HTML 解析结果。
+
+    ``data`` 是自动生成的**示例数据**（与配置分离，不由 ``DocumentConfig`` 携带）。
+    """
 
     document: DocumentConfig
     fields: list[HtmlField] = field(default_factory=list)
+    data: dict[str, Any] | None = None
 
 
 @dataclass
@@ -393,9 +397,8 @@ class _Converter:
             page=PageConfig(),
             body=body,
             variables=variables,
-            data=data or None,
         )
-        return HtmlParseResult(document=document, fields=self.fields)
+        return HtmlParseResult(document=document, fields=self.fields, data=data or None)
 
     @staticmethod
     def _read(source: str | bytes | io.BytesIO) -> str:

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/models/document.py

@@ -183,7 +183,12 @@ class Variable:
 
 @dataclass
 class DocumentConfig:
-    """顶层文档配置（设计师最终产出的页面 JSON）。"""
+    """顶层文档配置（设计师最终产出的页面 JSON）。
+
+    配置与数据分离：本文档**只描述页面**（版式/元素/变量声明/PDF 配置），不含任何填写数据。
+    数据一律由调用方在渲染时传入（``render_pdf(document, data)``，缺省视为空对象）。
+    变量的默认值写在 ``variables[].default``（变量/元素自身的配置）里，不另设文档级 data。
+    """
 
     version: str = "1.0"
     page: PageConfig = field(default_factory=PageConfig)
@@ -191,7 +196,6 @@ class DocumentConfig:
     security: dict[str, Any] | None = None
     variables: list[Variable] = field(default_factory=list)
     body: list[Element] = field(default_factory=list)
-    data: dict[str, Any] | None = None  # 示例/默认数据（运行态由表单填写产生）
     html: dict[str, Any] | None = None  # HTML 预览专有配置节
     pdf: dict[str, Any] | None = None  # PDF 渲染专有配置节
     #: 文档元数据。标准键（title/author/subject/keywords/creator）写入 PDF 标准字段，
@@ -207,7 +211,6 @@ class DocumentConfig:
             raise SchemaError(message="文档配置必须是 JSON 对象")
         body = [Element.from_dict(item) for item in raw.get("body", []) or []]
         variables = [Variable.from_dict(item) for item in raw.get("variables", []) or []]
-        data = raw.get("data")
         meta_raw = raw.get("meta")
         pdf_raw = raw.get("pdf")
         html_raw = raw.get("html")
@@ -217,7 +220,6 @@ class DocumentConfig:
             security=raw.get("security") if isinstance(raw.get("security"), dict) else None,
             variables=variables,
             body=body,
-            data=data if isinstance(data, dict) else None,
             html=html_raw if isinstance(html_raw, dict) else None,
             pdf=pdf_raw if isinstance(pdf_raw, dict) else None,
             meta=meta_raw if isinstance(meta_raw, dict) else {},
@@ -230,6 +232,8 @@ class DocumentConfig:
                     "variables",
                     "page",
                     "version",
+                    # 顶层 ``data`` 不是配置字段（配置与数据分离）：读过即丢，
+                    # 也不能漏进 ``raw`` —— 否则 ``to_dict()`` 会把它吐回来，脏数据复活。
                     "data",
                     "html",
                     "pdf",
@@ -247,8 +251,6 @@ class DocumentConfig:
         }
         if self.variables:
             out["variables"] = [v.to_dict() for v in self.variables]
-        if self.data is not None:
-            out["data"] = self.data
         if self.html:
             out["html"] = self.html
         if self.pdf:
@@ -284,16 +286,6 @@ class DocumentConfig:
             page["footerDistance"] = self.page.footerDistance
         return page
 
-    def default_data(self) -> dict[str, Any]:
-        """合并默认数据：显式 data 优先，其次变量声明的 default。"""
-        data: dict[str, Any] = {}
-        for variable in self.variables:
-            if variable.default is not None:
-                data[variable.name] = variable.default
-        if self.data:
-            data.update(self.data)
-        return data
-
     def widget_elements(self) -> list[Element]:
         """文档所有数据控件节点（填写表单据此生成）。"""
         return collect_widgets(self.body)

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/render/html/__init__.py

@@ -36,7 +36,14 @@ from pdfwright.render.codes import (
     DEFAULT_QR_SIZE,
     code_png,
 )
-from pdfwright.render.markup import parse_markup, parse_style_attr, strip_markup
+from pdfwright.render.markup import (
+    clamp_css_font_size,
+    clamp_font_size,
+    is_safe_href,
+    parse_markup,
+    parse_style_attr,
+    strip_markup,
+)
 from pdfwright.render.table import cell_regions, grid_placements
 from pdfwright.security import ensure_image_size, ensure_local_path
 from pdfwright.template.engine import TemplateEngine
@@ -74,8 +81,6 @@ _SAFE_CSS_PROPS = {
     "text-decoration",
 }
 
-_SAFE_URL_SCHEMES = ("http://", "https://", "mailto:", "/", "#")
-
 
 def markup_to_html(markup: str | None) -> str:
     """内联标记 → HTML（文本转义；``<font face size color>`` 转成 span 内联样式）。
@@ -104,7 +109,7 @@ def markup_to_html(markup: str | None) -> str:
             continue
         if tag == "a":
             href = str(token.attrs.get("href") or "")
-            if href and not href.lower().startswith(_SAFE_URL_SCHEMES):
+            if not is_safe_href(href):
                 href = ""
             attrs = f' href="{_html.escape(href)}"' if href else ""
             parts.append(f"<a{attrs}>")
@@ -113,8 +118,10 @@ def markup_to_html(markup: str | None) -> str:
             styles = []
             parsed = parse_style_attr(token.attrs.get("style", ""))
             for prop, value in parsed.items():
-                if prop in _SAFE_CSS_PROPS:
-                    styles.append(f"{prop}:{value}")
+                if prop not in _SAFE_CSS_PROPS:
+                    continue
+                raw = clamp_css_font_size(value) if prop == "font-size" else value
+                styles.append(f"{prop}:{raw}")
             if parsed.get("font-family"):
                 family = css_font_family(parsed["font-family"].split(",")[0].strip())
                 if family:
@@ -134,7 +141,7 @@ def markup_to_html(markup: str | None) -> str:
         size = token.attrs.get("size")
         if size:
             with contextlib.suppress(ValueError):
-                styles.append(f"font-size:{float(size):.1f}pt")
+                styles.append(f"font-size:{clamp_font_size(float(size)):.1f}pt")
         if token.attrs.get("color"):
             styles.append(f"color:{token.attrs['color']}")
         if token.attrs.get("backcolor"):

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/render/markup.py

@@ -8,6 +8,8 @@
 - 渲染器各自决定如何落地（ReportLab 用自己的 ``<font>``；HTML 把 ``size`` 换算成
   ``font-size:Npt``，因为 HTML 的 ``<font size>`` 是 1–7 档，语义完全不同）；
 - 非白名单标签一律按普通文本处理（调用方负责转义），避免注入。
+- ``<a href>`` 只放行 ``SAFE_URL_SCHEMES``（HTML 与 PDF 两侧一致，`javascript:`/`data:` 丢弃）；
+  ``<font size>`` / ``span{font-size}`` 夹到 ``MIN/MAX_MARKUP_FONT_SIZE``（挡病态字号撑爆版面）。
 """
 
 from __future__ import annotations
@@ -52,6 +54,42 @@ PAIRED_TAGS = ALLOWED_TAGS - {"br"}
 #: span/mark 的默认高亮色
 DEFAULT_MARK_COLOR = "#fffbb8"
 
+#: `<a href>` 允许的 URL scheme（白名单：其余一律丢弃）。
+#: 用**允许列表**而不是黑名单：任何归一化差异（大小写/空白/换行）只会误拦安全链接，
+#: 不会放过 `javascript:` / `data:` / `vbscript:` 之类。
+SAFE_URL_SCHEMES = ("http://", "https://", "mailto:", "/", "#")
+
+#: 内联标记里的字号范围（pt）：挡住 `size="5000"` 这类把版面撑爆的病态值。
+#: 500pt ≈ 17.6cm 字高，正常排版（A4/A3 海报）远小于此。
+MIN_MARKUP_FONT_SIZE = 1.0
+MAX_MARKUP_FONT_SIZE = 500.0
+
+#: CSS font-size 里的数值部分（保留单位）
+_CSS_FONT_SIZE_RE = re.compile(r"(-?[\d.]+)")
+
+
+def is_safe_href(href: str | None) -> bool:
+    """`<a href>` 是否可信（非空且 scheme 在白名单内）。"""
+    return bool(href) and str(href).lower().startswith(SAFE_URL_SCHEMES)
+
+
+def clamp_font_size(size: float) -> float:
+    """把字号（pt）夹到合法范围。"""
+    return min(max(float(size), MIN_MARKUP_FONT_SIZE), MAX_MARKUP_FONT_SIZE)
+
+
+def clamp_css_font_size(value: str) -> str:
+    """把 CSS ``font-size`` 的数值部分夹到合法范围（保留原单位）。"""
+    raw = value.strip()
+    match = _CSS_FONT_SIZE_RE.match(raw)
+    if not match:
+        return value
+    try:
+        size = float(match.group(1))
+    except ValueError:
+        return value
+    return f"{clamp_font_size(size):g}{raw[match.end() :]}"
+
 
 def parse_style_attr(value: str) -> dict[str, str]:
     """解析 ``style="color:red;font-size:12pt"`` → dict（键小写）。"""
@@ -109,4 +147,16 @@ def strip_markup(markup: str) -> str:
     return "".join(token.text for token in parse_markup(markup) if token.kind == "text")
 
 
-__all__ = ["ALLOWED_TAGS", "Token", "parse_markup", "strip_markup"]
+__all__ = [
+    "ALLOWED_TAGS",
+    "MAX_MARKUP_FONT_SIZE",
+    "MIN_MARKUP_FONT_SIZE",
+    "SAFE_URL_SCHEMES",
+    "Token",
+    "clamp_css_font_size",
+    "clamp_font_size",
+    "is_safe_href",
+    "parse_markup",
+    "parse_style_attr",
+    "strip_markup",
+]

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/render/pdf.py

@@ -64,6 +64,8 @@ from pdfwright.render.codes import (
 from pdfwright.render.markup import (
     DEFAULT_MARK_COLOR,
     REPORTLAB_TAGS,
+    clamp_font_size,
+    is_safe_href,
     parse_markup,
     parse_style_attr,
     strip_markup,
@@ -572,7 +574,9 @@ class PdfRenderer:
                 state["family"] = "mono"
             elif tag == "a":
                 stack.append(("link", state["link"]))
-                state["link"] = token.attrs.get("href") or None
+                href = token.attrs.get("href")
+                # scheme 白名单：`javascript:` 之类不得写进 PDF 的 /URI 动作（与 HTML 侧一致）
+                state["link"] = href if is_safe_href(href) else None
             elif tag == "span":
                 stack.append(("span", dict(state)))
                 self._apply_style_attr(state, token.attrs.get("style", ""))
@@ -582,7 +586,7 @@ class PdfRenderer:
                     state["family"] = token.attrs["face"]
                 if token.attrs.get("size"):
                     with contextlib.suppress(ValueError):
-                        state["size"] = float(token.attrs["size"])
+                        state["size"] = clamp_font_size(float(token.attrs["size"]))
                 if token.attrs.get("color"):
                     state["color"] = token.attrs["color"]
                 if token.attrs.get("backcolor"):
@@ -597,7 +601,7 @@ class PdfRenderer:
         size = parsed.get("font-size", "")
         match = re.match(r"([\d.]+)", size) if size else None
         if match:
-            state["size"] = float(match.group(1))
+            state["size"] = clamp_font_size(float(match.group(1)))
         if parsed.get("color"):
             state["color"] = parsed["color"]
         if parsed.get("background-color"):

{pdfwright-0.2.1 → pdfwright-0.2.2}/src/pdfwright/template/context.py

@@ -1,4 +1,4 @@
-"""模板上下文：把 data（用户填写数据）与变量默认值合并为 jinja2 渲染的作用域。"""
+"""模板上下文：把填写数据（data）与变量默认值合并为 jinja2 渲染的作用域。"""
 
 from __future__ import annotations
 
@@ -14,14 +14,15 @@ def build_context(
 ) -> dict[str, Any]:
     """构建渲染上下文（顶层变量直接可访问）。
 
-    合并顺序（低到高优先级）：变量默认值 < 用户数据 data < extra（循环变量等）。
+    配置与数据分离：数据**只**从 ``data`` 参数进（未传 = 空对象），
+    ``document`` 不携带任何数据。
+
+    合并顺序（低到高优先级）：变量默认值（``variables[].default``）< 填写数据 < extra（循环变量等）。
     """
     context: dict[str, Any] = {}
     for variable in document.variables:
         if variable.default is not None:
             context[variable.name] = variable.default
-    if document.data:
-        context.update(document.data)
     if data:
         context.update(data)
     if extra:

{pdfwright-0.2.1 → pdfwright-0.2.2}/tests/test_html_converter.py

@@ -71,9 +71,9 @@ def test_html_table_with_loop() -> None:
     # 循环内 {{item.*}} 不登记字段，循环外 {{total}} 登记
     names = {f.name for f in result.fields}
     assert names == {"total"}
-    # 示例数据可渲染
-    assert result.document.data
-    assert result.document.data["rows"]
+    # 示例数据（与配置分离，挂在 ParseResult 上）可渲染
+    assert result.data
+    assert result.data["rows"]
 
 
 def test_html_security_and_sanitizing() -> None:

pdfwright-0.2.2/tests/test_render_markup.py

@@ -0,0 +1,131 @@
+"""内联富文本标记的**安全硬化**：链接 scheme 白名单 + 字号 clamp。
+
+设计要点（同 `render/markup.py`）：`<a href>` 只放行允许的 scheme（HTML 与 PDF 一致，
+`javascript:` 一律丢弃）；`<font size>` / `span{font-size}` 夹到合法范围，挡住撑爆版面的病态值。
+"""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+from pypdf import PdfReader
+
+from pdfwright import DocumentConfig
+from pdfwright.render.html import markup_to_html, render_html
+from pdfwright.render.markup import (
+    MAX_MARKUP_FONT_SIZE,
+    MIN_MARKUP_FONT_SIZE,
+    clamp_css_font_size,
+    clamp_font_size,
+    is_safe_href,
+)
+from pdfwright.render.pdf import render_pdf
+
+
+def _doc(text: str) -> DocumentConfig:
+    return DocumentConfig.from_dict({"body": [{"type": "paragraph", "text": text}]})
+
+
+# --------------------------------------------------------------------------- #
+# scheme 白名单
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize(
+    "href",
+    ["http://a.example", "https://a.example", "mailto:a@b.c", "/rel/path", "#anchor"],
+)
+def test_is_safe_href_allows(href: str) -> None:
+    assert is_safe_href(href)
+
+
+@pytest.mark.parametrize(
+    "href",
+    [
+        None,
+        "",
+        "javascript:alert(1)",
+        "JAVASCRIPT:alert(1)",
+        " javascript:alert(1)",  # 前置空白归一化差异只应误拦，不能放过
+        "java\nscript:alert(1)",
+        "data:text/html,<script>1</script>",
+        "vbscript:msgbox(1)",
+        "file:///etc/passwd",
+    ],
+)
+def test_is_safe_href_rejects(href: str | None) -> None:
+    assert not is_safe_href(href)
+
+
+def test_html_drops_unsafe_href_keeps_safe() -> None:
+    html = markup_to_html('<a href="javascript:alert(1)">坏</a><a href="https://ok.example">好</a>')
+    assert "javascript:" not in html
+    assert html.startswith("<a>坏</a>")  # scheme 不合法 → 剥成无 href 的 <a>
+    assert 'href="https://ok.example"' in html
+
+
+def test_pdf_drops_unsafe_href_keeps_safe() -> None:
+    """PDF 的 /URI 动作必须与 HTML 同样过滤（此前 javascript: 会原样写进去）。"""
+    payload = render_pdf(
+        _doc('<a href="javascript:alert(1)">坏</a> <a href="https://ok.example">好</a>'), {}
+    )
+    uris = [
+        annot.get_object().get("/A").get_object().get("/URI")
+        for page in PdfReader(io.BytesIO(payload)).pages
+        for annot in (page.get("/Annots") or [])
+    ]
+    assert "https://ok.example" in uris
+    assert all(not str(uri).lower().startswith("javascript:") for uri in uris)
+
+
+# --------------------------------------------------------------------------- #
+# 字号 clamp
+# --------------------------------------------------------------------------- #
+def test_clamp_font_size_bounds() -> None:
+    assert clamp_font_size(5000) == MAX_MARKUP_FONT_SIZE
+    assert clamp_font_size(0) == MIN_MARKUP_FONT_SIZE
+    assert clamp_font_size(-12) == MIN_MARKUP_FONT_SIZE
+    assert clamp_font_size(14) == 14
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("5000pt", f"{MAX_MARKUP_FONT_SIZE:g}pt"),
+        ("0.0001pt", f"{MIN_MARKUP_FONT_SIZE:g}pt"),
+        ("-3pt", f"{MIN_MARKUP_FONT_SIZE:g}pt"),
+        ("14pt", "14pt"),
+        ("16px", "16px"),  # 保留原单位
+        ("abc", "abc"),  # 非数值原样返回
+    ],
+)
+def test_clamp_css_font_size(raw: str, expected: str) -> None:
+    assert clamp_css_font_size(raw) == expected
+
+
+def test_html_clamps_font_size() -> None:
+    html = markup_to_html('<font size="5000">甲</font><font size="0.0001">乙</font>')
+    assert f"font-size:{MAX_MARKUP_FONT_SIZE:.1f}pt" in html
+    assert f"font-size:{MIN_MARKUP_FONT_SIZE:.1f}pt" in html
+    assert "5000.0pt" not in html
+
+
+def test_html_clamps_span_font_size() -> None:
+    html = markup_to_html('<span style="font-size:9999pt;color:red">甲</span>')
+    assert f"font-size:{MAX_MARKUP_FONT_SIZE:g}pt" in html
+    assert "color:red" in html
+
+
+def test_pdf_clamps_huge_font_size_without_breaking() -> None:
+    """超大字号被夹住，渲染仍然成功（不撑爆版面、不抛异常）。"""
+    payload = render_pdf(_doc('<font size="5000">甲</font><font size="0.0001">乙</font>'), {})
+    assert payload[:4] == b"%PDF"
+    text = "".join(page.extract_text() or "" for page in PdfReader(io.BytesIO(payload)).pages)
+    assert "甲" in text
+    assert "乙" in text
+
+
+def test_render_html_escapes_unknown_tags_as_text() -> None:
+    """未知标签按文本输出（转义），不是丢弃、更不是执行。"""
+    html = render_html(_doc("<script>alert(1)</script>正文"), {})
+    assert "<script>" not in html
+    assert "&lt;script&gt;" in html

{pdfwright-0.2.1 → pdfwright-0.2.2}/tests/test_template.py

@@ -105,15 +105,29 @@ def test_build_context_merge_order() -> None:
     doc = DocumentConfig.from_dict(
         {
             "variables": [{"name": "a", "default": 1}, {"name": "b", "default": 2}],
-            "data": {"b": 20},
         }
     )
     ctx = build_context(doc, {"b": 200}, extra={"loop": "x"})
-    assert ctx["a"] == 1  # 默认值
-    assert ctx["b"] == 200  # 填写数据覆盖默认与示例
+    assert ctx["a"] == 1  # 变量默认值
+    assert ctx["b"] == 200  # 填写数据覆盖默认值
     assert ctx["loop"] == "x"
 
 
+def test_document_data_is_not_a_config_field() -> None:
+    """配置与数据分离：顶层 ``data`` 不是配置字段，既不入上下文也不 round-trip 回来。"""
+    raw = {
+        "variables": [{"name": "b", "default": 2}],
+        "data": {"b": 20},
+        "body": [{"type": "paragraph", "text": "{{ b }}"}],
+    }
+    doc = DocumentConfig.from_dict(raw)
+    assert not hasattr(doc, "data"), "DocumentConfig 不应有 data 字段"
+    # 未传数据 → 空对象：只取变量默认值，顶层 data 被忽略
+    assert build_context(doc) == {"b": 2}
+    # round-trip 不把 data 吐回来
+    assert "data" not in doc.to_dict()
+
+
 def test_data_keys_shadow_python_dict_methods() -> None:
     """模板取值必须**先按键**：数据里叫 items/values/item 的字段不能被 dict 方法截胡。