docvortex 0.2.1__py3-none-any.whl

docvortex/render/__init__.py

@@ -0,0 +1,48 @@
+from .api import render
+from .contracts import (
+    AssetResolver,
+    DocxRenderOptions,
+    EpubRenderOptions,
+    HtmlRenderOptions,
+    ImageRenderer,
+    LatexRenderOptions,
+    MarkdownRenderOptions,
+    PdfRenderOptions,
+    RenderFormat,
+    RenderMode,
+    RenderOptions,
+    RenderOutput,
+    StructuredContentRenderOptions,
+)
+from .docx import DocxRenderError, render_docx
+from .epub import render_epub
+from .html import render_html
+from .latex import render_latex
+from .markdown import render_markdown
+from .pdf import render_pdf
+from .structured_content import render_structured_content
+
+__all__ = [
+    "AssetResolver",
+    "DocxRenderError",
+    "DocxRenderOptions",
+    "EpubRenderOptions",
+    "HtmlRenderOptions",
+    "ImageRenderer",
+    "LatexRenderOptions",
+    "MarkdownRenderOptions",
+    "PdfRenderOptions",
+    "RenderFormat",
+    "RenderMode",
+    "RenderOptions",
+    "RenderOutput",
+    "StructuredContentRenderOptions",
+    "render",
+    "render_docx",
+    "render_epub",
+    "render_html",
+    "render_latex",
+    "render_markdown",
+    "render_pdf",
+    "render_structured_content",
+]

docvortex/render/_internal/__init__.py

@@ -0,0 +1,3 @@
+"""DocVortex renderer 的非公共实现模块。"""
+
+__all__: list[str] = []

docvortex/render/_internal/common/__init__.py

@@ -0,0 +1,3 @@
+"""各输出格式共用的渲染语义与规划实现。"""
+
+__all__: list[str] = []

docvortex/render/_internal/common/context.py

