docvortex 0.2.1__py3-none-any.whl

docvortex/analyzers/native/office/ppt/ppt_converter.py

@@ -0,0 +1,292 @@
+"""把旧版 PPT 内部语义模型转换为 DocVortex 分页 model-list。"""
+
+from __future__ import annotations
+
+from typing import Any, BinaryIO
+
+from ..legacy.ole import BoundedOleReader
+from ..._shared.xycut import sort_entries
+from ..streams import read_stream_bytes_from_start
+from .....schema import BlockType
+from ..rich_text import OfficeRichTextSegment, build_rich_text_from_segments, build_rich_text_html_from_segments
+
+from .models import (
+    PptChartElement,
+    PptEquationElement,
+    PptImageElement,
+    PptParagraph,
+    PptPresentation,
+    PptSlide,
+    PptTableCell,
+    PptTableElement,
+    PptTextElement,
+    PptTextRun,
+)
+from .parser import parse_ppt_document
+
+PPT_XYCUT_BETA = 2.0
+PPT_XYCUT_DENSITY_THRESHOLD = 0.9
+
+
+class PptConverter:
+    """将 PowerPoint 97–2003 二进制流转换为分页 raw blocks。"""
+
+    def __init__(self) -> None:
+        """初始化无状态转换器输出。"""
+
+        self.pages: list[list[dict[str, Any]]] = []
+
+    def convert(self, file_binary: BinaryIO) -> None:
+        """读取输入流、解析三个核心 OLE streams 并生成 model-list。"""
+
+        file_bytes = read_stream_bytes_from_start(file_binary)
+        with BoundedOleReader(file_bytes) as ole:
+            presentation = parse_ppt_document(
+                ole.read_stream("PowerPoint Document"),
+                current_user=ole.read_stream("Current User", required=False),
+                pictures=ole.read_stream("Pictures", required=False),
+            )
+        self.pages = self._presentation_to_pages(presentation)
+
+    @staticmethod
+    def _run_styles(run: PptTextRun) -> list[str]:
+        """把内部字符属性转换为 DocVortex 富文本样式名。"""
+
+        styles: list[str] = []
+        if run.bold:
+            styles.append("bold")
+        if run.italic:
+            styles.append("italic")
+        if run.underline:
+            styles.append("underline")
+        if run.strike:
+            styles.append("strikethrough")
+        if run.baseline is not None and run.baseline > 0:
+            styles.append("superscript")
+        elif run.baseline is not None and run.baseline < 0:
+            styles.append("subscript")
+        return styles
+
+    @classmethod
+    def _paragraph_content(cls, paragraph: PptParagraph) -> list[dict[str, Any]]:
+        """把段落 run 直接构建为结构化 Span。"""
+
+        segments = [
+            OfficeRichTextSegment(
+                text=run.text.replace("\n", " "),
+                style=cls._run_styles(run),
+                hyperlink=run.hyperlink,
+            )
+            for run in paragraph.runs
+            if run.text
+        ]
+        return build_rich_text_from_segments(segments, trim_plain_edges=True)
+
+    @classmethod
+    def _append_list_paragraph(
+        cls,
+        root_blocks: list[dict[str, Any]],
+        stack: list[dict[str, Any]],
+        paragraph: PptParagraph,
+    ) -> None:
+        """把一个列表段落放入对应层级，并按需创建中间列表。"""
+
+        depth = max(0, int(paragraph.depth))
+        while len(stack) > depth + 1:
+            stack.pop()
+        while len(stack) < depth + 1:
+            attribute = paragraph.list_kind or "unordered"
+            new_list: dict[str, Any] = {
+                "type": BlockType.LIST,
+                "attribute": attribute,
+                "ilevel": len(stack),
+                "content": [],
+            }
+            if attribute == "ordered" and paragraph.start is not None:
+                new_list["start"] = paragraph.start
+            if stack:
+                stack[-1]["content"].append(new_list)
+            else:
+                root_blocks.append(new_list)
+            stack.append(new_list)
+        current = stack[depth]
+        expected_attribute = paragraph.list_kind or "unordered"
+        if current.get("attribute") != expected_attribute:
+            del stack[depth:]
+            cls._append_list_paragraph(root_blocks, stack, paragraph)
+            return
+        content = cls._paragraph_content(paragraph)
+        if content:
+            current["content"].append({"type": BlockType.TEXT, "content": content})
+
+    @classmethod
+    def _text_element_blocks(
+        cls,
+        element: PptTextElement,
+        *,
+        title_candidate: bool,
+    ) -> list[dict[str, Any]]:
+        """把文本形状转换为标题、正文和嵌套列表 raw blocks。"""
+
+        blocks: list[dict[str, Any]] = []
+        list_stack: list[dict[str, Any]] = []
+        title_consumed = False
+        for paragraph in element.paragraphs:
+            content = cls._paragraph_content(paragraph)
+            if not content:
+                continue
+            if title_candidate and not title_consumed and paragraph.list_kind is None:
+                blocks.append(
+                    {
+                        "type": BlockType.PARAGRAPH_TITLE,
+                        "content": content,
+                        "level": 2,
+                        "_ppt_title_candidate": True,
+                    }
+                )
+                title_consumed = True
+                list_stack.clear()
+                continue
+            if paragraph.list_kind is not None:
+                cls._append_list_paragraph(blocks, list_stack, paragraph)
+                continue
+            list_stack.clear()
+            blocks.append({"type": BlockType.TEXT, "content": content})
+        return blocks
+
+    @classmethod
+    def _table_cell_content(cls, cell: PptTableCell) -> str:
+        """把表格单元格内的多个段落连接为 HTML 内容。"""
+        paragraphs: list[str] = []
+        for paragraph in cell.paragraphs:
+            segments = [
+                OfficeRichTextSegment(
+                    text=run.text.replace("\n", " "),
+                    style=cls._run_styles(run),
+                    hyperlink=run.hyperlink,
+                )
+                for run in paragraph.runs
+                if run.text
+            ]
+            if content := build_rich_text_html_from_segments(segments, trim_plain_edges=True):
+                paragraphs.append(content)
+        return "<br/>".join(paragraphs)
+
+    @classmethod
+    def _table_html(cls, table: PptTableElement) -> str:
+        """按原点单元格生成带 rowspan/colspan 的稳定 HTML 表格。"""
+
+        origins = {(cell.row, cell.col): cell for cell in table.cells}
+        covered: set[tuple[int, int]] = set()
+        rows: list[str] = []
+        for row in range(table.rows):
+            cells: list[str] = []
+            for col in range(table.cols):
+                if (row, col) in covered:
+                    continue
+                cell = origins.get((row, col))
+                if cell is None:
+                    cells.append("<td></td>")
+                    continue
+                attributes: list[str] = []
+                if cell.row_span > 1:
+                    attributes.append(f'rowspan="{cell.row_span}"')
+                if cell.col_span > 1:
+                    attributes.append(f'colspan="{cell.col_span}"')
+                attribute_text = f" {' '.join(attributes)}" if attributes else ""
+                cells.append(f"<td{attribute_text}>{cls._table_cell_content(cell)}</td>")
+                for covered_row in range(row, row + cell.row_span):
+                    for covered_col in range(col, col + cell.col_span):
+                        if (covered_row, covered_col) != (row, col):
+                            covered.add((covered_row, covered_col))
+            rows.append(f"<tr>{''.join(cells)}</tr>")
+        return f'<table border="1">{"".join(rows)}</table>'
+
+    @classmethod
+    def _element_blocks(
+        cls,
+        element: PptTextElement | PptImageElement | PptEquationElement | PptChartElement | PptTableElement,
+        *,
+        slide_height: int,
+        is_first_text_element: bool,
+    ) -> list[dict[str, Any]]:
+        """把一个语义元素转换为 raw blocks。"""
+
+        if isinstance(element, PptImageElement):
+            return [{"type": BlockType.IMAGE, "image_base64": element.image_base64}]
+        if isinstance(element, PptEquationElement):
+            return [{"type": BlockType.EQUATION, "content": element.latex}]
+        if isinstance(element, PptChartElement):
+            block: dict[str, Any] = {
+                "type": BlockType.CHART,
+                "content": element.content,
+            }
+            if element.image_base64:
+                block["image_base64"] = element.image_base64
+            return [block]
+        if isinstance(element, PptTableElement):
+            return [{"type": BlockType.TABLE, "content": cls._table_html(element)}]
+
+        authoritative_title = element.text_type in {0, 6}
+        first_paragraph = element.paragraphs[0] if element.paragraphs else None
+        heuristic_title = bool(
+            is_first_text_element
+            and element.is_placeholder
+            and first_paragraph is not None
+            and first_paragraph.list_kind is None
+            and element.bbox[1] <= slide_height * 0.35
+            and len("".join(run.text for run in first_paragraph.runs).strip()) <= 200
+        )
+        return cls._text_element_blocks(
+            element,
+            title_candidate=authoritative_title or heuristic_title,
+        )
+
+    @classmethod
+    def _slide_to_page(cls, slide: PptSlide, presentation: PptPresentation) -> list[dict[str, Any]]:
+        """按 XYCut++ 排序一张幻灯片，并把备注稳定追加到末尾。"""
+
+        entries: list[dict[str, Any]] = []
+        text_seen = False
+        for element in slide.elements:
+            is_first_text = isinstance(element, PptTextElement) and not text_seen
+            blocks = cls._element_blocks(
+                element,
+                slide_height=presentation.height,
+                is_first_text_element=is_first_text,
+            )
+            if isinstance(element, PptTextElement) and blocks:
+                text_seen = True
+            if blocks:
+                entries.append({"bbox": element.bbox, "blocks": blocks, "order": element.order})
+        ordered_entries = sort_entries(
+            entries,
+            beta=PPT_XYCUT_BETA,
+            density_threshold=PPT_XYCUT_DENSITY_THRESHOLD,
+        )
+        page = [block for entry in ordered_entries for block in entry["blocks"]]
+        for paragraph in slide.notes:
+            content = cls._paragraph_content(paragraph)
+            if content:
+                page.append({"type": BlockType.PAGE_FOOTNOTE, "content": content})
+        return page
+
+    @classmethod
+    def _presentation_to_pages(cls, presentation: PptPresentation) -> list[list[dict[str, Any]]]:
+        """转换整份演示文稿，并把首个有效标题提升为文档标题。"""
+
+        pages = [cls._slide_to_page(slide, presentation) for slide in presentation.slides]
+        document_title_promoted = False
+        for page in pages:
+            candidates = [block for block in page if block.pop("_ppt_title_candidate", False)]
+            if not candidates:
+                continue
+            first = candidates[0]
+            if not document_title_promoted:
+                first["type"] = BlockType.DOC_TITLE
+                first["level"] = 1
+                document_title_promoted = True
+            for candidate in candidates[1:] if first["type"] == BlockType.DOC_TITLE else candidates:
+                candidate["type"] = BlockType.PARAGRAPH_TITLE
+                candidate["level"] = 2
+        return pages

