docvortex 0.2.1__py3-none-any.whl

docvortex/render/_internal/docx/assets.py

@@ -0,0 +1,202 @@
+"""DOCX renderer 的安全图片素材解析与格式准备。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import PurePosixPath
+import re
+from urllib.parse import urlsplit
+
+from PIL import Image, UnidentifiedImageError
+
+from ...contracts import AssetResolver
+from ....schema import ImagePayloadBlock
+from ....foundation.image_payload import (
+    extract_generated_svg_fallback,
+    parse_image_data_uri_strict,
+    validate_image_sidecar_path,
+)
+
+_PIL_FORMAT_EXTENSIONS = {
+    "BMP": "bmp",
+    "GIF": "gif",
+    "JPEG": "jpg",
+    "PNG": "png",
+    "TIFF": "tiff",
+    "WEBP": "webp",
+}
+_EXTENSION_ALIASES = {
+    "jpeg": "jpg",
+    "jpe": "jpg",
+    "tif": "tiff",
+}
+_SVG_START_RE = re.compile(rb"^(?:\xef\xbb\xbf)?\s*(?:<\?xml\b.*?\?>\s*)?<svg\b", re.IGNORECASE | re.DOTALL)
+
+
+class DocxAssetError(ValueError):
+    """表示 DOCX renderer 无法安全加载或识别图片素材。"""
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedImage:
+    """保存可直接交给 DOCX 的图片字节、格式与像素尺寸。"""
+
+    data: bytes
+    extension: str
+    width_px: int
+    height_px: int
+    svg_data: bytes | None = None
+
+
+def prepare_block_image(
+    block: ImagePayloadBlock,
+    asset_resolver: AssetResolver | None = None,
+) -> PreparedImage:
+    """从图片载荷 block 加载图片，按 sidecar、data URI 的公共优先级选择。"""
+    if not isinstance(block, ImagePayloadBlock):
+        raise TypeError("block must be an ImagePayloadBlock")
+    if block.image_path is not None:
+        return _prepare_relative_asset(block.image_path, asset_resolver)
+    if block.image_base64 is not None:
+        return _prepare_data_uri(block.image_base64)
+    raise DocxAssetError("Image block does not contain image_base64 or image_path")
+
+
+def prepare_html_image(
+    source: str,
+    asset_resolver: AssetResolver | None = None,
+) -> PreparedImage:
+    """从 HTML ``img`` 的 src 加载 data URI 或安全的相对 sidecar 图片。"""
+    if not isinstance(source, str):
+        raise TypeError("HTML image source must be a string")
+    normalized_source = source.strip()
+    if not normalized_source:
+        raise DocxAssetError("HTML image source must not be empty")
+    if normalized_source.lower().startswith("data:"):
+        if not normalized_source.lower().startswith("data:image/"):
+            raise DocxAssetError("Only image data URIs are supported")
+        return _prepare_data_uri(normalized_source)
+    return _prepare_relative_asset(normalized_source, asset_resolver)
+
+
+def prepare_image_bytes(
+    data: bytes,
+    *,
+    declared_extension: str | None = None,
+) -> PreparedImage:
+    """严格解码图片字节，并将 Word 不直接支持的 WebP 在内存中转为 PNG。"""
+    if not isinstance(data, bytes):
+        raise DocxAssetError("Image resolver must return bytes")
+    if not data:
+        raise DocxAssetError("Image payload must not be empty")
+
+    expected_extension = _normalize_extension(declared_extension)
+    if expected_extension == "svg" or _looks_like_svg(data):
+        try:
+            fallback, logical_width, logical_height = extract_generated_svg_fallback(data)
+        except ValueError as exc:
+            raise DocxAssetError("SVG images are not supported unless they are safely generated by DocVortex") from exc
+        prepared = prepare_image_bytes(fallback, declared_extension="png")
+        return PreparedImage(
+            data=prepared.data,
+            extension=prepared.extension,
+            width_px=logical_width,
+            height_px=logical_height,
+            svg_data=data,
+        )
+
+    try:
+        with Image.open(BytesIO(data)) as image:
+            detected_extension = _PIL_FORMAT_EXTENSIONS.get((image.format or "").upper())
+            if detected_extension is None:
+                raise DocxAssetError(f"Unsupported image format: {image.format or 'unknown'}")
+            width_px, height_px = image.size
+            image.load()
+            if expected_extension is not None and expected_extension != detected_extension:
+                raise DocxAssetError(
+                    f"Image bytes do not match declared format: expected {expected_extension}, detected {detected_extension}"
+                )
+            if detected_extension == "webp":
+                return _convert_webp_to_png(image, width_px, height_px)
+    except DocxAssetError:
+        raise
+    except (UnidentifiedImageError, OSError, ValueError) as exc:
+        raise DocxAssetError("Invalid or corrupted image payload") from exc
+
+    return PreparedImage(
+        data=data,
+        extension=detected_extension,
+        width_px=width_px,
+        height_px=height_px,
+    )
+
+
+def _prepare_data_uri(data_uri: str) -> PreparedImage:
+    """严格解析 data URI，并校验 MIME、签名和完整图片数据。"""
+    try:
+        data, extension = parse_image_data_uri_strict(data_uri)
+    except ValueError as exc:
+        raise DocxAssetError(str(exc)) from exc
+    return prepare_image_bytes(data, declared_extension=extension)
+
+
+def _prepare_relative_asset(
+    image_path: str,
+    asset_resolver: AssetResolver | None,
+) -> PreparedImage:
+    """校验相对 sidecar 路径，通过调用方 resolver 读取字节且不访问文件系统或网络。"""
+    parsed_source = urlsplit(image_path)
+    if parsed_source.scheme or parsed_source.netloc:
+        raise DocxAssetError(f"Remote or scheme-based image source is not supported: {image_path}")
+    try:
+        safe_path = validate_image_sidecar_path(image_path)
+    except ValueError as exc:
+        raise DocxAssetError(str(exc)) from exc
+    if asset_resolver is None:
+        raise DocxAssetError(f"asset_resolver is required for image_path: {safe_path}")
+    try:
+        data = asset_resolver(safe_path)
+    except Exception as exc:
+        raise DocxAssetError(f"Failed to resolve image asset: {safe_path}") from exc
+
+    extension = PurePosixPath(safe_path).suffix.removeprefix(".") or None
+    return prepare_image_bytes(data, declared_extension=extension)
+
+
+def _normalize_extension(extension: str | None) -> str | None:
+    """规范化可识别的扩展名；未知扩展名不作为图片格式声明。"""
+    if extension is None:
+        return None
+    normalized = extension.lower().lstrip(".").split("+", 1)[0]
+    normalized = _EXTENSION_ALIASES.get(normalized, normalized)
+    if normalized == "svg":
+        return normalized
+    return normalized if normalized in set(_PIL_FORMAT_EXTENSIONS.values()) else None
+
+
+def _looks_like_svg(data: bytes) -> bool:
+    """识别带可选 BOM/XML 声明的 SVG 字节，以便给出明确的不支持错误。"""
+    return _SVG_START_RE.match(data[:4096]) is not None
+
+
+def _convert_webp_to_png(image: Image.Image, width_px: int, height_px: int) -> PreparedImage:
+    """在内存中把已解码 WebP 转换为 PNG，保留透明通道与像素尺寸。"""
+    output = BytesIO()
+    image.save(output, format="PNG")
+    return PreparedImage(
+        data=output.getvalue(),
+        extension="png",
+        width_px=width_px,
+        height_px=height_px,
+    )
+
+
+__all__ = [
+    "AssetResolver",
+    "DocxAssetError",
+    "PreparedImage",
+    "prepare_block_image",
+    "prepare_html_image",
+    "prepare_image_bytes",
+]

docvortex/render/_internal/docx/inline.py

@@ -0,0 +1,434 @@
+"""Middle JSON 2.0 行内 Span 到 Word run、超链接、书签和 OMML 的写入。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from hashlib import sha1
+import re
+
+from docx.opc.constants import RELATIONSHIP_TYPE
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.text.paragraph import Paragraph
+from docx.text.run import Run
+from docx.shared import Pt, RGBColor
+from lxml import etree
+from loguru import logger
+
+from ....content.inline import inline_plain_text, join_inline_spans
+from ....schema import CodeInlineSpan, EquationInlineSpan, HyperlinkSpan, InlineSpan, TextSpan
+from .math import DocxFormulaError, latex_to_omml
+
+_BOOKMARK_SAFE_RE = re.compile(r"[^A-Za-z0-9_]+")
+_BOOKMARK_MAX_LENGTH = 40
+_INVALID_XML_TEXT_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]")
+_BARE_SCRIPT_RE = re.compile(r"^\s*(?P<marker>[\^_])\s*\{(?P<content>[^{}]+)\}\s*$")
+_VISIBLE_SPACE_STYLES = frozenset({"underline", "strikethrough", "emphasis"})
+_NONBREAKING_SPACE = "\u00a0"
+
+
+@dataclass(frozen=True, slots=True)
+class InlineRenderContext:
+    """保存行内渲染告警所需的 block 定位与书签表。"""
+
+    bookmarks: BookmarkRegistry
+    page_idx: int
+    block_index: int | None
+    block_type: str
+
+    def location(self) -> str:
+        """返回稳定、可读的 page/block 定位文本。"""
+        return f"page_idx={self.page_idx}, block_index={self.block_index}, block_type={self.block_type}"
+
+
+class BookmarkRegistry:
+    """把 MiddleJson anchor 映射为合法且唯一的 Word bookmark 名称。"""
+
+    def __init__(self, anchors: Iterable[str]) -> None:
+        """预注册全部 anchor，保证标题、目录和脚注前向引用可提前解析。"""
+        self._names: dict[str, str] = {}
+        self._attached: set[str] = set()
+        self._used_names: set[str] = set()
+        self._next_id = 0
+        for anchor in anchors:
+            normalized = anchor.strip()
+            if normalized and normalized not in self._names:
+                self._names[normalized] = self._allocate_name(normalized)
+
+    def _allocate_name(self, anchor: str) -> str:
+        """为一个原始 anchor 分配满足 Word 限制的确定性名称。"""
+        base = _BOOKMARK_SAFE_RE.sub("_", anchor).strip("_")
+        if not base or not base[0].isalpha():
+            base = f"b_{base}"
+        candidate = base[:_BOOKMARK_MAX_LENGTH]
+        if candidate not in self._used_names:
+            self._used_names.add(candidate)
+            return candidate
+
+        digest = sha1(anchor.encode("utf-8")).hexdigest()[:8]
+        prefix_length = _BOOKMARK_MAX_LENGTH - len(digest) - 1
+        candidate = f"{base[:prefix_length]}_{digest}"
+        ordinal = 1
+        while candidate in self._used_names:
+            suffix = f"_{ordinal}"
+            candidate = f"{base[: _BOOKMARK_MAX_LENGTH - len(suffix)]}{suffix}"
+            ordinal += 1
+        self._used_names.add(candidate)
+        return candidate
+
+    def resolve(self, anchor: str | None) -> str | None:
+        """解析已注册 anchor；空值或未知 anchor 返回 None。"""
+        if not anchor:
+            return None
+        return self._names.get(anchor.strip())
+
+    def attach(self, paragraph: Paragraph, anchor: str | None) -> bool:
+        """把 anchor bookmark 包围当前段落内容；重复正文 anchor 只保留首个。"""
+        normalized = (anchor or "").strip()
+        name = self.resolve(normalized)
+        if name is None:
+            return False
+        if normalized in self._attached:
+            logger.warning("Duplicate DOCX bookmark anchor ignored: {}", normalized)
+            return False
+
+        bookmark_id = str(self._next_id)
+        self._next_id += 1
+        start = OxmlElement("w:bookmarkStart")
+        start.set(qn("w:id"), bookmark_id)
+        start.set(qn("w:name"), name)
+        end = OxmlElement("w:bookmarkEnd")
+        end.set(qn("w:id"), bookmark_id)
+
+        paragraph_xml = paragraph._p
+        insert_at = 1 if paragraph_xml.pPr is not None else 0
+        paragraph_xml.insert(insert_at, start)
+        paragraph_xml.append(end)
+        self._attached.add(normalized)
+        return True
+
+
+def append_inline_content(
+    paragraph: Paragraph,
+    content: list[InlineSpan],
+    *,
+    context: InlineRenderContext,
+) -> None:
+    """把一段 MiddleJson 行内 Span 追加到 Word 段落。"""
+    append_inline_spans(paragraph, content, context=context)
+
+
+def append_joined_inline_contents(
+    paragraph: Paragraph,
+    contents: list[list[InlineSpan]],
+    *,
+    context: InlineRenderContext,
+) -> None:
+    """按共享边界规则合并续段，并把结构化行内 Span 写入 Word。"""
+    append_inline_spans(paragraph, join_inline_spans(contents), context=context)
+
+
+def append_inline_spans(
+    paragraph: Paragraph,
+    spans: list[InlineSpan],
+    *,
+    context: InlineRenderContext,
+    inherited_styles: tuple[str, ...] = (),
+) -> None:
+    """把行内 Span 写入段落，同时保留样式、链接与公式语义。"""
+    _append_spans_to_container(
+        paragraph._p,
+        paragraph,
+        spans,
+        context=context,
+        inherited_styles=inherited_styles,
+        hyperlink=False,
+    )
+
+
+def append_internal_link(
+    paragraph: Paragraph,
+    label_spans: list[InlineSpan],
+    *,
+    anchor: str | None,
+    context: InlineRenderContext,
+) -> bool:
+    """把目录标签写为内部链接；目标缺失时退回普通行内内容。"""
+    bookmark_name = context.bookmarks.resolve(anchor)
+    if bookmark_name is None:
+        append_inline_spans(paragraph, label_spans, context=context)
+        if anchor:
+            logger.warning("Unmatched DOCX index anchor: {} ({})", anchor, context.location())
+        return False
+
+    hyperlink = OxmlElement("w:hyperlink")
+    hyperlink.set(qn("w:anchor"), bookmark_name)
+    hyperlink.set(qn("w:history"), "1")
+    paragraph._p.append(hyperlink)
+    _append_spans_to_container(
+        hyperlink,
+        paragraph,
+        label_spans,
+        context=context,
+        inherited_styles=(),
+        hyperlink=True,
+    )
+    return True
+
+
+def _append_spans_to_container(
+    container: etree._Element,
+    paragraph: Paragraph,
+    spans: list[InlineSpan],
+    *,
+    context: InlineRenderContext,
+    inherited_styles: tuple[str, ...],
+    hyperlink: bool,
+) -> None:
+    """递归写入一个段落或 hyperlink XML 容器。"""
+    for span in spans:
+        if isinstance(span, TextSpan):
+            styles = tuple(dict.fromkeys((*inherited_styles, *span.styles)))
+            _append_text_run(
+                container,
+                paragraph,
+                span.content,
+                styles=styles,
+                hyperlink=hyperlink,
+                context=context,
+            )
+            continue
+        if isinstance(span, CodeInlineSpan):
+            run = _append_text_run(
+                container,
+                paragraph,
+                span.content,
+                styles=inherited_styles,
+                hyperlink=hyperlink,
+                context=context,
+            )
+            run.font.name = "Courier New"
+            run.font.size = Pt(9)
+            continue
+        if isinstance(span, EquationInlineSpan):
+            bare_script = _BARE_SCRIPT_RE.fullmatch(span.content)
+            if bare_script is not None:
+                script_style = "superscript" if bare_script.group("marker") == "^" else "subscript"
+                styles = tuple(dict.fromkeys((*inherited_styles, script_style)))
+                _append_text_run(
+                    container,
+                    paragraph,
+                    bare_script.group("content"),
+                    styles=styles,
+                    hyperlink=hyperlink,
+                    context=context,
+                )
+                continue
+            if hyperlink:
+                _append_text_run(
+                    container,
+                    paragraph,
+                    span.content,
+                    styles=inherited_styles,
+                    hyperlink=True,
+                    context=context,
+                )
+                continue
+            try:
+                container.append(latex_to_omml(span.content, display=False))
+            except DocxFormulaError as exc:
+                logger.warning("DOCX inline formula fallback: {} ({})", exc, context.location())
+                _append_text_run(
+                    container,
+                    paragraph,
+                    span.content,
+                    styles=inherited_styles,
+                    hyperlink=False,
+                    formula_fallback=True,
+                    context=context,
+                )
+            continue
+        if isinstance(span, HyperlinkSpan):
+            if hyperlink or not span.url or span.url == ".":
+                _append_spans_to_container(
+                    container,
+                    paragraph,
+                    list(span.content),
+                    context=context,
+                    inherited_styles=inherited_styles,
+                    hyperlink=hyperlink,
+                )
+                continue
+            if span.url.startswith("#"):
+                _append_inline_internal_link(
+                    container,
+                    paragraph,
+                    span,
+                    context=context,
+                    inherited_styles=inherited_styles,
+                )
+                continue
+            _append_external_link(
+                paragraph,
+                span,
+                context=context,
+                inherited_styles=inherited_styles,
+            )
+            continue
+        raise TypeError(f"Unsupported inline span: {type(span).__name__}")
+
+
+def _append_inline_internal_link(
+    container: etree._Element,
+    paragraph: Paragraph,
+    span: HyperlinkSpan,
+    *,
+    context: InlineRenderContext,
+    inherited_styles: tuple[str, ...],
+) -> None:
+    """把 #anchor 行内链接写为 Word bookmark 跳转，未知目标退化为普通文本。"""
+    anchor = span.url[1:].strip()
+    bookmark_name = context.bookmarks.resolve(anchor)
+    if bookmark_name is None:
+        _append_spans_to_container(
+            container,
+            paragraph,
+            list(span.content),
+            context=context,
+            inherited_styles=inherited_styles,
+            hyperlink=False,
+        )
+        return
+
+    internal_link = OxmlElement("w:hyperlink")
+    internal_link.set(qn("w:anchor"), bookmark_name)
+    internal_link.set(qn("w:history"), "1")
+    container.append(internal_link)
+    _append_spans_to_container(
+        internal_link,
+        paragraph,
+        list(span.content),
+        context=context,
+        inherited_styles=inherited_styles,
+        hyperlink=True,
+    )
+
+
+def _append_external_link(
+    paragraph: Paragraph,
+    span: HyperlinkSpan,
+    *,
+    context: InlineRenderContext,
+    inherited_styles: tuple[str, ...],
+) -> None:
+    """创建外部 hyperlink relationship，并写入完整标签内容。"""
+    relation_id = paragraph.part.relate_to(
+        sanitize_xml_text(span.url, context=context),
+        RELATIONSHIP_TYPE.HYPERLINK,
+        is_external=True,
+    )
+    hyperlink = OxmlElement("w:hyperlink")
+    hyperlink.set(qn("r:id"), relation_id)
+    paragraph._p.append(hyperlink)
+    _append_spans_to_container(
+        hyperlink,
+        paragraph,
+        list(span.content),
+        context=context,
+        inherited_styles=inherited_styles,
+        hyperlink=True,
+    )
+
+
+def _append_text_run(
+    container: etree._Element,
+    paragraph: Paragraph,
+    content: str,
+    *,
+    styles: tuple[str, ...],
+    hyperlink: bool,
+    context: InlineRenderContext,
+    formula_fallback: bool = False,
+) -> Run:
+    """向 XML 容器追加一个 run，并应用 MiddleJson 行内样式。"""
+    run_xml = OxmlElement("w:r")
+    container.append(run_xml)
+    run = Run(run_xml, paragraph)
+    sanitized = sanitize_xml_text(content, context=context)
+    run.text = _make_visible_style_spaces(sanitized, styles)
+    _apply_run_styles(run, styles)
+    if hyperlink:
+        run.font.color.rgb = _rgb_color("0563C1")
+        run.underline = True
+    if formula_fallback:
+        run.font.name = "Courier New"
+        run.font.size = Pt(9)
+        run.font.color.rgb = _rgb_color("555555")
+    return run
+
+
+def _make_visible_style_spaces(content: str, styles: tuple[str, ...]) -> str:
+    """把可见样式 run 的边界 ASCII 空格等量转为 NBSP，避免 Word 隐藏装饰线。"""
+    if not content or not _VISIBLE_SPACE_STYLES.intersection(styles):
+        return content
+
+    leading_count = len(content) - len(content.lstrip(" "))
+    trailing_count = len(content) - len(content.rstrip(" "))
+    if leading_count == 0 and trailing_count == 0:
+        return content
+    if leading_count + trailing_count >= len(content):
+        return _NONBREAKING_SPACE * len(content)
+
+    content_end = len(content) - trailing_count if trailing_count else len(content)
+    return _NONBREAKING_SPACE * leading_count + content[leading_count:content_end] + _NONBREAKING_SPACE * trailing_count
+
+
+def sanitize_xml_text(content: str, *, context: InlineRenderContext) -> str:
+    """把 XML 1.0 禁止字符替换为 U+FFFD，并记录可定位的 renderer 告警。"""
+    sanitized, replacement_count = _INVALID_XML_TEXT_RE.subn("\ufffd", content)
+    if replacement_count:
+        logger.warning(
+            "DOCX replaced {} XML-incompatible character(s) with U+FFFD ({})",
+            replacement_count,
+            context.location(),
+        )
+    return sanitized
+
+
+def _apply_run_styles(run: Run, styles: tuple[str, ...]) -> None:
+    """把已解析的行内样式应用到 Word run。"""
+    style_set = set(styles)
+    run.bold = "bold" in style_set
+    run.italic = "italic" in style_set
+    run.underline = "underline" in style_set
+    run.font.strike = "strikethrough" in style_set
+    run.font.superscript = "superscript" in style_set
+    run.font.subscript = "subscript" in style_set and "superscript" not in style_set
+    if "emphasis" in style_set:
+        run_properties = run._element.get_or_add_rPr()
+        emphasis = OxmlElement("w:em")
+        emphasis.set(qn("w:val"), "underDot")
+        run_properties.append(emphasis)
+
+
+def _rgb_color(value: str) -> RGBColor:
+    """延迟构造 RGBColor，避免在模块常量阶段加载额外对象。"""
+    return RGBColor.from_string(value)
+
+
+def plain_inline_text(content: list[InlineSpan]) -> str:
+    """提取一段 MiddleJson 行内内容的可见文本。"""
+    return inline_plain_text(content)
+
+
+__all__ = [
+    "BookmarkRegistry",
+    "InlineRenderContext",
+    "append_inline_content",
+    "append_inline_spans",
+    "append_internal_link",
+    "append_joined_inline_contents",
+    "plain_inline_text",
+    "sanitize_xml_text",
+]