@@ -0,0 +1,43 @@
+"""在一次内部渲染调用中传递独占副本，不缓存用户的可变文档。"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Iterator
+
+from ....schema import MiddleJson
+
+
+@dataclass(slots=True)
+class _OwnedRenderDocument:
+    """只允许一个规划器消费当前调用已经隔离的文档。"""
+
+    document: MiddleJson
+    consumed: bool = False
+
+
+_owned_document: ContextVar[_OwnedRenderDocument | None] = ContextVar("docvortex_owned_render_document", default=None)
+
+
+@contextmanager
+def owned_render_document(document: MiddleJson) -> Iterator[None]:
+    """限定独占文档的调用范围，异常和重入后均恢复外层上下文。"""
+    token = _owned_document.set(_OwnedRenderDocument(document))
+    try:
+        yield
+    finally:
+        _owned_document.reset(token)
+
+
+def claim_owned_document(document: MiddleJson) -> bool:
+    """仅复用当前调用的精确对象一次，回调重入必须重新隔离。"""
+    context = _owned_document.get()
+    if context is None or context.document is not document or context.consumed:
+        return False
+    context.consumed = True
+    return True
+
+
+__all__ = ["owned_render_document", "claim_owned_document"]

docvortex/render/_internal/common/html_table.py

@@ -0,0 +1,178 @@
+"""多格式 renderer 共用的有界 HTML table 占位网格解析。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import TypeAlias
+
+from bs4 import BeautifulSoup, Tag
+
+MAX_NESTED_TABLE_DEPTH = 4
+MAX_TABLE_ROWS = 500
+MAX_TABLE_COLUMNS = 100
+MAX_TABLE_SLOTS = 10_000
+_POSITIVE_INTEGER_RE = re.compile(r"[0-9]+")
+
+HtmlTableSource: TypeAlias = str | BeautifulSoup | Tag
+
+
+class HtmlTableError(ValueError):
+    """表示 HTML table 无法安全解析为严格矩形网格。"""
+
+
+@dataclass(frozen=True, slots=True)
+class HtmlTableCell:
+    """保存原始 HTML 单元格在逻辑占位网格中的位置。"""
+
+    tag: Tag
+    row: int
+    column: int
+    rowspan: int
+    colspan: int
+    is_header: bool
+
+    @property
+    def end_row(self) -> int:
+        """返回单元格占用的末行下标。"""
+        return self.row + self.rowspan - 1
+
+    @property
+    def end_column(self) -> int:
+        """返回单元格占用的末列下标。"""
+        return self.column + self.colspan - 1
+
+
+@dataclass(frozen=True, slots=True)
+class HtmlTableGrid:
+    """保存经过重叠、边界、规模与矩形校验的 HTML 表格网格。"""
+
+    tag: Tag
+    row_count: int
+    column_count: int
+    cells: tuple[HtmlTableCell, ...]
+    header_rows: tuple[int, ...]
+
+
+def parse_html_tables(source: HtmlTableSource) -> tuple[HtmlTableGrid, ...]:
+    """解析 source 中相对当前上下文的一个或多个顶层 table。"""
+    root = BeautifulSoup(source, "html.parser") if isinstance(source, str) else source
+    if not isinstance(root, (BeautifulSoup, Tag)):
+        raise HtmlTableError("HTML table source must be a string or BeautifulSoup Tag")
+    if isinstance(root, Tag) and root.name == "table":
+        table_tags = (root,)
+    else:
+        parent_table = root.find_parent("table") if isinstance(root, Tag) else None
+        table_tags = tuple(table for table in root.find_all("table") if table.find_parent("table") is parent_table)
+    if not table_tags:
+        raise HtmlTableError("HTML does not contain a top-level table")
+    return tuple(_parse_html_table(table) for table in table_tags)
+
+
+def _parse_html_table(table: Tag) -> HtmlTableGrid:
+    """把单个 table 标签解析为严格矩形占位网格。"""
+    if table.name != "table":
+        raise HtmlTableError("Expected a <table> tag")
+    rows = tuple(row for row in table.find_all("tr") if row.find_parent("table") is table)
+    if not rows or len(rows) > MAX_TABLE_ROWS:
+        raise HtmlTableError(f"Table row count must be between 1 and {MAX_TABLE_ROWS}")
+
+    occupied: dict[tuple[int, int], HtmlTableCell] = {}
+    cells: list[HtmlTableCell] = []
+    for row_index, row in enumerate(rows):
+        column_index = 0
+        for source_cell in row.find_all(("td", "th"), recursive=False):
+            while (row_index, column_index) in occupied:
+                column_index += 1
+            rowspan = _parse_span(source_cell, "rowspan")
+            colspan = _parse_span(source_cell, "colspan")
+            if row_index + rowspan > len(rows):
+                raise HtmlTableError(f"rowspan exceeds table bounds at row={row_index}, column={column_index}")
+            if column_index + colspan > MAX_TABLE_COLUMNS:
+                raise HtmlTableError(f"Table column count exceeds {MAX_TABLE_COLUMNS}")
+            coordinates = tuple(
+                (target_row, target_column)
+                for target_row in range(row_index, row_index + rowspan)
+                for target_column in range(column_index, column_index + colspan)
+            )
+            overlap = next((coordinate for coordinate in coordinates if coordinate in occupied), None)
+            if overlap is not None:
+                raise HtmlTableError(f"Cell span overlaps row={overlap[0]}, column={overlap[1]}")
+            placement = HtmlTableCell(
+                tag=source_cell,
+                row=row_index,
+                column=column_index,
+                rowspan=rowspan,
+                colspan=colspan,
+                is_header=source_cell.name == "th",
+            )
+            cells.append(placement)
+            occupied.update(dict.fromkeys(coordinates, placement))
+            if len(occupied) > MAX_TABLE_SLOTS:
+                raise HtmlTableError(f"Table occupancy exceeds {MAX_TABLE_SLOTS} slots")
+            column_index += colspan
+
+    if not occupied:
+        raise HtmlTableError("Table must contain at least one cell")
+    column_count = max(column for _, column in occupied) + 1
+    missing = next(
+        (
+            (row_index, column_index)
+            for row_index in range(len(rows))
+            for column_index in range(column_count)
+            if (row_index, column_index) not in occupied
+        ),
+        None,
+    )
+    if missing is not None:
+        raise HtmlTableError(f"Table occupancy is not rectangular at row={missing[0]}, column={missing[1]}")
+    header_rows = tuple(
+        row_index
+        for row_index, row in enumerate(rows)
+        if _row_belongs_to_thead(row, table)
+        or all(occupied[(row_index, column_index)].is_header for column_index in range(column_count))
+    )
+    return HtmlTableGrid(
+        tag=table,
+        row_count=len(rows),
+        column_count=column_count,
+        cells=tuple(cells),
+        header_rows=header_rows,
+    )
+
+
+def _parse_span(cell: Tag, attribute: str) -> int:
+    """读取严格正整数 rowspan/colspan，缺失时返回一。"""
+    raw_value = cell.get(attribute, "1")
+    if isinstance(raw_value, list):
+        raise HtmlTableError(f"Invalid {attribute}: {raw_value!r}")
+    value = str(raw_value).strip()
+    if _POSITIVE_INTEGER_RE.fullmatch(value) is None:
+        raise HtmlTableError(f"Invalid {attribute}: {raw_value!r}")
+    span = int(value)
+    if span < 1 or span > MAX_TABLE_SLOTS:
+        raise HtmlTableError(f"Invalid {attribute}: {raw_value!r}")
+    return span
+
+
+def _row_belongs_to_thead(row: Tag, table: Tag) -> bool:
+    """判断 tr 是否位于当前 table 的 thead 内。"""
+    parent = row.parent
+    while isinstance(parent, Tag) and parent is not table:
+        if parent.name == "thead":
+            return True
+        parent = parent.parent
+    return False
+
+
+__all__ = [
+    "HtmlTableCell",
+    "HtmlTableError",
+    "HtmlTableGrid",
+    "HtmlTableSource",
+    "MAX_NESTED_TABLE_DEPTH",
+    "MAX_TABLE_COLUMNS",
+    "MAX_TABLE_ROWS",
+    "MAX_TABLE_SLOTS",
+    "parse_html_tables",
+]

