docvortex 0.2.1__py3-none-any.whl

docvortex/analyzers/native/office/odf/package.py

@@ -0,0 +1,270 @@
+"""受限读取 OpenDocument ZIP 包及 XML part。"""
+
+from __future__ import annotations
+
+import posixpath
+from io import BytesIO
+from pathlib import PurePosixPath
+from urllib.parse import unquote, urlsplit
+from zipfile import BadZipFile, ZipFile, ZipInfo
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from .constants import (
+    MAX_ASSET_TOTAL_BYTES,
+    MAX_ENTRY_BYTES,
+    MAX_ENTRY_COUNT,
+    MAX_TOTAL_BYTES,
+    MAX_XML_DEPTH,
+    MAX_XML_NODES,
+    ODF_BODY_BY_SUFFIX,
+    ODF_MIME_BY_SUFFIX,
+    ODF_SUFFIX_BY_MIME,
+    OdfSuffix,
+    qname,
+)
+from .errors import OdfEncryptedError, OdfParseError, OdfResourceLimitError
+
+
+def _xml_parser() -> etree.XMLParser:
+    """为每次 part 解析新建禁用实体、DTD 和网络的 XML parser。"""
+    return etree.XMLParser(
+        resolve_entities=False,
+        load_dtd=False,
+        no_network=True,
+        recover=False,
+        remove_blank_text=False,
+        huge_tree=False,
+    )
+
+
+class OdfPackage:
+    """在固定资源预算内读取一个 OpenDocument ZIP 包。"""
+
+    def __init__(self, file_bytes: bytes) -> None:
+        """打开内存包并在读取正文前完成中央目录安全校验。"""
+        try:
+            self._zip = ZipFile(BytesIO(file_bytes))
+        except (BadZipFile, OSError, ValueError) as exc:
+            raise OdfParseError(f"Malformed ODF package: {exc}") from exc
+        try:
+            self._infos = self._validate_members(self._zip.infolist())
+        except Exception:
+            self._zip.close()
+            raise
+        self._cache: dict[str, bytes] = {}
+        self._asset_bytes = 0
+        self._asset_parts: set[str] = set()
+        self._manifest_media_types: dict[str, str] | None = None
+
+    @staticmethod
+    def _validate_members(infos: list[ZipInfo]) -> dict[str, ZipInfo]:
+        """校验成员数量、解压体积、路径与重名，避免包级歧义。"""
+        if len(infos) > MAX_ENTRY_COUNT:
+            raise OdfResourceLimitError(f"ODF resource limit exceeded: max_entry_count={MAX_ENTRY_COUNT}")
+        total_size = 0
+        members: dict[str, ZipInfo] = {}
+        for info in infos:
+            name = info.filename
+            if not OdfPackage._is_safe_member_name(name):
+                raise OdfParseError(f"Malformed ODF package: unsafe member path {name!r}")
+            if name in members:
+                raise OdfParseError(f"Malformed ODF package: duplicate member {name!r}")
+            if info.file_size > MAX_ENTRY_BYTES:
+                raise OdfResourceLimitError(
+                    f"ODF resource limit exceeded: member {name!r} exceeds max_entry_bytes={MAX_ENTRY_BYTES}"
+                )
+            total_size += info.file_size
+            if total_size > MAX_TOTAL_BYTES:
+                raise OdfResourceLimitError(f"ODF resource limit exceeded: max_total_bytes={MAX_TOTAL_BYTES}")
+            members[name] = info
+        return members
+
+    @staticmethod
+    def _is_safe_member_name(name: str) -> bool:
+        """判断 ZIP 成员是否为无反斜杠、无绝对路径和上跳段的 POSIX 路径。"""
+        if not name or "\x00" in name or "\\" in name or name.startswith("/"):
+            return False
+        parts = PurePosixPath(name).parts
+        return bool(parts) and all(part not in {"", ".", ".."} for part in parts)
+
+    def has_part(self, part_name: str) -> bool:
+        """返回包内是否存在指定规范成员。"""
+        return part_name in self._infos
+
+    def read_part(self, part_name: str, *, required: bool = False, asset: bool = False) -> bytes | None:
+        """读取一个已校验成员，并对累计图片资源执行独立限制。"""
+        info = self._infos.get(part_name)
+        if info is None:
+            if required:
+                raise OdfParseError(f"Malformed ODF package: missing required part {part_name!r}")
+            return None
+        if part_name in self._cache:
+            data = self._cache[part_name]
+            if asset:
+                self._charge_asset(part_name, len(data))
+            return data
+        try:
+            data = self._zip.read(info)
+        except (BadZipFile, OSError, RuntimeError, ValueError) as exc:
+            if required:
+                raise OdfParseError(f"Malformed ODF package: cannot read {part_name!r}: {exc}") from exc
+            return None
+        if len(data) > MAX_ENTRY_BYTES:
+            raise OdfResourceLimitError(
+                f"ODF resource limit exceeded: member {part_name!r} exceeds max_entry_bytes={MAX_ENTRY_BYTES}"
+            )
+        if asset:
+            self._charge_asset(part_name, len(data))
+        self._cache[part_name] = data
+        return data
+
+    def _charge_asset(self, part_name: str, byte_count: int) -> None:
+        """按唯一资源成员累计保留字节，重复引用不重复计费。"""
+        if part_name in self._asset_parts:
+            return
+        self._asset_parts.add(part_name)
+        self._asset_bytes += byte_count
+        if self._asset_bytes > MAX_ASSET_TOTAL_BYTES:
+            raise OdfResourceLimitError(f"ODF resource limit exceeded: max_asset_total_bytes={MAX_ASSET_TOTAL_BYTES}")
+
+    def xml_part(self, part_name: str, *, required: bool = False) -> etree._Element | None:
+        """禁用实体和网络后解析 XML，并校验节点数及最大深度。"""
+        data = self.read_part(part_name, required=required)
+        if data is None:
+            return None
+        try:
+            root = etree.fromstring(data, parser=_xml_parser())
+        except (etree.XMLSyntaxError, ValueError) as exc:
+            if required:
+                raise OdfParseError(f"Malformed ODF package: invalid XML part {part_name!r}: {exc}") from exc
+            return None
+        if root.getroottree().docinfo.doctype:
+            raise OdfParseError(f"Malformed ODF package: DTD is not allowed in {part_name!r}")
+        self._validate_xml_shape(root, part_name)
+        return root
+
+    @staticmethod
+    def _validate_xml_shape(root: etree._Element, part_name: str) -> None:
+        """迭代统计 XML 节点与深度，避免深递归或超大 DOM 继续传播。"""
+        node_count = 0
+        stack: list[tuple[etree._Element, int]] = [(root, 1)]
+        while stack:
+            element, depth = stack.pop()
+            node_count += 1
+            if node_count > MAX_XML_NODES:
+                raise OdfResourceLimitError(f"ODF resource limit exceeded: {part_name!r} exceeds max_xml_nodes={MAX_XML_NODES}")
+            if depth > MAX_XML_DEPTH:
+                raise OdfResourceLimitError(f"ODF resource limit exceeded: {part_name!r} exceeds max_xml_depth={MAX_XML_DEPTH}")
+            for child in element:
+                if isinstance(child.tag, str):
+                    stack.append((child, depth + 1))
+
+    def detected_suffix(self) -> OdfSuffix | None:
+        """按 mimetype、manifest 根条目依次识别 ODF 三种包类型。"""
+        mimetype = self.read_part("mimetype")
+        if mimetype is not None:
+            try:
+                normalized = mimetype.decode("ascii", errors="strict").strip()
+            except UnicodeDecodeError:
+                normalized = ""
+            if suffix := ODF_SUFFIX_BY_MIME.get(normalized):
+                return suffix
+        return ODF_SUFFIX_BY_MIME.get(self.manifest_media_types().get("/", ""))
+
+    def validate_document(self, expected_suffix: OdfSuffix) -> etree._Element:
+        """校验包类型、加密状态和 required 正文 body 后返回内容根节点。"""
+        detected = self.detected_suffix()
+        if detected is not None and detected != expected_suffix:
+            raise OdfParseError(
+                f"Malformed ODF package: expected {ODF_MIME_BY_SUFFIX[expected_suffix]!r}, got {ODF_MIME_BY_SUFFIX[detected]!r}"
+            )
+        if self.is_encrypted():
+            raise OdfEncryptedError("Encrypted ODF documents are not supported")
+        content_root = self.xml_part("content.xml", required=True)
+        assert content_root is not None
+        body = content_root.find(f".//{qname('office', 'body')}")
+        expected_body = ODF_BODY_BY_SUFFIX[expected_suffix]
+        if body is None or body.find(qname("office", expected_body)) is None:
+            raise OdfParseError(f"Malformed ODF package: content.xml has no office:{expected_body} body")
+        return content_root
+
+    def manifest_media_types(self) -> dict[str, str]:
+        """读取 manifest 中规范成员路径到 MIME 的映射，损坏时安全降级为空。"""
+        if self._manifest_media_types is not None:
+            return self._manifest_media_types
+        result: dict[str, str] = {}
+        root = self.xml_part("META-INF/manifest.xml")
+        if root is not None:
+            for entry in root.iter(qname("manifest", "file-entry")):
+                path = entry.get(qname("manifest", "full-path"))
+                media_type = entry.get(qname("manifest", "media-type"))
+                if path and media_type:
+                    result[path] = media_type
+        self._manifest_media_types = result
+        return result
+
+    def is_encrypted(self) -> bool:
+        """按 manifest:encryption-data 元素判断包内是否存在加密内容。"""
+        root = self.xml_part("META-INF/manifest.xml")
+        return root is not None and next(root.iter(qname("manifest", "encryption-data")), None) is not None
+
+    def content_type_for(self, part_name: str) -> str | None:
+        """返回 manifest 为指定成员声明的媒体类型。"""
+        return self.manifest_media_types().get(part_name)
+
+    def resolve_reference(self, href: str, *, base_part: str = "content.xml") -> str | None:
+        """把相对 xlink 引用解析为安全包成员；绝对 URI 和上跳路径返回空。"""
+        normalized_href = unquote((href or "").strip())
+        if not normalized_href or normalized_href.startswith("#"):
+            return None
+        try:
+            split = urlsplit(normalized_href)
+        except ValueError:
+            return None
+        if split.scheme or split.netloc:
+            return None
+        candidate = split.path.replace("\\", "/")
+        base_dir = posixpath.dirname(base_part)
+        resolved = posixpath.normpath(posixpath.join(base_dir, candidate))
+        if resolved in {"", ".", ".."} or resolved.startswith("../") or resolved.startswith("/"):
+            return None
+        return resolved.removeprefix("./")
+
+    def resolve_object_content(self, href: str, *, base_part: str = "content.xml") -> str | None:
+        """把 draw:object 目录引用解析到其 content.xml 成员。"""
+        resolved = self.resolve_reference(href, base_part=base_part)
+        if resolved is None:
+            return None
+        if resolved.endswith(".xml"):
+            return resolved
+        return f"{resolved.rstrip('/')}/content.xml"
+
+    def body_element(self, content_root: etree._Element, suffix: OdfSuffix) -> etree._Element:
+        """返回已验证内容树中的 text、spreadsheet 或 presentation 正文节点。"""
+        body = content_root.find(f".//{qname('office', 'body')}")
+        if body is None:
+            raise OdfParseError("Malformed ODF package: content.xml has no office:body")
+        child = body.find(qname("office", ODF_BODY_BY_SUFFIX[suffix]))
+        if child is None:
+            raise OdfParseError(f"Malformed ODF package: content.xml has no {suffix} body")
+        return child
+
+    def close(self) -> None:
+        """关闭底层 ZipFile，但不触碰调用方提供的输入流。"""
+        self._zip.close()
+
+
+def detect_odf_suffix(file_bytes: bytes) -> OdfSuffix | None:
+    """只按 ODF 包身份识别三种后缀，任意损坏均返回空供上层继续兜底。"""
+    try:
+        package = OdfPackage(file_bytes)
+    except (OdfParseError, OdfResourceLimitError):
+        return None
+    try:
+        return package.detected_suffix()
+    finally:
+        package.close()
+
+
+__all__ = ["OdfPackage", "detect_odf_suffix"]

