docvortex 0.2.1__py3-none-any.whl

docvortex/analyzers/native/office/legacy/officeart.py

@@ -0,0 +1,362 @@
+"""旧版 Office 二进制格式共享的 OfficeArt 记录与图片解码。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+import struct
+import zlib
+
+from loguru import logger
+
+from ..image import ensure_bmp_header
+from ..errors import LegacyOfficeResourceLimitError
+from ..limits import MAX_ASSET_TOTAL_BYTES, MAX_ENTRY_BYTES, MAX_PICTURE_RECORDS, MAX_RECORD_DEPTH
+
+OFFICEART_CONTAINER_VERSION = 0xF
+OFFICEART_DGG_CONTAINER = 0xF000
+OFFICEART_BSTORE_CONTAINER = 0xF001
+OFFICEART_SP_CONTAINER = 0xF004
+OFFICEART_BSE = 0xF007
+OFFICEART_FSP = 0xF00A
+OFFICEART_FOPT = 0xF00B
+OFFICEART_CLIENT_ANCHOR = 0xF010
+OFFICEART_TERTIARY_FOPT = 0xF122
+
+FOPT_PIB = 0x0104
+FOPT_GROUP_SHAPE = 0x03BF
+F_HIDDEN = 0x0000_0002
+F_USE_HIDDEN = 0x0002_0000
+
+
+@dataclass(frozen=True, slots=True)
+class OfficeArtRecord:
+    """一条已经通过长度边界校验的 OfficeArt 记录。"""
+
+    offset: int
+    version: int
+    instance: int
+    record_type: int
+    payload: bytes
+
+
+@dataclass(frozen=True, slots=True)
+class OfficeImagePayload:
+    """从 BLIP 中恢复出的原始图片及其媒体类型。"""
+
+    data: bytes
+    extension: str
+    content_type: str
+    render_size_emu: tuple[int, int] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OfficeArtShape:
+    """Excel drawing 中可绑定到 OBJ 的形状属性。"""
+
+    shape_id: int | None
+    anchor: tuple[int, int, int, int] | None
+    pib: int | None
+    hidden: bool
+
+
+def record_at(
+    data: bytes,
+    offset: int,
+    *,
+    end: int | None = None,
+    charge: Callable[[], None] | None = None,
+) -> OfficeArtRecord | None:
+    """从指定偏移读取一条 OfficeArt 记录，坏边界返回空值。"""
+
+    limit = len(data) if end is None else min(end, len(data))
+    if offset < 0 or offset + 8 > limit:
+        return None
+    version_instance, record_type, length = struct.unpack_from("<HHI", data, offset)
+    payload_start = offset + 8
+    payload_end = payload_start + int(length)
+    if payload_end < payload_start or payload_end > limit:
+        return None
+    if charge is not None:
+        charge()
+    return OfficeArtRecord(
+        offset=offset,
+        version=version_instance & 0xF,
+        instance=version_instance >> 4,
+        record_type=record_type,
+        payload=data[payload_start:payload_end],
+    )
+
+
+def iter_records(
+    data: bytes,
+    *,
+    start: int = 0,
+    end: int | None = None,
+    charge: Callable[[], None] | None = None,
+) -> Iterator[OfficeArtRecord]:
+    """顺序遍历同一 OfficeArt 容器内的直接子记录。"""
+
+    limit = len(data) if end is None else min(end, len(data))
+    cursor = start
+    while cursor < limit:
+        record = record_at(data, cursor, end=limit, charge=charge)
+        if record is None:
+            return
+        yield record
+        cursor += 8 + len(record.payload)
+
+
+def iter_descendants(
+    data: bytes,
+    *,
+    charge: Callable[[], None] | None = None,
+) -> Iterator[OfficeArtRecord]:
+    """以显式栈深度优先遍历 OfficeArt 记录树并限制嵌套深度。"""
+
+    stack: list[Iterator[OfficeArtRecord]] = [iter_records(data, charge=charge)]
+    while stack:
+        if len(stack) > MAX_RECORD_DEPTH:
+            raise LegacyOfficeResourceLimitError(f"record nesting exceeds max_record_depth={MAX_RECORD_DEPTH}")
+        try:
+            record = next(stack[-1])
+        except StopIteration:
+            stack.pop()
+            continue
+        yield record
+        if record.version == OFFICEART_CONTAINER_VERSION:
+            stack.append(iter_records(record.payload, charge=charge))
+
+
+def _simple_properties(record: OfficeArtRecord) -> dict[int, int]:
+    """读取 FOPT 简单属性并让后出现的同名属性覆盖前值。"""
+
+    properties: dict[int, int] = {}
+    for index in range(record.instance):
+        offset = index * 6
+        if offset + 6 > len(record.payload):
+            break
+        opid, value = struct.unpack_from("<HI", record.payload, offset)
+        properties[opid & 0x3FFF] = int(value)
+    return properties
+
+
+def _excel_client_anchor(payload: bytes) -> tuple[int, int, int, int] | None:
+    """把 OfficeArtClientAnchorChart 转成起止行列坐标。"""
+
+    if len(payload) < 18:
+        return None
+    start_col = struct.unpack_from("<H", payload, 2)[0]
+    start_row = struct.unpack_from("<H", payload, 6)[0]
+    end_col = struct.unpack_from("<H", payload, 10)[0]
+    end_row = struct.unpack_from("<H", payload, 14)[0]
+    return int(start_row), int(start_col), int(end_row), int(end_col)
+
+
+def _shape_from_container(
+    record: OfficeArtRecord,
+    *,
+    charge: Callable[[], None] | None = None,
+) -> OfficeArtShape | None:
+    """从单个 SpContainer 提取 shape id、anchor、pib 与隐藏状态。"""
+
+    shape_id: int | None = None
+    anchor: tuple[int, int, int, int] | None = None
+    properties: dict[int, int] = {}
+    for child in iter_records(record.payload, charge=charge):
+        if child.record_type == OFFICEART_FSP and len(child.payload) >= 4:
+            shape_id = int(struct.unpack_from("<I", child.payload, 0)[0])
+        elif child.record_type in {OFFICEART_FOPT, OFFICEART_TERTIARY_FOPT}:
+            properties.update(_simple_properties(child))
+        elif child.record_type == OFFICEART_CLIENT_ANCHOR:
+            anchor = _excel_client_anchor(child.payload)
+    hidden_flags = properties.get(FOPT_GROUP_SHAPE, 0)
+    hidden = bool(hidden_flags & F_USE_HIDDEN and hidden_flags & F_HIDDEN)
+    pib = properties.get(FOPT_PIB)
+    if anchor is None and pib is None:
+        return None
+    return OfficeArtShape(shape_id=shape_id, anchor=anchor, pib=pib, hidden=hidden)
+
+
+def extract_excel_shapes(
+    data: bytes,
+    *,
+    charge: Callable[[], None] | None = None,
+) -> list[OfficeArtShape]:
+    """按 drawing 顺序提取可与 Excel OBJ 一一绑定的形状。"""
+
+    shapes: list[OfficeArtShape] = []
+    for record in iter_descendants(data, charge=charge):
+        if record.record_type != OFFICEART_SP_CONTAINER:
+            continue
+        shape = _shape_from_container(record, charge=charge)
+        if shape is not None:
+            shapes.append(shape)
+    return shapes
+
+
+def _bitmap_payload(body: bytes, instance: int) -> bytes | None:
+    """跳过 BLIP UID 和 tag，返回位图原始载荷。"""
+
+    doubled = instance in {0x46B, 0x6E3, 0x6E1, 0x7A9}
+    start = (32 if doubled else 16) + 1
+    return body[start:] if start < len(body) else None
+
+
+def decode_blip(record: OfficeArtRecord) -> OfficeImagePayload | None:
+    """解码常见位图和 EMF/WMF BLIP，并限制矢量解压输出。"""
+
+    instance = record.instance
+    body = record.payload
+    if record.record_type in {0xF01D, 0xF01E, 0xF01F, 0xF029}:
+        data = _bitmap_payload(body, instance)
+        if data is None:
+            return None
+        if len(data) > MAX_ENTRY_BYTES:
+            raise LegacyOfficeResourceLimitError("bitmap BLIP exceeds max_entry_bytes")
+        if record.record_type == 0xF01D:
+            return OfficeImagePayload(data=data, extension="jpg", content_type="image/jpeg")
+        if record.record_type == 0xF01E:
+            return OfficeImagePayload(data=data, extension="png", content_type="image/png")
+        if record.record_type == 0xF029:
+            return OfficeImagePayload(data=data, extension="tiff", content_type="image/tiff")
+        return OfficeImagePayload(data=ensure_bmp_header(data), extension="bmp", content_type="image/bmp")
+
+    if record.record_type not in {0xF01A, 0xF01B}:
+        return None
+    doubled = instance in ({0x3D5} if record.record_type == 0xF01A else {0x217})
+    header_offset = 32 if doubled else 16
+    if header_offset + 34 > len(body):
+        return None
+    declared_size = int(struct.unpack_from("<I", body, header_offset)[0])
+    render_width_emu, render_height_emu = struct.unpack_from("<ii", body, header_offset + 20)
+    render_size_emu = (render_width_emu, render_height_emu) if render_width_emu > 0 and render_height_emu > 0 else None
+    compressed_size = int(struct.unpack_from("<I", body, header_offset + 28)[0])
+    compression = body[header_offset + 32]
+    payload_start = header_offset + 34
+    payload = body[payload_start : payload_start + compressed_size]
+    if declared_size > MAX_ENTRY_BYTES:
+        raise LegacyOfficeResourceLimitError("metafile BLIP exceeds max_entry_bytes")
+    if compression == 0:
+        data = b""
+        reached_eof = False
+        for window_bits in (-zlib.MAX_WBITS, zlib.MAX_WBITS):
+            try:
+                inflater = zlib.decompressobj(window_bits)
+                candidate = inflater.decompress(payload, MAX_ENTRY_BYTES + 1)
+                candidate += inflater.flush(MAX_ENTRY_BYTES + 1 - len(candidate))
+            except zlib.error:
+                continue
+            if inflater.eof:
+                data = candidate
+                reached_eof = True
+                break
+        if not reached_eof:
+            return None
+        if len(data) > MAX_ENTRY_BYTES:
+            raise LegacyOfficeResourceLimitError("metafile BLIP decompression exceeded its limit")
+    else:
+        data = payload
+    if record.record_type == 0xF01A:
+        return OfficeImagePayload(
+            data=data,
+            extension="emf",
+            content_type="image/emf",
+            render_size_emu=render_size_emu,
+        )
+    # 保留合法 placeable header，使跨平台渲染器继续获得 bbox 与 units-per-inch。
+    return OfficeImagePayload(
+        data=data,
+        extension="wmf",
+        content_type="image/wmf",
+        render_size_emu=render_size_emu,
+    )
+
+
+def first_blip(
+    data: bytes,
+    *,
+    charge: Callable[[], None] | None = None,
+) -> OfficeImagePayload | None:
+    """深度优先返回一段 OfficeArt 数据中的首个可支持 BLIP。"""
+
+    for record in iter_descendants(data, charge=charge):
+        if record.record_type == OFFICEART_BSE:
+            decoded = _decode_bse_body(record.payload, charge=charge)
+            if decoded is not None:
+                return decoded
+        decoded = decode_blip(record)
+        if decoded is not None:
+            return decoded
+    return None
+
+
+def extract_word_shapes(
+    data: bytes,
+    *,
+    charge: Callable[[], None] | None = None,
+) -> list[OfficeArtShape]:
+    """按 Word drawing 顺序提取 shape id、pib 和隐藏状态。"""
+
+    shapes: list[OfficeArtShape] = []
+    for record in iter_descendants(data, charge=charge):
+        if record.record_type != OFFICEART_SP_CONTAINER:
+            continue
+        shape = _shape_from_container(record, charge=charge)
+        if shape is not None:
+            shapes.append(shape)
+    return shapes
+
+
+def _decode_bse_body(
+    body: bytes,
+    *,
+    charge: Callable[[], None] | None = None,
+    delay_stream: bytes | None = None,
+) -> OfficeImagePayload | None:
+    """从 FBSE body 的内嵌或延迟 BLIP 中恢复图片。"""
+
+    if len(body) < 36:
+        return None
+    inner_offset = 36 + int(body[33])
+    inner = record_at(body, inner_offset, charge=charge) if inner_offset < len(body) else None
+    if inner is None and delay_stream is not None:
+        delayed_size = int(struct.unpack_from("<I", body, 20)[0])
+        reference_count = int(struct.unpack_from("<I", body, 24)[0])
+        delayed_offset = int(struct.unpack_from("<I", body, 28)[0])
+        if reference_count and delayed_offset != 0xFFFF_FFFF:
+            delayed_end = delayed_offset + delayed_size
+            if delayed_end >= delayed_offset and delayed_end <= len(delay_stream):
+                inner = record_at(delay_stream, delayed_offset, end=delayed_end, charge=charge)
+    return decode_blip(inner) if inner is not None else None
+
+
+def decode_bstore(
+    data: bytes,
+    *,
+    charge: Callable[[], None] | None = None,
+    delay_stream: bytes | None = None,
+) -> dict[int, OfficeImagePayload]:
+    """按一基 BSE 序号解码 drawing group 中的图片资源。"""
+
+    bse_records = [record for record in iter_descendants(data, charge=charge) if record.record_type == OFFICEART_BSE]
+    result: dict[int, OfficeImagePayload] = {}
+    asset_total = 0
+    for index, bse in enumerate(bse_records[:MAX_PICTURE_RECORDS], start=1):
+        decoded = _decode_bse_body(
+            bse.payload,
+            charge=charge,
+            delay_stream=delay_stream,
+        )
+        if decoded is None:
+            continue
+        asset_total += len(decoded.data)
+        if asset_total > MAX_ASSET_TOTAL_BYTES:
+            raise LegacyOfficeResourceLimitError(f"embedded assets exceed max_asset_total_bytes={MAX_ASSET_TOTAL_BYTES}")
+        result[index] = decoded
+    if len(bse_records) > MAX_PICTURE_RECORDS:
+        logger.warning(
+            "LEGACY_OFFICE_PICTURE_LIMIT: ignored BSE records after {}",
+            MAX_PICTURE_RECORDS,
+        )
+    return result

docvortex/analyzers/native/office/legacy/ole.py

@@ -0,0 +1,110 @@
+"""基于 olefile 的有界 OLE2/CFB 只读包装。"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+import olefile  # type: ignore[reportMissingModuleSource]
+
+from ..errors import LegacyOfficeMalformedError, LegacyOfficeMissingPartError, LegacyOfficeResourceLimitError
+from ..limits import MAX_ENTRY_BYTES, MAX_TOTAL_BYTES
+
+
+class BoundedOleReader:
+    """限制输入、单流及累计读取量，并提供大小写无关的 stream 访问。"""
+
+    def __init__(self, file_bytes: bytes) -> None:
+        """校验输入大小并打开内存中的 OLE2 容器。"""
+
+        if not isinstance(file_bytes, bytes):
+            raise TypeError("legacy Office input must be bytes")
+        if len(file_bytes) > MAX_TOTAL_BYTES:
+            raise LegacyOfficeResourceLimitError(f"input exceeds max_total_bytes={MAX_TOTAL_BYTES}")
+        try:
+            self._ole: Any = olefile.OleFileIO(BytesIO(file_bytes), raise_defects=olefile.DEFECT_FATAL)
+        except Exception as exc:
+            raise LegacyOfficeMalformedError(f"not a readable OLE2 compound file: {exc}") from exc
+        self._total_read = 0
+        self._stream_names = self._build_stream_name_map()
+
+    def _build_stream_name_map(self) -> dict[str, tuple[str, ...]]:
+        """建立大小写无关的完整 stream 名称索引。"""
+
+        names: dict[str, tuple[str, ...]] = {}
+        try:
+            for parts in self._ole.listdir(streams=True, storages=False):
+                normalized = tuple(str(part) for part in parts)
+                names["/".join(normalized).casefold()] = normalized
+        except Exception as exc:
+            self.close()
+            raise LegacyOfficeMalformedError(f"cannot enumerate OLE streams: {exc}") from exc
+        return names
+
+    def has_stream(self, name: str) -> bool:
+        """返回容器是否含有指定 stream。"""
+
+        return name.casefold() in self._stream_names
+
+    def stream_names(self, *, prefix: str | None = None) -> tuple[str, ...]:
+        """返回完整 stream 名称；可按大小写无关前缀筛选。"""
+
+        normalized_prefix = prefix.casefold() if prefix is not None else None
+        names = (
+            "/".join(parts)
+            for key, parts in self._stream_names.items()
+            if normalized_prefix is None or key.startswith(normalized_prefix)
+        )
+        return tuple(sorted(names, key=str.casefold))
+
+    def read_stream(self, name: str, *, required: bool = True) -> bytes:
+        """有界读取指定 stream；可选 stream 不存在时返回空字节。"""
+
+        parts = self._stream_names.get(name.casefold())
+        if parts is None:
+            if required:
+                raise LegacyOfficeMissingPartError(f"missing required OLE stream: {name}")
+            return b""
+        try:
+            size = int(self._ole.get_size(list(parts)))
+        except Exception as exc:
+            raise LegacyOfficeMalformedError(f"cannot read OLE stream size: {name}: {exc}") from exc
+        if size > MAX_ENTRY_BYTES:
+            raise LegacyOfficeResourceLimitError(f"stream {name!r} exceeds max_entry_bytes={MAX_ENTRY_BYTES}")
+        if self._total_read + size > MAX_TOTAL_BYTES:
+            raise LegacyOfficeResourceLimitError(f"OLE streams exceed max_total_bytes={MAX_TOTAL_BYTES}")
+        try:
+            with self._ole.openstream(list(parts)) as stream:
+                payload = stream.read(MAX_ENTRY_BYTES + 1)
+        except Exception as exc:
+            raise LegacyOfficeMalformedError(f"cannot read OLE stream {name!r}: {exc}") from exc
+        if len(payload) > MAX_ENTRY_BYTES:
+            raise LegacyOfficeResourceLimitError(f"stream {name!r} exceeds max_entry_bytes={MAX_ENTRY_BYTES}")
+        self._total_read += len(payload)
+        return payload
+
+    def metadata(self) -> Any | None:
+        """尽力读取 SummaryInformation，失败时不影响正文解析。"""
+
+        try:
+            return self._ole.get_metadata()
+        except Exception:
+            return None
+
+    def close(self) -> None:
+        """关闭底层 olefile 句柄。"""
+
+        ole = getattr(self, "_ole", None)
+        if ole is not None:
+            ole.close()
+            self._ole = None
+
+    def __enter__(self) -> BoundedOleReader:
+        """返回当前有界读取器。"""
+
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        """离开上下文时关闭底层句柄。"""
+
+        self.close()