docvortex/analyzers/native/office/ppt/records.py

@@ -0,0 +1,131 @@
+"""有界读取 MS-PPT 与 OfficeArt 记录流。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import struct
+from typing import Iterator
+
+from ..errors import LegacyOfficeMalformedError, LegacyOfficeResourceLimitError
+from ..limits import MAX_RECORD_DEPTH, MAX_RECORDS
+
+CONTAINER_VERSION = 0xF
+ROUNDTRIP_OPAQUE_MIN = 1053
+ROUNDTRIP_OPAQUE_MAX = 1064
+
+
+@dataclass(frozen=True, slots=True)
+class PptRecord:
+    """一条已验证边界的 PPT/OfficeArt 记录。"""
+
+    offset: int
+    version: int
+    instance: int
+    record_type: int
+    payload: bytes
+
+
+@dataclass(slots=True)
+class RecordBudget:
+    """跨解析阶段累计记录访问次数。"""
+
+    count: int = 0
+
+    def charge(self) -> None:
+        """计入一条记录，超过固定上限时硬失败。"""
+
+        self.count += 1
+        if self.count > MAX_RECORDS:
+            raise LegacyOfficeResourceLimitError(f"record stream exceeds max_records={MAX_RECORDS}")
+
+
+def record_at(
+    data: bytes,
+    offset: int,
+    *,
+    end: int | None = None,
+    strict: bool = False,
+    budget: RecordBudget | None = None,
+) -> PptRecord | None:
+    """读取指定偏移的单条记录；严格模式下把坏边界转换为稳定错误。"""
+
+    limit = len(data) if end is None else min(end, len(data))
+    if offset < 0 or offset + 8 > limit:
+        if strict:
+            raise LegacyOfficeMalformedError("PowerPoint record header is truncated")
+        return None
+    version_instance, record_type, length = struct.unpack_from("<HHI", data, offset)
+    payload_start = offset + 8
+    payload_end = payload_start + length
+    if payload_end < payload_start or payload_end > limit:
+        if strict:
+            raise LegacyOfficeMalformedError("PowerPoint record extends beyond its container")
+        return None
+    if budget is not None:
+        budget.charge()
+    return PptRecord(
+        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,
+    budget: RecordBudget | None = None,
+    strict_first: bool = False,
+) -> Iterator[PptRecord]:
+    """按顺序遍历同一容器内的记录，允许尾部生产器填充字节。"""
+
+    limit = len(data) if end is None else min(end, len(data))
+    cursor = start
+    first = True
+    while cursor < limit:
+        record = record_at(
+            data,
+            cursor,
+            end=limit,
+            strict=strict_first and first,
+            budget=budget,
+        )
+        if record is None:
+            return
+        yield record
+        cursor += 8 + len(record.payload)
+        first = False
+
+
+def iter_descendants(
+    record: PptRecord,
+    *,
+    budget: RecordBudget | None = None,
+) -> Iterator[PptRecord]:
+    """用显式栈深度优先遍历容器，跳过不可递归的 round-trip blob。"""
+
+    if record.version != CONTAINER_VERSION:
+        return
+    stack: list[tuple[bytes, Iterator[PptRecord]]] = [(record.payload, iter_records(record.payload, budget=budget))]
+    while stack:
+        if len(stack) > MAX_RECORD_DEPTH:
+            raise LegacyOfficeResourceLimitError(f"record nesting exceeds max_record_depth={MAX_RECORD_DEPTH}")
+        _, iterator = stack[-1]
+        try:
+            child = next(iterator)
+        except StopIteration:
+            stack.pop()
+            continue
+        yield child
+        if child.version == CONTAINER_VERSION and not ROUNDTRIP_OPAQUE_MIN <= child.record_type <= ROUNDTRIP_OPAQUE_MAX:
+            stack.append((child.payload, iter_records(child.payload, budget=budget)))
+
+
+def utf16_text(payload: bytes) -> str:
+    """容错解码 UTF-16LE 文本并移除末尾 NUL。"""
+
+    usable = payload[: len(payload) - (len(payload) % 2)]
+    return usable.decode("utf-16le", "replace").rstrip("\x00")

docvortex/analyzers/native/office/ppt/style_text.py

@@ -0,0 +1,247 @@
+"""解析 StyleTextPropAtom 与 TextMasterStyleAtom。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..legacy.binary import get_i16, get_u16, get_u32
+
+
+@dataclass(frozen=True, slots=True)
+class ParagraphRun:
+    """一段 UTF-16 文本范围对应的段落属性。"""
+
+    count: int
+    depth: int
+    bullet: bool | None = None
+    ordered: bool | None = None
+    start: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CharacterRun:
+    """一段 UTF-16 文本范围对应的字符属性。"""
+
+    count: int
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    strike: bool | None = None
+    baseline: int | None = None
+    pp9rt: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class MasterLevel:
+    """一个母版缩进层级的可继承默认值。"""
+
+    bullet: bool | None = None
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    baseline: int | None = None
+
+
+@dataclass(slots=True)
+class StyleRuns:
+    """同一文本形状的段落与字符属性序列。"""
+
+    paragraphs: list[ParagraphRun] = field(default_factory=list)
+    characters: list[CharacterRun] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class _CharacterStyle:
+    """TextCFException 解出的三态字符属性。"""
+
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    strike: bool | None = None
+    baseline: int | None = None
+    pp9rt: int = 0
+
+
+def _parse_paragraph_exception(
+    body: bytes,
+    position: int,
+) -> tuple[bool | None, int] | None:
+    """解析 TextPFException 并返回显式 bullet 状态与下一偏移。"""
+
+    mask = get_u32(body, position)
+    if mask is None:
+        return None
+    position += 4
+    bullet = None
+    if mask & 0x000F:
+        flags = get_u16(body, position)
+        if flags is None:
+            return None
+        if mask & 0x0001:
+            bullet = bool(flags & 0x0001)
+        position += 2
+    fixed_sizes = (
+        (0x0080, 2),
+        (0x0010, 2),
+        (0x0040, 2),
+        (0x0020, 4),
+        (0x0800, 2),
+        (0x1000, 2),
+        (0x2000, 2),
+        (0x4000, 2),
+        (0x0100, 2),
+        (0x0400, 2),
+        (0x8000, 2),
+    )
+    for property_mask, size in fixed_sizes:
+        if mask & property_mask:
+            position += size
+    if mask & 0x0010_0000:
+        tab_count = get_u16(body, position)
+        if tab_count is None:
+            return None
+        position += 2 + tab_count * 4
+    if mask & 0x0001_0000:
+        position += 2
+    if mask & 0x000E_0000:
+        position += 2
+    if mask & 0x0020_0000:
+        position += 2
+    if position > len(body):
+        return None
+    return bullet, position
+
+
+def _parse_character_exception(
+    body: bytes,
+    position: int,
+) -> tuple[_CharacterStyle, int] | None:
+    """解析 TextCFException，并保留每个可继承属性的三态值。"""
+
+    mask = get_u32(body, position)
+    if mask is None:
+        return None
+    position += 4
+    bold = italic = underline = strike = None
+    pp9rt = 0
+    if mask & 0xFFFF:
+        flags = get_u16(body, position)
+        if flags is None:
+            return None
+        if mask & 0x0001:
+            bold = bool(flags & 0x0001)
+        if mask & 0x0002:
+            italic = bool(flags & 0x0002)
+        if mask & 0x0004:
+            underline = bool(flags & 0x0004)
+        # 一些生产器把删除线写入扩展 style 位；未声明时继续继承。
+        if mask & 0x0100:
+            strike = bool(flags & 0x0100)
+        # fontStyle 的 4 位 pp9rt 选择 StyleTextProp9 数组条目。
+        pp9rt = (flags >> 10) & 0xF
+        position += 2
+    for property_mask in (0x0001_0000, 0x0020_0000, 0x0040_0000, 0x0080_0000):
+        if mask & property_mask:
+            position += 2
+    if mask & 0x0002_0000:
+        position += 2
+    if mask & 0x0004_0000:
+        position += 4
+    baseline = None
+    if mask & 0x0008_0000:
+        baseline = get_i16(body, position)
+        if baseline is None:
+            return None
+        position += 2
+    if position > len(body):
+        return None
+    return (
+        _CharacterStyle(
+            bold=bold,
+            italic=italic,
+            underline=underline,
+            strike=strike,
+            baseline=baseline,
+            pp9rt=pp9rt,
+        ),
+        position,
+    )
+
+
+def parse_style_text(body: bytes, text_utf16_length: int) -> StyleRuns:
+    """按 UTF-16 单元长度解析一个 StyleTextPropAtom。"""
+
+    runs = StyleRuns()
+    position = 0
+    covered = 0
+    while covered <= text_utf16_length:
+        count = get_u32(body, position)
+        depth = get_u16(body, position + 4)
+        if count is None or depth is None:
+            break
+        position += 6
+        parsed = _parse_paragraph_exception(body, position)
+        if parsed is None:
+            return runs
+        bullet, position = parsed
+        runs.paragraphs.append(ParagraphRun(count=int(count), depth=min(int(depth), 8), bullet=bullet))
+        covered += int(count)
+        if count == 0:
+            break
+
+    covered = 0
+    while covered <= text_utf16_length:
+        count = get_u32(body, position)
+        if count is None:
+            break
+        position += 4
+        parsed = _parse_character_exception(body, position)
+        if parsed is None:
+            break
+        style, position = parsed
+        runs.characters.append(
+            CharacterRun(
+                count=int(count),
+                bold=style.bold,
+                italic=style.italic,
+                underline=style.underline,
+                strike=style.strike,
+                baseline=style.baseline,
+                pp9rt=style.pp9rt,
+            )
+        )
+        covered += int(count)
+        if count == 0:
+            break
+    return runs
+
+
+def parse_master_style(body: bytes, instance: int) -> list[MasterLevel]:
+    """解析 TextMasterStyleAtom 的逐层默认字符与列表属性。"""
+
+    level_count = get_u16(body, 0)
+    if level_count is None:
+        return []
+    position = 2
+    result: list[MasterLevel] = []
+    for _ in range(min(int(level_count), 10)):
+        if instance >= 5:
+            position += 2
+        parsed_paragraph = _parse_paragraph_exception(body, position)
+        if parsed_paragraph is None:
+            break
+        bullet, position = parsed_paragraph
+        parsed_character = _parse_character_exception(body, position)
+        if parsed_character is None:
+            break
+        style, position = parsed_character
+        result.append(
+            MasterLevel(
+                bullet=bullet,
+                bold=style.bold,
+                italic=style.italic,
+                underline=style.underline,
+                baseline=style.baseline,
+            )
+        )
+    return result

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

@@ -0,0 +1,3 @@
+"""Flash PPTX 转换实现。"""
+
+__all__: list[str] = []