docvortex/analyzers/native/office/odf/styles.py

@@ -0,0 +1,329 @@
+"""解析 OpenDocument 样式继承、列表和逻辑分页属性。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from loguru import logger
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from .constants import qname
+from .models import ListLevel, TextStyle, TextStyleDelta
+
+
+@dataclass(frozen=True, slots=True)
+class _StyleDefinition:
+    """保存一个命名样式的父级、文本增量和跨格式投影属性。"""
+
+    name: str
+    family: str
+    parent: str | None
+    display_name: str | None
+    text_delta: TextStyleDelta
+    master_page_name: str | None
+    table_display: bool | None
+    drawing_page_visible: bool | None
+
+
+def _numeric_font_weight(value: str) -> int | None:
+    """在整数转换前验证 CSS 数字字重的词法长度和有效范围。"""
+    normalized = value.strip()
+    if not normalized or len(normalized) > 4 or not normalized.isascii() or not normalized.isdigit():
+        return None
+    weight = int(normalized)
+    return weight if 1 <= weight <= 1_000 else None
+
+
+class OdfStyles:
+    """合并 styles.xml 与 content.xml 中的 ODF 样式定义。"""
+
+    def __init__(self, *roots: etree._Element | None) -> None:
+        """按传入顺序收集文档样式，使 content.xml 自动样式覆盖基础定义。"""
+        self._styles: dict[tuple[str, str], _StyleDefinition] = {}
+        self._defaults: dict[str, TextStyleDelta] = {}
+        self._list_styles: dict[str, dict[int, ListLevel]] = {}
+        self._resolved_text: dict[tuple[str, str], TextStyleDelta] = {}
+        self._resolved_table_display: dict[str, bool | None] = {}
+        self._resolved_drawing_page_visibility: dict[str, bool | None] = {}
+        self._master_pages: dict[str, etree._Element] = {}
+        for root in roots:
+            if root is not None:
+                self._collect(root)
+
+    def _collect(self, root: etree._Element) -> None:
+        """从一棵 ODF XML 树收集默认、命名、列表和 master-page 样式。"""
+        for default in root.iter(qname("style", "default-style")):
+            family = default.get(qname("style", "family"))
+            if family:
+                self._defaults[family] = self._text_delta(default)
+        for style in root.iter(qname("style", "style")):
+            name = style.get(qname("style", "name"))
+            family = style.get(qname("style", "family"))
+            if not name or not family:
+                continue
+            self._styles[(family, name)] = _StyleDefinition(
+                name=name,
+                family=family,
+                parent=style.get(qname("style", "parent-style-name")),
+                display_name=style.get(qname("style", "display-name")),
+                text_delta=self._text_delta(style),
+                master_page_name=style.get(qname("style", "master-page-name")),
+                table_display=self._table_display(style),
+                drawing_page_visible=self._drawing_page_visibility(style),
+            )
+        for list_style in root.iter(qname("text", "list-style")):
+            name = list_style.get(qname("style", "name"))
+            if name:
+                self._list_styles[name] = self._parse_list_style(list_style)
+        for master_page in root.iter(qname("style", "master-page")):
+            name = master_page.get(qname("style", "name"))
+            if name:
+                self._master_pages[name] = master_page
+
+    @staticmethod
+    def _text_delta(style: etree._Element) -> TextStyleDelta:
+        """把 style:text-properties 转换为可继承的三态样式增量。"""
+        properties = style.find(qname("style", "text-properties"))
+        if properties is None:
+            return TextStyleDelta()
+        weight = properties.get(qname("fo", "font-weight"))
+        bold: bool | None = None
+        if weight is not None:
+            normalized_weight = weight.strip().casefold()
+            numeric_weight = _numeric_font_weight(normalized_weight)
+            bold = numeric_weight >= 600 if numeric_weight is not None else normalized_weight == "bold"
+        font_style = properties.get(qname("fo", "font-style"))
+        italic = None if font_style is None else font_style.casefold() in {"italic", "oblique"}
+        underline_style = properties.get(qname("style", "text-underline-style"))
+        underline = None if underline_style is None else underline_style.casefold() != "none"
+        strike_style = properties.get(qname("style", "text-line-through-style"))
+        strikethrough = None if strike_style is None else strike_style.casefold() != "none"
+        position = (properties.get(qname("style", "text-position")) or "").strip().casefold()
+        superscript: bool | None = None
+        subscript: bool | None = None
+        if position:
+            superscript = position.startswith("super") or OdfStyles._position_is_positive(position)
+            subscript = position.startswith("sub") or OdfStyles._position_is_negative(position)
+            if position == "0%":
+                superscript = False
+                subscript = False
+        return TextStyleDelta(
+            bold=bold,
+            italic=italic,
+            underline=underline,
+            strikethrough=strikethrough,
+            superscript=superscript,
+            subscript=subscript,
+        )
+
+    @staticmethod
+    def _position_is_positive(position: str) -> bool:
+        """判断百分比形式的 text-position 是否表示上标。"""
+        try:
+            return float(position.split("%", 1)[0]) > 0
+        except ValueError:
+            return False
+
+    @staticmethod
+    def _position_is_negative(position: str) -> bool:
+        """判断百分比形式的 text-position 是否表示下标。"""
+        try:
+            return float(position.split("%", 1)[0]) < 0
+        except ValueError:
+            return False
+
+    @staticmethod
+    def _table_display(style: etree._Element) -> bool | None:
+        """读取表格样式的 display 开关，用于过滤隐藏工作表。"""
+        properties = style.find(qname("style", "table-properties"))
+        if properties is None:
+            return None
+        display = properties.get(qname("table", "display"))
+        if display is None:
+            return None
+        return display.casefold() != "false"
+
+    @staticmethod
+    def _drawing_page_visibility(style: etree._Element) -> bool | None:
+        """读取 drawing-page 样式的 presentation visibility。"""
+        properties = style.find(qname("style", "drawing-page-properties"))
+        if properties is None:
+            return None
+        visibility = properties.get(qname("presentation", "visibility"))
+        if visibility is None:
+            return None
+        return visibility.casefold() != "hidden"
+
+    @staticmethod
+    def _parse_list_style(element: etree._Element) -> dict[int, ListLevel]:
+        """解析列表样式的层级、类型和通用起始值。"""
+        levels: dict[int, ListLevel] = {}
+        for child in element:
+            if not isinstance(child.tag, str):
+                continue
+            local_name = etree.QName(child).localname
+            if local_name not in {"list-level-style-number", "list-level-style-bullet", "list-level-style-image"}:
+                continue
+            try:
+                level = max(1, int(child.get(qname("text", "level"), "1")))
+            except ValueError:
+                level = 1
+            try:
+                start = max(1, int(child.get(qname("text", "start-value"), "1")))
+            except ValueError:
+                start = 1
+            ordered = local_name == "list-level-style-number" and bool(child.get(qname("style", "num-format"), "1"))
+            levels[level - 1] = ListLevel(
+                ordered=ordered,
+                start=start,
+            )
+        return levels
+
+    def _resolved_delta(self, family: str, name: str | None) -> TextStyleDelta:
+        """沿 parent-style-name 合并样式，并在循环处安全截断。"""
+        if not name:
+            return self._defaults.get(family, TextStyleDelta())
+        key = (family, name)
+        if key in self._resolved_text:
+            return self._resolved_text[key]
+        chain: list[_StyleDefinition] = []
+        seen: set[str] = set()
+        current = name
+        while current:
+            if current in seen:
+                logger.warning("ODF style inheritance cycle detected: family={}, style={}", family, current)
+                break
+            seen.add(current)
+            definition = self._styles.get((family, current))
+            if definition is None:
+                break
+            chain.append(definition)
+            current = definition.parent or ""
+        result = self._defaults.get(family, TextStyleDelta())
+        for definition in reversed(chain):
+            result = result.merge(definition.text_delta)
+        self._resolved_text[key] = result
+        return result
+
+    def text_style(self, style_name: str | None, *, family: str, inherited: TextStyle | None = None) -> TextStyle:
+        """解析指定样式，并让 span 的未声明属性继承当前段落样式。"""
+        delta = self._resolved_delta(family, style_name)
+        if inherited is not None:
+            base = TextStyleDelta(
+                bold=inherited.bold,
+                italic=inherited.italic,
+                underline=inherited.underline,
+                strikethrough=inherited.strikethrough,
+                superscript=inherited.superscript,
+                subscript=inherited.subscript,
+            )
+            delta = base.merge(delta)
+        return delta.resolve()
+
+    def paragraph_master_page_name(self, style_name: str | None) -> str | None:
+        """沿段落父样式查找首个有效 master-page 名称。"""
+        if not style_name:
+            return None
+        seen: set[str] = set()
+        current = style_name
+        while current:
+            if current in seen:
+                logger.warning("ODF style inheritance cycle detected: family=paragraph, style={}", current)
+                break
+            seen.add(current)
+            definition = self._styles.get(("paragraph", current))
+            if definition is None:
+                break
+            if definition.master_page_name is not None:
+                return definition.master_page_name
+            current = definition.parent or ""
+        return None
+
+    def is_document_title(self, style_name: str | None) -> bool:
+        """沿段落父样式，根据名称和 display-name 判断是否继承文档标题语义。"""
+        if not style_name:
+            return False
+        seen: set[str] = set()
+        current = style_name
+        while current:
+            if current in seen:
+                logger.warning("ODF style inheritance cycle detected: family=paragraph, style={}", current)
+                break
+            seen.add(current)
+            definition = self._styles.get(("paragraph", current))
+            names = {current, definition.display_name if definition is not None else ""}
+            normalized = {name.replace("_20_", " ").replace("_", " ").strip().casefold() for name in names if name}
+            if normalized & {"title", "document title", "标题"}:
+                return True
+            if definition is None:
+                break
+            current = definition.parent or ""
+        return False
+
+    def list_level(self, style_name: str | None, depth: int) -> ListLevel:
+        """返回指定列表深度的定义，不存在时使用无序默认值。"""
+        if not style_name:
+            return ListLevel()
+        levels = self._list_styles.get(style_name, {})
+        return levels.get(depth, ListLevel())
+
+    def table_is_visible(self, style_name: str | None) -> bool:
+        """沿表格父样式解析 display，子样式显式值优先。"""
+        if not style_name:
+            return True
+        if style_name in self._resolved_table_display:
+            return self._resolved_table_display[style_name] is not False
+        seen: set[str] = set()
+        current = style_name
+        resolved: bool | None = None
+        while current:
+            if current in seen:
+                logger.warning("ODF style inheritance cycle detected: family=table, style={}", current)
+                break
+            seen.add(current)
+            definition = self._styles.get(("table", current))
+            if definition is None:
+                break
+            if definition.table_display is not None:
+                resolved = definition.table_display
+                break
+            current = definition.parent or ""
+        self._resolved_table_display[style_name] = resolved
+        return resolved is not False
+
+    def drawing_page_is_visible(self, page: etree._Element) -> bool:
+        """解析 ODP 页面直接属性或 drawing-page 样式中的隐藏状态。"""
+        direct_visibility = page.get(qname("presentation", "visibility"))
+        if direct_visibility is not None:
+            return direct_visibility.casefold() != "hidden"
+        style_name = page.get(qname("draw", "style-name"))
+        if not style_name:
+            return True
+        if style_name in self._resolved_drawing_page_visibility:
+            return self._resolved_drawing_page_visibility[style_name] is not False
+        seen: set[str] = set()
+        current = style_name
+        resolved: bool | None = None
+        while current:
+            if current in seen:
+                logger.warning("ODF style inheritance cycle detected: family=drawing-page, style={}", current)
+                break
+            seen.add(current)
+            definition = self._styles.get(("drawing-page", current))
+            if definition is None:
+                break
+            if definition.drawing_page_visible is not None:
+                resolved = definition.drawing_page_visible
+                break
+            current = definition.parent or ""
+        self._resolved_drawing_page_visibility[style_name] = resolved
+        return resolved is not False
+
+    def master_page(self, name: str | None) -> etree._Element | None:
+        """返回指定 master-page；空名称时优先使用第一个定义。"""
+        if name and name in self._master_pages:
+            return self._master_pages[name]
+        return next(iter(self._master_pages.values()), None)
+
+
+__all__ = ["OdfStyles"]