docvortex/render/_internal/common/index.py

@@ -0,0 +1,33 @@
+"""各格式共用的目录页码尾部识别与清理。"""
+
+from __future__ import annotations
+
+import re
+
+from ....content.inline import inline_plain_text, map_text_span_content, normalize_inline_spans, slice_inline_spans
+from ....schema import InlineSpan
+
+_INDEX_ROMAN_RE = re.compile(r"[ivxlcdm]+", re.IGNORECASE)
+
+
+def strip_index_page_tail(content: list[InlineSpan]) -> list[InlineSpan]:
+    """删除目录末尾可信页码，并把其余 tab 转换为普通空格。"""
+    content = normalize_inline_spans(content)
+    visible_text = inline_plain_text(content)
+    if "\t" not in visible_text:
+        return content
+    tab_offset = visible_text.rfind("\t")
+    tail_text = visible_text[tab_offset + 1 :].strip()
+    if looks_like_index_page_token(tail_text):
+        content = slice_inline_spans(content, 0, tab_offset)
+    return map_text_span_content(content, lambda value: value.replace("\t", " "))
+
+
+def looks_like_index_page_token(content: str) -> bool:
+    """判断目录 tab 后缀是否为数字、罗马数字或单字母页码。"""
+    if not content or len(content) > 12:
+        return False
+    return bool(content.isdigit() or _INDEX_ROMAN_RE.fullmatch(content) or re.fullmatch(r"[A-Za-z]", content))
+
+
+__all__ = ["looks_like_index_page_token", "strip_index_page_tail"]

docvortex/render/_internal/common/list_items.py

