docvortex 0.2.1__py3-none-any.whl

docvortex/render/_internal/epub/assets.py

@@ -0,0 +1,173 @@
+"""EPUB renderer 的图片解析、规范化与包内去重。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+from io import BytesIO
+from pathlib import PurePosixPath
+import re
+from urllib.parse import unquote, urlsplit
+
+from PIL import Image, UnidentifiedImageError
+
+from ...contracts import AssetResolver
+from ....schema import ImagePayloadBlock
+from ....foundation.image_payload import (
+    MAX_IMAGE_DATA_URI_BYTES,
+    MAX_IMAGE_PAYLOAD_BYTES,
+    extract_generated_svg_fallback,
+    normalize_image_extension,
+    parse_image_data_uri_strict,
+    validate_decoded_raster_size,
+    validate_image_sidecar_path,
+)
+
+_SVG_START_RE = re.compile(rb"^(?:\xef\xbb\xbf)?\s*(?:<\?xml\b.*?\?>\s*)?<svg\b", re.IGNORECASE | re.DOTALL)
+_PASSTHROUGH_FORMATS = {"gif", "jpg", "png"}
+_MEDIA_TYPES = {
+    "gif": "image/gif",
+    "jpg": "image/jpeg",
+    "png": "image/png",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class EpubAsset:
+    """保存一个已规范化且可写入 EPUB 的图片资源。"""
+
+    file_name: str
+    media_type: str
+    data: bytes
+
+
+class EpubAssetRegistry:
+    """按内容哈希登记 EPUB 图片，并隔离所有外部素材读取。"""
+
+    def __init__(self, asset_resolver: AssetResolver | None) -> None:
+        """保存显式 resolver，并初始化来源缓存与内容去重表。"""
+        self._asset_resolver = asset_resolver
+        self._source_cache: dict[str, str | None] = {}
+        self._assets: dict[str, EpubAsset] = {}
+
+    @property
+    def assets(self) -> tuple[EpubAsset, ...]:
+        """按稳定文件名顺序返回所有已登记包内图片。"""
+        return tuple(self._assets[name] for name in sorted(self._assets))
+
+    def resolve_block(self, block: ImagePayloadBlock) -> str | None:
+        """按 sidecar、data URI、远程 URL 优先级解析一个图片 block。"""
+        if block.image_path:
+            resolved = self._resolve_relative_path(block.image_path)
+            if resolved is not None:
+                return resolved
+        if block.image_base64:
+            resolved = self._resolve_data_uri(block.image_base64)
+            if resolved is not None:
+                return resolved
+        # EPUB 图片必须位于容器中；远程 image_url 只作为不可下载的最后候选跳过。
+        return None
+
+    def resolve_embedded_source(self, source: str) -> str | None:
+        """解析富 HTML img 的 data URI 或安全相对 sidecar，拒绝网络来源。"""
+        normalized = source.strip()
+        if not normalized:
+            return None
+        if normalized.lower().startswith("data:"):
+            return self._resolve_data_uri(normalized)
+        try:
+            parsed = urlsplit(normalized)
+        except ValueError:
+            return None
+        if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment or normalized.startswith(("/", "\\")):
+            return None
+        decoded_path = unquote(parsed.path)
+        try:
+            safe_path = validate_image_sidecar_path(decoded_path)
+        except ValueError:
+            return None
+        return self._resolve_relative_path(safe_path)
+
+    def _resolve_relative_path(self, image_path: str) -> str | None:
+        """通过显式 resolver 读取相对图片，失败时返回可降级的空结果。"""
+        cache_key = f"path:{image_path}"
+        if cache_key in self._source_cache:
+            return self._source_cache[cache_key]
+        if self._asset_resolver is None:
+            self._source_cache[cache_key] = None
+            return None
+        try:
+            safe_path = validate_image_sidecar_path(image_path)
+            data = self._asset_resolver(safe_path)
+            if not isinstance(data, bytes):
+                raise TypeError("asset_resolver must return bytes")
+            declared_extension = PurePosixPath(safe_path).suffix.removeprefix(".") or None
+            href = self._register_prepared(data, declared_extension=declared_extension)
+        except Exception:
+            href = None
+        self._source_cache[cache_key] = href
+        return href
+
+    def _resolve_data_uri(self, data_uri: str) -> str | None:
+        """严格解码图片 data URI，失败时返回可降级的空结果。"""
+        if len(data_uri) > MAX_IMAGE_DATA_URI_BYTES:
+            return None
+        cache_key = f"data:{hashlib.sha256(data_uri.encode('utf-8', errors='replace')).hexdigest()}"
+        if cache_key in self._source_cache:
+            return self._source_cache[cache_key]
+        try:
+            data, extension = parse_image_data_uri_strict(data_uri)
+            href = self._register_prepared(data, declared_extension=extension)
+        except (OSError, TypeError, ValueError):
+            href = None
+        self._source_cache[cache_key] = href
+        return href
+
+    def _register_prepared(self, data: bytes, *, declared_extension: str | None) -> str:
+        """规范化图片格式，按 SHA-256 去重并返回正文相对 href。"""
+        normalized, extension = _prepare_epub_image(data, declared_extension=declared_extension)
+        digest = hashlib.sha256(normalized).hexdigest()
+        file_name = f"{digest}.{extension}"
+        if file_name not in self._assets:
+            self._assets[file_name] = EpubAsset(
+                file_name=file_name,
+                media_type=_MEDIA_TYPES[extension],
+                data=normalized,
+            )
+        return f"../assets/{file_name}"
+
+
+def _prepare_epub_image(data: bytes, *, declared_extension: str | None) -> tuple[bytes, str]:
+    """校验图片字节，并把非 PNG/JPEG/GIF 栅格统一转为 PNG。"""
+    if not isinstance(data, bytes) or not data:
+        raise ValueError("Image payload must contain bytes")
+    if len(data) > MAX_IMAGE_PAYLOAD_BYTES:
+        raise ValueError("Image payload exceeds its byte limit")
+    expected = normalize_image_extension(declared_extension or "") or None
+    if expected == "svg" or _SVG_START_RE.match(data[:4096]) is not None:
+        if expected not in {None, "svg"}:
+            raise ValueError("Image bytes do not match the declared format")
+        fallback, _, _ = extract_generated_svg_fallback(data)
+        return _prepare_epub_image(fallback, declared_extension="png")
+
+    try:
+        with Image.open(BytesIO(data)) as image:
+            detected = normalize_image_extension(image.format or "")
+            if not detected:
+                raise ValueError("Unsupported image format")
+            validate_decoded_raster_size(*image.size)
+            image.load()
+            if expected is not None and expected != detected:
+                raise ValueError("Image bytes do not match the declared format")
+            if detected in _PASSTHROUGH_FORMATS:
+                return data, detected
+            has_alpha = "A" in image.getbands() or (image.mode == "P" and "transparency" in image.info)
+            converted = image.convert("RGBA" if has_alpha else "RGB")
+            output = BytesIO()
+            converted.save(output, format="PNG")
+            return output.getvalue(), "png"
+    except (Image.DecompressionBombError, UnidentifiedImageError, OSError, ValueError) as exc:
+        raise ValueError("Invalid or unsupported image payload") from exc
+
+
+__all__ = ["EpubAsset", "EpubAssetRegistry"]

docvortex/render/_internal/epub/package.py

@@ -0,0 +1,249 @@
+"""EPUB 3.3 的元数据 XML、导航文档与确定性 OCF 打包。"""
+
+from __future__ import annotations
+
+import calendar
+from dataclasses import dataclass, field
+from datetime import datetime
+from io import BytesIO
+from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile, ZipInfo
+
+from lxml import etree
+
+from .assets import EpubAsset
+
+_CONTAINER_NS = "urn:oasis:names:tc:opendocument:xmlns:container"
+_DC_NS = "http://purl.org/dc/elements/1.1/"
+_EPUB_NS = "http://www.idpf.org/2007/ops"
+_OPF_NS = "http://www.idpf.org/2007/opf"
+_XHTML_NS = "http://www.w3.org/1999/xhtml"
+_XML_NS = "http://www.w3.org/XML/1998/namespace"
+_EPUB_MIME = b"application/epub+zip"
+_CONTENT_PATH = "EPUB/text/content.xhtml"
+_STYLE_PATH = "EPUB/styles/docvortex.css"
+
+
+@dataclass(frozen=True, slots=True)
+class EpubMetadata:
+    """保存 package document 所需的规范化书籍元数据。"""
+
+    title: str
+    authors: tuple[str, ...]
+    language: str
+    identifier: str
+    modified_at: datetime
+
+
+@dataclass(slots=True)
+class NavigationItem:
+    """保存 EPUB toc nav 中一个可链接的层级条目。"""
+
+    title: str
+    href: str
+    children: list[NavigationItem] = field(default_factory=list)
+
+
+def build_epub_package(
+    *,
+    metadata: EpubMetadata,
+    content_xhtml: bytes,
+    navigation: list[NavigationItem],
+    stylesheet: bytes,
+    assets: tuple[EpubAsset, ...],
+    has_mathml: bool,
+) -> bytes:
+    """在内存中按固定成员顺序构造完整 EPUB 3.3 容器。"""
+    container_xml = _build_container_xml()
+    navigation_xhtml = _build_navigation_xhtml(metadata, navigation)
+    package_document = _build_package_document(metadata, assets, has_mathml=has_mathml)
+    output = BytesIO()
+    with ZipFile(output, "w", compression=ZIP_DEFLATED, compresslevel=9) as archive:
+        _write_member(archive, "mimetype", _EPUB_MIME, metadata.modified_at, compression=ZIP_STORED)
+        _write_member(archive, "META-INF/container.xml", container_xml, metadata.modified_at)
+        _write_member(archive, "EPUB/package.opf", package_document, metadata.modified_at)
+        _write_member(archive, "EPUB/nav.xhtml", navigation_xhtml, metadata.modified_at)
+        _write_member(archive, _CONTENT_PATH, content_xhtml, metadata.modified_at)
+        _write_member(archive, _STYLE_PATH, stylesheet, metadata.modified_at)
+        for asset in assets:
+            _write_member(archive, f"EPUB/assets/{asset.file_name}", asset.data, metadata.modified_at)
+    return output.getvalue()
+
+
+def _build_container_xml() -> bytes:
+    """生成指向唯一 OPF package document 的 container.xml。"""
+    root = etree.Element(f"{{{_CONTAINER_NS}}}container", nsmap={None: _CONTAINER_NS}, version="1.0")
+    rootfiles = etree.SubElement(root, f"{{{_CONTAINER_NS}}}rootfiles")
+    etree.SubElement(
+        rootfiles,
+        f"{{{_CONTAINER_NS}}}rootfile",
+        attrib={
+            "full-path": "EPUB/package.opf",
+            "media-type": "application/oebps-package+xml",
+        },
+    )
+    return _serialize_xml(root)
+
+
+def _build_package_document(metadata: EpubMetadata, assets: tuple[EpubAsset, ...], *, has_mathml: bool) -> bytes:
+    """生成包含必需元数据、完整 manifest 与单正文 spine 的 OPF。"""
+    root = etree.Element(
+        f"{{{_OPF_NS}}}package",
+        nsmap={None: _OPF_NS, "dc": _DC_NS},
+        attrib={
+            "version": "3.0",
+            "unique-identifier": "pub-id",
+            f"{{{_XML_NS}}}lang": metadata.language,
+        },
+    )
+    metadata_element = etree.SubElement(root, f"{{{_OPF_NS}}}metadata")
+    identifier = etree.SubElement(metadata_element, f"{{{_DC_NS}}}identifier", id="pub-id")
+    identifier.text = metadata.identifier
+    title = etree.SubElement(metadata_element, f"{{{_DC_NS}}}title")
+    title.text = metadata.title
+    language = etree.SubElement(metadata_element, f"{{{_DC_NS}}}language")
+    language.text = metadata.language
+    for author in metadata.authors:
+        creator = etree.SubElement(metadata_element, f"{{{_DC_NS}}}creator")
+        creator.text = author
+    modified = etree.SubElement(metadata_element, f"{{{_OPF_NS}}}meta", property="dcterms:modified")
+    modified.text = metadata.modified_at.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    manifest = etree.SubElement(root, f"{{{_OPF_NS}}}manifest")
+    etree.SubElement(
+        manifest,
+        f"{{{_OPF_NS}}}item",
+        id="nav",
+        href="nav.xhtml",
+        attrib={"media-type": "application/xhtml+xml", "properties": "nav"},
+    )
+    content_attributes = {
+        "id": "content",
+        "href": "text/content.xhtml",
+        "media-type": "application/xhtml+xml",
+    }
+    if has_mathml:
+        content_attributes["properties"] = "mathml"
+    etree.SubElement(manifest, f"{{{_OPF_NS}}}item", attrib=content_attributes)
+    etree.SubElement(
+        manifest,
+        f"{{{_OPF_NS}}}item",
+        id="style",
+        href="styles/docvortex.css",
+        attrib={"media-type": "text/css"},
+    )
+    for position, asset in enumerate(assets, start=1):
+        etree.SubElement(
+            manifest,
+            f"{{{_OPF_NS}}}item",
+            id=f"asset-{position}",
+            href=f"assets/{asset.file_name}",
+            attrib={"media-type": asset.media_type},
+        )
+    spine = etree.SubElement(root, f"{{{_OPF_NS}}}spine")
+    etree.SubElement(spine, f"{{{_OPF_NS}}}itemref", idref="content")
+    return _serialize_xml(root)
+
+
+def _build_navigation_xhtml(metadata: EpubMetadata, navigation: list[NavigationItem]) -> bytes:
+    """生成恰含一个 toc nav 和一个 landmarks nav 的 EPUB 导航文档。"""
+    root = etree.Element(
+        f"{{{_XHTML_NS}}}html",
+        nsmap={None: _XHTML_NS, "epub": _EPUB_NS},
+        attrib={f"{{{_XML_NS}}}lang": metadata.language, "lang": metadata.language},
+    )
+    head = etree.SubElement(root, f"{{{_XHTML_NS}}}head")
+    etree.SubElement(head, f"{{{_XHTML_NS}}}meta", charset="utf-8")
+    title = etree.SubElement(head, f"{{{_XHTML_NS}}}title")
+    title.text = f"{metadata.title} — Table of Contents"
+    etree.SubElement(
+        head,
+        f"{{{_XHTML_NS}}}link",
+        rel="stylesheet",
+        href="styles/docvortex.css",
+        type="text/css",
+    )
+    body = etree.SubElement(root, f"{{{_XHTML_NS}}}body")
+    toc = etree.SubElement(
+        body,
+        f"{{{_XHTML_NS}}}nav",
+        id="toc",
+        role="doc-toc",
+        attrib={f"{{{_EPUB_NS}}}type": "toc"},
+    )
+    heading = etree.SubElement(toc, f"{{{_XHTML_NS}}}h1")
+    heading.text = "Table of Contents"
+    ordered = etree.SubElement(toc, f"{{{_XHTML_NS}}}ol")
+    for item in navigation:
+        _append_navigation_item(ordered, item)
+
+    landmarks = etree.SubElement(
+        body,
+        f"{{{_XHTML_NS}}}nav",
+        id="landmarks",
+        hidden="hidden",
+        attrib={f"{{{_EPUB_NS}}}type": "landmarks"},
+    )
+    landmarks_heading = etree.SubElement(landmarks, f"{{{_XHTML_NS}}}h2")
+    landmarks_heading.text = "Landmarks"
+    landmarks_list = etree.SubElement(landmarks, f"{{{_XHTML_NS}}}ol")
+    item = etree.SubElement(landmarks_list, f"{{{_XHTML_NS}}}li")
+    link = etree.SubElement(
+        item,
+        f"{{{_XHTML_NS}}}a",
+        href="text/content.xhtml#content-start",
+        attrib={f"{{{_EPUB_NS}}}type": "bodymatter"},
+    )
+    link.text = "Start of Content"
+    return _serialize_xml(root, doctype="<!DOCTYPE html>")
+
+
+def _append_navigation_item(parent: etree._Element, item: NavigationItem) -> None:
+    """递归把一个导航条目及其子项写入有序列表。"""
+    entry = etree.SubElement(parent, f"{{{_XHTML_NS}}}li")
+    link = etree.SubElement(entry, f"{{{_XHTML_NS}}}a", href=item.href)
+    link.text = item.title
+    if item.children:
+        nested = etree.SubElement(entry, f"{{{_XHTML_NS}}}ol")
+        for child in item.children:
+            _append_navigation_item(nested, child)
+
+
+def _serialize_xml(root: etree._Element, *, doctype: str | None = None) -> bytes:
+    """以 UTF-8 XML 声明和稳定缩进序列化一个 EPUB XML 文档。"""
+    etree.indent(root, space="  ")
+    return etree.tostring(
+        root,
+        encoding="utf-8",
+        xml_declaration=True,
+        doctype=doctype,
+        pretty_print=True,
+    )
+
+
+def _write_member(
+    archive: ZipFile,
+    name: str,
+    data: bytes,
+    modified_at: datetime,
+    *,
+    compression: int = ZIP_DEFLATED,
+) -> None:
+    """用固定权限、无 extra 字段和规范时间写入一个 OCF ZIP 成员。"""
+    info = ZipInfo(name, date_time=_zip_datetime(modified_at))
+    info.compress_type = compression
+    info.create_system = 3
+    info.external_attr = 0o100644 << 16
+    info.extra = b""
+    info.comment = b""
+    archive.writestr(info, data)
+
+
+def _zip_datetime(modified_at: datetime) -> tuple[int, int, int, int, int, int]:
+    """把 UTC 修改时间约束到 ZIP DOS 时间范围并截断到双秒。"""
+    year = min(max(modified_at.year, 1980), 2107)
+    day = min(modified_at.day, calendar.monthrange(year, modified_at.month)[1])
+    second = modified_at.second - modified_at.second % 2
+    return year, modified_at.month, day, modified_at.hour, modified_at.minute, second
+
+
+__all__ = ["EpubMetadata", "NavigationItem", "build_epub_package"]