docvortex 0.2.1__py3-none-any.whl

docvortex/content/spans.py

@@ -0,0 +1,183 @@
+"""Flash 各格式构造 Middle JSON 2.0 行内 Span 的轻量工具。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ..schema import (
+    INLINE_STYLE_ORDER,
+    CodeInlineSpan,
+    EquationInlineSpan,
+    HyperlinkSpan,
+    InlineSpan,
+    TextSpan,
+    parse_inline_spans,
+)
+
+
+def append_text_span(output: list[dict[str, Any]], content: str, styles: Iterable[str] = ()) -> None:
+    """追加非空 TextSpan，并合并相邻同样式文字。"""
+    if not content:
+        return
+    style_set = set(styles)
+    normalized_styles = [style for style in INLINE_STYLE_ORDER if style in style_set]
+    if output and output[-1].get("type") == "text" and output[-1].get("styles", []) == normalized_styles:
+        output[-1]["content"] = f"{output[-1].get('content', '')}{content}"
+        return
+    span: dict[str, Any] = {"type": "text", "content": content}
+    if normalized_styles:
+        span["styles"] = normalized_styles
+    output.append(span)
+
+
+def text_spans(content: str, styles: Iterable[str] = ()) -> list[dict[str, Any]]:
+    """把一段文字构造成零个或一个规范 TextSpan。"""
+    output: list[dict[str, Any]] = []
+    append_text_span(output, content, styles)
+    return output
+
+
+def append_equation_span(output: list[dict[str, Any]], latex: str) -> None:
+    """追加非空行内公式 Span。"""
+    normalized = latex.strip()
+    if normalized:
+        output.append({"type": "equation_inline", "content": normalized})
+
+
+def append_code_span(output: list[dict[str, Any]], content: str) -> None:
+    """追加非空行内代码 Span。"""
+    if content:
+        output.append({"type": "code_inline", "content": content})
+
+
+def append_hyperlink_span(output: list[dict[str, Any]], children: list[dict[str, Any]], url: str | None) -> None:
+    """追加安全超链接；目标缺失时把标签子 Span 直接降级为普通内容。"""
+    if not children:
+        return
+    normalized_url = (url or "").strip()
+    if not normalized_url:
+        extend_inline_spans(output, children)
+        return
+    non_link_children = [child for child in children if child.get("type") != "hyperlink"]
+    if not non_link_children:
+        return
+    output.append({"type": "hyperlink", "url": normalized_url, "content": non_link_children})
+
+
+def extend_inline_spans(output: list[dict[str, Any]], spans: Iterable[dict[str, Any]]) -> None:
+    """追加 Span 序列，并在边界合并同样式文字。"""
+    for span in spans:
+        if span.get("type") == "text" and isinstance(span.get("content"), str):
+            append_text_span(output, str(span["content"]), span.get("styles", []))
+        else:
+            output.append(span)
+
+
+def normalize_span_dicts(spans: Iterable[dict[str, Any] | InlineSpan]) -> list[dict[str, Any]]:
+    """严格校验 Span 并返回确定性的 JSON 字典列表。"""
+    parsed = parse_inline_spans(list(spans))
+    output: list[dict[str, Any]] = []
+    for span in parsed:
+        payload = span.model_dump(mode="json")
+        if payload.get("type") == "text":
+            append_text_span(output, str(payload["content"]), payload.get("styles", []))
+        else:
+            output.append(payload)
+    return output
+
+
+def inline_span_plain_text(spans: Iterable[dict[str, Any]]) -> str:
+    """从 raw Span 字典中提取可见文本。"""
+    parts: list[str] = []
+    for span in spans:
+        span_type = span.get("type")
+        if span_type in {"text", "equation_inline", "code_inline"}:
+            content = span.get("content")
+            if isinstance(content, str):
+                parts.append(content)
+        elif span_type == "hyperlink":
+            children = span.get("content")
+            if isinstance(children, list):
+                parts.append(inline_span_plain_text(child for child in children if isinstance(child, dict)))
+    return "".join(parts)
+
+
+def slice_span_dicts(
+    spans: Iterable[dict[str, Any] | InlineSpan], start: int = 0, end: int | None = None
+) -> list[dict[str, Any]]:
+    """按可见字符偏移裁剪 raw Span，并保留样式和链接。"""
+    parsed = parse_inline_spans(list(spans))
+    visible_length = len(_typed_plain_text(parsed))
+    resolved_start = min(max(start, 0), visible_length)
+    resolved_end = visible_length if end is None else min(max(end, resolved_start), visible_length)
+    output: list[InlineSpan] = []
+    cursor = 0
+    for span in parsed:
+        span_length = len(_typed_plain_text([span]))
+        span_end = cursor + span_length
+        overlap_start = max(resolved_start, cursor)
+        overlap_end = min(resolved_end, span_end)
+        if overlap_start < overlap_end:
+            sliced = _slice_typed_span(span, overlap_start - cursor, overlap_end - cursor)
+            if sliced is not None:
+                output.append(sliced)
+        cursor = span_end
+        if cursor >= resolved_end:
+            break
+    return normalize_span_dicts(output)
+
+
+def strip_span_dicts(spans: Iterable[dict[str, Any] | InlineSpan]) -> list[dict[str, Any]]:
+    """裁剪 Span 首尾空白，并保持内部样式与链接结构。"""
+    parsed = parse_inline_spans(list(spans))
+    visible = _typed_plain_text(parsed)
+    start = len(visible) - len(visible.lstrip())
+    end = len(visible.rstrip())
+    return slice_span_dicts(parsed, start, end)
+
+
+def _typed_plain_text(spans: Iterable[InlineSpan]) -> str:
+    """提取已验证 Span 的可见文本。"""
+    parts: list[str] = []
+    for span in spans:
+        if isinstance(span, (TextSpan, EquationInlineSpan, CodeInlineSpan)):
+            parts.append(span.content)
+        elif isinstance(span, HyperlinkSpan):
+            parts.append(_typed_plain_text(span.content))
+    return "".join(parts)
+
+
+def _slice_typed_span(span: InlineSpan, start: int, end: int) -> InlineSpan | None:
+    """裁剪一个已验证 Span 的局部区间。"""
+    if start >= end:
+        return None
+    if isinstance(span, TextSpan):
+        content = span.content[start:end]
+        return span.model_copy(update={"content": content}) if content else None
+    if isinstance(span, EquationInlineSpan):
+        content = span.content[start:end]
+        return span.model_copy(update={"content": content}) if content.strip() else None
+    if isinstance(span, CodeInlineSpan):
+        content = span.content[start:end]
+        return span.model_copy(update={"content": content}) if content else None
+    if isinstance(span, HyperlinkSpan):
+        children = slice_span_dicts(span.content, start, end)
+        parsed_children = parse_inline_spans(children)
+        non_links = [child for child in parsed_children if not isinstance(child, HyperlinkSpan)]
+        return span.model_copy(update={"content": non_links}) if non_links else None
+    return None
+
+
+__all__ = [
+    "append_code_span",
+    "append_equation_span",
+    "append_hyperlink_span",
+    "append_text_span",
+    "extend_inline_spans",
+    "inline_span_plain_text",
+    "normalize_span_dicts",
+    "slice_span_dicts",
+    "strip_span_dicts",
+    "text_spans",
+]

docvortex/content/table/__init__.py

@@ -0,0 +1,18 @@
+"""跨页表格结构检测和内容合并的稳定入口。"""
+
+from .content import merge_table_content
+from .document import merge_table
+from .html import build_row_rendered_cell_segments, build_table_state_from_html, calculate_row_rendered_segments
+from .structure import can_merge_by_structure, detect_table_headers
+from .structure import _expand_header_count_by_rowspan as expand_header_count_by_rowspan
+
+__all__ = [
+    "merge_table",
+    "merge_table_content",
+    "build_table_state_from_html",
+    "build_row_rendered_cell_segments",
+    "can_merge_by_structure",
+    "calculate_row_rendered_segments",
+    "detect_table_headers",
+    "expand_header_count_by_rowspan",
+]

docvortex/content/table/blocks.py

@@ -0,0 +1,152 @@
+"""DocVortex table block 的主体、辅助文本和 bbox 访问规则。"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from bs4 import BeautifulSoup
+
+from ...schema import BlockType
+
+from .html import _build_front_cache, _scan_rows
+from .models import MAX_HEADER_ROWS, BlockDict, CalculationBBox, TableMergeState
+from .rules import is_table_continuation_text
+
+
+def _bbox_for_calculation(bbox: Any) -> CalculationBBox | None:
+    """复制归一化 bbox 并放大为千分位整数，原始字段保持不变。"""
+    if not isinstance(bbox, (list, tuple)) or len(bbox) != 4:
+        return None
+    if any(isinstance(value, bool) or not isinstance(value, (int, float)) for value in bbox):
+        return None
+
+    values = tuple(float(value) for value in bbox)
+    if not all(math.isfinite(value) and 0 <= value <= 1 for value in values):
+        return None
+
+    x0, y0, x1, y1 = (int(round(value * 1000)) for value in values)
+    if x1 <= x0 or y1 <= y0:
+        return None
+    return x0, y0, x1, y1
+
+
+def _table_children(table_block: BlockDict) -> list[BlockDict]:
+    """读取 table 根块下的合法 dict 子块。"""
+    content = table_block.get("content")
+    if not isinstance(content, list):
+        return []
+    return [block for block in content if isinstance(block, dict)]
+
+
+def _find_table_body_block(table_block: BlockDict) -> BlockDict | None:
+    """查找 dict table block 中的主体子块。"""
+    for block in _table_children(table_block):
+        if block.get("type") == BlockType.TABLE_BODY:
+            return block
+    return None
+
+
+def _build_post_body_child_index(table_block: BlockDict, offset: int) -> int | None:
+    """为复制到前表的 footnote 生成表体后的安全 index。"""
+    body_block = _find_table_body_block(table_block)
+    if body_block is None:
+        return None
+    body_index = body_block.get("index")
+    if not isinstance(body_index, int):
+        return None
+
+    child_indices = [block.get("index") for block in _table_children(table_block) if isinstance(block.get("index"), int)]
+    return max([body_index, *child_indices]) + offset
+
+
+def _block_text(block: BlockDict) -> str:
+    """递归读取 dict block 的文本内容，供续表标记判断使用。"""
+    content = block.get("content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    return "".join(_block_text(child) for child in content if isinstance(child, dict))
+
+
+def _is_continuation_caption(caption_block: BlockDict) -> bool:
+    """判断 dict caption 文本是否带有续表标记。"""
+    return is_table_continuation_text(_block_text(caption_block))
+
+
+def _is_post_table_non_continuation_caption(table_block: BlockDict, caption_block: BlockDict) -> bool:
+    """判断 caption 是否是误挂到表格下方的新段落标题。
+
+    这类 caption 位于 table body 下方，且不含续表标记；它不应作为
+    当前表的新标题阻断跨页关系判断。
+    """
+    if _is_continuation_caption(caption_block):
+        return False
+
+    body_block = _find_table_body_block(table_block)
+    if body_block is None:
+        return False
+
+    body_bbox = _bbox_for_calculation(body_block.get("bbox"))
+    caption_bbox = _bbox_for_calculation(caption_block.get("bbox"))
+    if body_bbox is None or caption_bbox is None:
+        return False
+
+    return caption_bbox[1] >= body_bbox[3]
+
+
+def _build_table_state(table_block: BlockDict, max_header_rows: int = MAX_HEADER_ROWS) -> TableMergeState | None:
+    """从 dict table block 构建结构缓存，非法主体安全返回空。"""
+    body_block = _find_table_body_block(table_block)
+    if body_block is None:
+        return None
+
+    html = body_block.get("content")
+    if not isinstance(html, str) or not html:
+        return None
+
+    soup = BeautifulSoup(html, "html.parser")
+    tbody = soup.find("tbody") or soup.find("table")
+    rows = soup.find_all("tr")
+    if tbody is None or not rows:
+        return None
+
+    scan = _scan_rows(rows)
+    if scan.total_cols <= 0 or scan.last_nonempty_row_metrics is None:
+        return None
+    front_header_info, front_first_data_row_metrics = _build_front_cache(rows, max_header_rows=max_header_rows)
+
+    return TableMergeState(
+        owner_block=table_block,
+        body_block=body_block,
+        soup=soup,
+        tbody=tbody,
+        rows=rows,
+        total_cols=scan.total_cols,
+        front_header_info=front_header_info,
+        front_first_data_row_metrics=front_first_data_row_metrics,
+        last_data_row_metrics=scan.last_nonempty_row_metrics,
+        row_effective_cols=scan.row_effective_cols,
+        tail_occupied=scan.tail_occupied,
+    )
+
+
+def _get_or_create_table_state(
+    table_block: BlockDict,
+    state_cache: dict[int, TableMergeState],
+    max_header_rows: int = MAX_HEADER_ROWS,
+) -> TableMergeState | None:
+    """按 table dict 对象身份复用 HTML 结构扫描结果。"""
+    cache_key = id(table_block)
+    state = state_cache.get(cache_key)
+    if state is not None:
+        return state
+
+    try:
+        state = _build_table_state(table_block, max_header_rows=max_header_rows)
+    except (AssertionError, TypeError, ValueError):
+        return None
+    if state is not None:
+        state_cache[cache_key] = state
+    return state