@@ -0,0 +1,158 @@
+"""各格式共用的列表 marker 解析与参考文献判定。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Literal, TypeAlias
+
+from ....content.inline import inline_plain_text, normalize_inline_spans, slice_inline_spans
+from ....schema import BlockType, InlineSpan, ListBlock
+
+ListItemKind: TypeAlias = Literal["unordered", "ordered", "explicit", "none"]
+OrderedListStyle: TypeAlias = Literal["decimal", "lower-alpha", "upper-alpha", "lower-roman", "upper-roman"]
+
+_LIST_ITEM_MARKER_RE = re.compile(
+    r"^(?P<leading>\s*)(?P<marker>"
+    r"(?P<unordered>[-*+])"
+    r"|(?P<ordered>\d+\.|[A-Za-z]\.|[IVXLCDMivxlcdm]{2,}\.)"
+    r"|(?P<explicit>\d+\)|\(\d+[.)]|[A-Za-z]\)|[IVXLCDMivxlcdm]{2,}\)|\[[^\]\n]+\])"
+    r")(?P<separator>\s+)(?P<body>.*)$",
+    re.DOTALL,
+)
+_LEADING_WHITESPACE_RE = re.compile(r"^[ \t]*")
+# 去除首部空白后，前五个可见字符内出现 Unicode 数字即视为单项命中。
+_REFERENCE_NUMBER_PREFIX_RE = re.compile(r"^\D{0,4}\d")
+_MARKDOWN_UNORDERED_MARKER_RE = re.compile(r"^[ \t]*-[ \t]+")
+_ROMAN_MARKER_RE = re.compile(r"[IVXLCDM]+", re.IGNORECASE)
+_CANONICAL_ROMAN_RE = re.compile(r"M{0,3}(?:CM|CD|D?C{0,3})(?:XC|XL|L?X{0,3})(?:IX|IV|V?I{0,3})")
+_ROMAN_VALUES = {"I": 1, "V": 5, "X": 10, "L": 50, "C": 100, "D": 500, "M": 1000}
+_MAX_NATIVE_ORDERED_VALUE = 1_000_000
+
+
+@dataclass(frozen=True, slots=True)
+class ListItem:
+    """保存一个列表条目的原始标记、正文与 HTML 所需分类。"""
+
+    marker: str | None
+    body: list[InlineSpan]
+    kind: ListItemKind
+    value: int | None
+    ordered_style: OrderedListStyle | None
+    leading: str
+    separator: str
+
+
+def parse_list_item_marker(content: list[InlineSpan]) -> ListItem:
+    """解析列表行首 marker；无法识别时仍拆出前导水平空白。"""
+    content = normalize_inline_spans(content)
+    visible_text = inline_plain_text(content)
+    match = _LIST_ITEM_MARKER_RE.match(visible_text)
+    if match is None:
+        leading_match = _LEADING_WHITESPACE_RE.match(visible_text)
+        leading = leading_match.group(0) if leading_match is not None else ""
+        return ListItem(
+            marker=None,
+            body=slice_inline_spans(content, len(leading)),
+            kind="none",
+            value=None,
+            ordered_style=None,
+            leading=leading,
+            separator="",
+        )
+
+    marker = match.group("marker")
+    if match.group("unordered") is not None:
+        kind: ListItemKind = "unordered"
+        value = None
+        ordered_style = None
+    elif match.group("ordered") is not None:
+        ordered = _ordered_marker_value(marker)
+        if ordered is None:
+            kind = "explicit"
+            value = None
+            ordered_style = None
+        else:
+            kind = "ordered"
+            value, ordered_style = ordered
+    else:
+        kind = "explicit"
+        value = None
+        ordered_style = None
+    return ListItem(
+        marker=marker,
+        body=slice_inline_spans(content, match.start("body")),
+        kind=kind,
+        value=value,
+        ordered_style=ordered_style,
+        leading=match.group("leading"),
+        separator=match.group("separator"),
+    )
+
+
+def _ordered_marker_value(marker: str) -> tuple[int, OrderedListStyle] | None:
+    """把有界且规范的点号 marker 转成序号；超限或畸形时返回 None。"""
+    stem = marker[:-1]
+    if re.fullmatch(r"(?:0|[1-9][0-9]*)", stem):
+        if len(stem) > 7:
+            return None
+        value = int(stem)
+        return (value, "decimal") if value <= _MAX_NATIVE_ORDERED_VALUE else None
+    # 单字符 i/v/x/l/c/d/m 固定按罗马数字解释，消除与字母序号的歧义。
+    if _ROMAN_MARKER_RE.fullmatch(stem):
+        if _CANONICAL_ROMAN_RE.fullmatch(stem.upper()) is None:
+            return None
+        style: OrderedListStyle = "upper-roman" if stem.isupper() else "lower-roman"
+        return _roman_marker_value(stem), style
+    if re.fullmatch(r"[A-Za-z]", stem) is None:
+        return None
+    style = "upper-alpha" if stem.isupper() else "lower-alpha"
+    return ord(stem.lower()) - ord("a") + 1, style
+
+
+def _roman_marker_value(marker: str) -> int:
+    """按减法记数规则计算罗马 marker 的数值，兼容 producer 的宽松组合。"""
+    total = 0
+    previous = 0
+    for character in reversed(marker.upper()):
+        current = _ROMAN_VALUES[character]
+        if current < previous:
+            total -= current
+        else:
+            total += current
+            previous = current
+    return total
+
+
+def has_markdown_unordered_marker(content: list[InlineSpan]) -> bool:
+    """判断条目是否已有 Markdown 短横线 marker，保持既有补 bullet 规则。"""
+    return _MARKDOWN_UNORDERED_MARKER_RE.match(inline_plain_text(normalize_inline_spans(content))) is not None
+
+
+def reference_list_needs_bullets(block: ListBlock) -> bool:
+    """按直属非空条目的数字前缀严格多数规则判断是否补无序 marker。"""
+    if block.sub_type != BlockType.REF_TEXT:
+        return False
+
+    item_count = 0
+    numbered_count = 0
+    for child in block.content:
+        if isinstance(child, ListBlock):
+            continue
+        visible_text = inline_plain_text(child.content).lstrip()
+        if not visible_text:
+            continue
+        item_count += 1
+        if _REFERENCE_NUMBER_PREFIX_RE.match(visible_text):
+            numbered_count += 1
+    return item_count > 0 and numbered_count * 2 <= item_count
+
+
+__all__ = [
+    "ListItem",
+    "ListItemKind",
+    "OrderedListStyle",
+    "has_markdown_unordered_marker",
+    "parse_list_item_marker",
+    "reference_list_needs_bullets",
+]

docvortex/render/_internal/common/planner.py

@@ -0,0 +1,140 @@
+"""各格式共用的逻辑块复制、延续合并与页面规划。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .context import claim_owned_document
+
+from ....content.table import merge_table_content
+from ...contracts import RenderMode
+from ....schema import (
+    MERGE_TRANSPARENT_BLOCK_TYPES,
+    BlockType,
+    ContinuableTextBlockBase,
+    ListBlock,
+    MiddleJson,
+    PageBlock,
+    InlineSpan,
+    RefTextBlock,
+    TableBlock,
+    TextBlock,
+)
+
+
+@dataclass(slots=True)
+class PlannedBlock:
+    """保存一个待渲染块及其来源页和文本延续片段。"""
+
+    page_idx: int
+    block: PageBlock
+    text_contents: list[list[InlineSpan]] = field(default_factory=list)
+    removed: bool = False
+
+
+def build_render_plan(
+    middle_json: MiddleJson,
+    mode: RenderMode = RenderMode.DEFAULT,
+) -> list[list[PlannedBlock]]:
+    """深拷贝 MiddleJson，并按模式生成不污染输入的逐页逻辑块计划。"""
+    owned = claim_owned_document(middle_json)
+    copied = middle_json if owned else middle_json.model_copy(deep=True)
+    pages = [
+        [
+            PlannedBlock(
+                page_idx=page.page_idx,
+                block=block,
+                text_contents=[block.content] if isinstance(block, ContinuableTextBlockBase) else [],
+            )
+            for block in page.blocks
+        ]
+        for page in copied.pages
+    ]
+    flattened = [planned for page in pages for planned in page]
+    _merge_continued_text_blocks(flattened, mode)
+    _merge_continued_list_blocks(flattened, mode, copy_on_merge=owned)
+    if mode is RenderMode.DEFAULT:
+        _merge_continued_table_blocks(flattened)
+    return pages
+
+
+def _merge_continued_text_blocks(blocks: list[PlannedBlock], mode: RenderMode) -> None:
+    """把无独立正文锚点的 continues_prev 文本吸收到最近的前序文本逻辑块。"""
+    previous_text: PlannedBlock | None = None
+    previous_reference: PlannedBlock | None = None
+    for current in blocks:
+        is_text = isinstance(current.block, TextBlock)
+        is_reference = isinstance(current.block, RefTextBlock)
+        previous = previous_text if is_text else previous_reference if is_reference else None
+        anchored = is_text and isinstance(current.block.anchor, str) and bool(current.block.anchor.strip())
+        if (
+            not current.removed
+            and isinstance(current.block, ContinuableTextBlockBase)
+            and current.block.continues_prev is True
+            and not anchored
+            and previous is not None
+            and not (mode is RenderMode.FULL and previous.page_idx != current.page_idx)
+        ):
+            previous.text_contents.extend(current.text_contents)
+            current.removed = True
+        if is_text and not current.removed:
+            previous_text = current
+        if is_reference:
+            if not current.removed:
+                previous_reference = current
+        elif current.block.type not in MERGE_TRANSPARENT_BLOCK_TYPES:
+            previous_reference = None
+
+
+def _merge_continued_list_blocks(blocks: list[PlannedBlock], mode: RenderMode, *, copy_on_merge: bool = False) -> None:
+    """把续接列表吸收到子类型一致的前序列表，参考文献可跨过合并透明块。"""
+    previous_list: PlannedBlock | None = None
+    previous_reference_list: PlannedBlock | None = None
+    copied: set[int] = set()
+    for current in blocks:
+        if not isinstance(current.block, ListBlock):
+            previous_list = None
+            if current.block.type not in MERGE_TRANSPARENT_BLOCK_TYPES:
+                previous_reference_list = None
+            continue
+        previous = previous_reference_list if current.block.sub_type == BlockType.REF_TEXT else previous_list
+        if (
+            not current.removed
+            and current.block.continues_prev is True
+            and previous is not None
+            and previous.block.sub_type == current.block.sub_type
+            and not (mode is RenderMode.FULL and previous.page_idx != current.page_idx)
+        ):
+            # EPUB 等渲染器仍读取原文档；只有实际修改的列表需要另建副本。
+            if copy_on_merge and id(previous) not in copied:
+                previous.block = previous.block.model_copy(deep=True)
+                copied.add(id(previous))
+            previous.block.content.extend(current.block.content)
+            current.removed = True
+        if not current.removed:
+            previous_list = previous_reference_list = current
+
+
+def _merge_continued_table_blocks(blocks: list[PlannedBlock]) -> None:
+    """在默认模式中把跨页续表合并到最近的前序表格。"""
+    previous: PlannedBlock | None = None
+    for current in blocks:
+        if current.removed or not isinstance(current.block, TableBlock):
+            continue
+        if current.block.continues_prev is True and previous is not None and previous.page_idx != current.page_idx:
+            merged = merge_table_content(
+                previous.block.model_dump(mode="python", exclude_none=True),
+                current.block.model_dump(mode="python", exclude_none=True),
+            )
+            if merged is not None:
+                try:
+                    previous.block = TableBlock.model_validate(merged)
+                except (TypeError, ValueError):
+                    pass
+                else:
+                    current.removed = True
+        if not current.removed:
+            previous = current
+
+
+__all__ = ["PlannedBlock", "build_render_plan"]

docvortex/render/_internal/docx/__init__.py

@@ -0,0 +1,3 @@
+"""DOCX renderer 的内部实现。"""
+
+__all__: list[str] = []