docvortex/analyzers/native/office/limits.py

@@ -0,0 +1,12 @@
+"""Flash Office 二进制、嵌入对象与 RTF 解析共享的固定安全限制。"""
+
+from typing import Final
+
+MAX_ENTRY_BYTES: Final = 128 * 1024 * 1024
+MAX_TOTAL_BYTES: Final = 512 * 1024 * 1024
+MAX_ASSET_TOTAL_BYTES: Final = 128 * 1024 * 1024
+MAX_GRID_SLOTS: Final = 4_000_000
+MAX_RECORD_DEPTH: Final = 64
+MAX_RECORDS: Final = 16_000_000
+MAX_PICTURE_RECORDS: Final = 100_000
+MAX_USER_EDIT_CHAIN: Final = 100

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

@@ -0,0 +1,3 @@
+"""OpenDocument 内部解析实现。"""
+
+__all__: list[str] = []

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

@@ -0,0 +1,76 @@
+"""恢复 ODF 嵌入图表的预览与源数据表。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from .....schema import BlockType
+from .constants import qname
+from .models import TableGrid
+from .table import (
+    OdfTableExpansionBudget,
+    crop_table_grid,
+    parse_cell_range_bounds,
+    parse_table_grid,
+    table_grid_to_html,
+    union_bounds,
+)
+
+
+def _chart_range_bounds(chart: etree._Element) -> tuple[int, int, int, int] | None:
+    """收集 chart series、label 和 categories 的精确单元格引用范围。"""
+    values: list[tuple[int, int, int, int]] = []
+    attribute_names = {
+        qname("chart", "values-cell-range-address"),
+        qname("chart", "label-cell-address"),
+        qname("table", "cell-range-address"),
+    }
+    for element in chart.iter():
+        for attribute_name in attribute_names:
+            if bounds := parse_cell_range_bounds(element.get(attribute_name, "")):
+                values.append(bounds)
+    return union_bounds(values)
+
+
+def _single_nonempty_grid(grids: list[TableGrid]) -> TableGrid | None:
+    """仅在对象内存在唯一非空表格时返回安全回退候选。"""
+    nonempty = [grid for grid in grids if grid.rows]
+    return nonempty[0] if len(nonempty) == 1 else None
+
+
+def parse_chart_block(
+    object_root: etree._Element,
+    *,
+    render_cell: Callable[[etree._Element], str],
+    preview_data_uri: str | None,
+    table_expansion_budget: OdfTableExpansionBudget | None = None,
+) -> dict | None:
+    """按精确引用优先、唯一表回退的规则构造图表 raw block。"""
+    chart = next(object_root.iter(qname("chart", "chart")), None)
+    if chart is None:
+        return None
+    grids = [
+        parse_table_grid(table, render_cell, expansion_budget=table_expansion_budget)
+        for table in object_root.iter(qname("table", "table"))
+    ]
+    selected: TableGrid | None = None
+    if grids and (bounds := _chart_range_bounds(chart)) is not None:
+        selected = crop_table_grid(grids[0], bounds)
+        if not selected.rows:
+            selected = None
+    if selected is None:
+        selected = _single_nonempty_grid(grids)
+    if selected is None:
+        return None
+    content = table_grid_to_html(selected)
+    if not content:
+        return None
+    block: dict = {"type": BlockType.CHART, "content": content}
+    if preview_data_uri:
+        block["image_base64"] = preview_data_uri
+    return block
+
+
+__all__ = ["parse_chart_block"]

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

@@ -0,0 +1,70 @@
+"""OpenDocument 命名空间、MIME 与固定资源上限。"""
+
+from __future__ import annotations
+
+from typing import Final, Literal, TypeAlias
+
+
+OdfSuffix: TypeAlias = Literal["odt", "ods", "odp"]
+
+NS: Final[dict[str, str]] = {
+    "chart": "urn:oasis:names:tc:opendocument:xmlns:chart:1.0",
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "draw": "urn:oasis:names:tc:opendocument:xmlns:drawing:1.0",
+    "fo": "urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0",
+    "form": "urn:oasis:names:tc:opendocument:xmlns:form:1.0",
+    "manifest": "urn:oasis:names:tc:opendocument:xmlns:manifest:1.0",
+    "math": "http://www.w3.org/1998/Math/MathML",
+    "meta": "urn:oasis:names:tc:opendocument:xmlns:meta:1.0",
+    "number": "urn:oasis:names:tc:opendocument:xmlns:datastyle:1.0",
+    "office": "urn:oasis:names:tc:opendocument:xmlns:office:1.0",
+    "presentation": "urn:oasis:names:tc:opendocument:xmlns:presentation:1.0",
+    "style": "urn:oasis:names:tc:opendocument:xmlns:style:1.0",
+    "svg": "urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0",
+    "table": "urn:oasis:names:tc:opendocument:xmlns:table:1.0",
+    "text": "urn:oasis:names:tc:opendocument:xmlns:text:1.0",
+    "xlink": "http://www.w3.org/1999/xlink",
+    "xml": "http://www.w3.org/XML/1998/namespace",
+}
+
+ODF_MIME_BY_SUFFIX: Final[dict[OdfSuffix, str]] = {
+    "odt": "application/vnd.oasis.opendocument.text",
+    "ods": "application/vnd.oasis.opendocument.spreadsheet",
+    "odp": "application/vnd.oasis.opendocument.presentation",
+}
+ODF_SUFFIX_BY_MIME: Final[dict[str, OdfSuffix]] = {mime: suffix for suffix, mime in ODF_MIME_BY_SUFFIX.items()}
+ODF_BODY_BY_SUFFIX: Final[dict[OdfSuffix, str]] = {
+    "odt": "text",
+    "ods": "spreadsheet",
+    "odp": "presentation",
+}
+
+MAX_ENTRY_BYTES: Final = 128 * 1024 * 1024
+MAX_TOTAL_BYTES: Final = 512 * 1024 * 1024
+MAX_ENTRY_COUNT: Final = 100_000
+MAX_XML_DEPTH: Final = 256
+MAX_XML_NODES: Final = 2_000_000
+MAX_EXPANSION_TEXT_BYTES: Final = 64 * 1024 * 1024
+MAX_ASSET_TOTAL_BYTES: Final = 128 * 1024 * 1024
+
+
+def qname(prefix: str, local_name: str) -> str:
+    """返回指定 ODF 命名空间下的 Clark notation 标签名。"""
+    return f"{{{NS[prefix]}}}{local_name}"
+
+
+__all__ = [
+    "MAX_ASSET_TOTAL_BYTES",
+    "MAX_ENTRY_BYTES",
+    "MAX_ENTRY_COUNT",
+    "MAX_EXPANSION_TEXT_BYTES",
+    "MAX_TOTAL_BYTES",
+    "MAX_XML_DEPTH",
+    "MAX_XML_NODES",
+    "NS",
+    "ODF_BODY_BY_SUFFIX",
+    "ODF_MIME_BY_SUFFIX",
+    "ODF_SUFFIX_BY_MIME",
+    "OdfSuffix",
+    "qname",
+]