docvortex 0.4.0__tar.gz → 0.4.1__tar.gz

{docvortex-0.4.0/src/docvortex.egg-info → docvortex-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.0
+Version: 0.4.1
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex
@@ -177,7 +177,11 @@ DocVortex markers and semantic round trips.
 ## Scope and development
 
 PDF output is a semantic reflow of the document, not a lossless reproduction of
-the original page drawing instructions. Input support for PPTX/XLSX does not imply
+the original page drawing instructions. Short paragraphs (up to a quarter of the
+content area height) and short tables including annotations (up to half) stay
+together when possible. Longer content can paginate; tables repeat existing
+headers, and images scale to fit while keeping short captions on the same page.
+Input support for PPTX/XLSX does not imply
 PPTX/XLSX output support. Rust implementation work is a future stage behind these
 public data and processing boundaries.
 

{docvortex-0.4.0 → docvortex-0.4.1}/README.md

@@ -124,7 +124,11 @@ DocVortex markers and semantic round trips.
 ## Scope and development
 
 PDF output is a semantic reflow of the document, not a lossless reproduction of
-the original page drawing instructions. Input support for PPTX/XLSX does not imply
+the original page drawing instructions. Short paragraphs (up to a quarter of the
+content area height) and short tables including annotations (up to half) stay
+together when possible. Longer content can paginate; tables repeat existing
+headers, and images scale to fit while keeping short captions on the same page.
+Input support for PPTX/XLSX does not imply
 PPTX/XLSX output support. Rust implementation work is a future stage behind these
 public data and processing boundaries.
 

docvortex-0.4.1/src/docvortex/render/_internal/pdf/pagination.py

@@ -0,0 +1,193 @@
+"""按实际排版高度保护短语义块，并保留长表格的分页能力。"""
+
+from __future__ import annotations
+
+from reportlab.pdfgen.canvas import Canvas
+from reportlab.platypus import Flowable, Image, KeepTogether, Paragraph, Table
+from reportlab.platypus.flowables import _Container, _listWrapOn
+
+PARAGRAPH_KEEP_RATIO = 0.25
+TABLE_KEEP_RATIO = 0.5
+
+
+class _FlowableGroup(Flowable):
+    """提供可测量的容器，同时允许 ReportLab 将前面的标题与容器绑定。"""
+
+    def __init__(self, content: list[Flowable]) -> None:
+        """保存有序子项，不继承会被标题绑定逻辑排除的内部容器基类。"""
+        super().__init__()
+        self._content = content
+
+    def wrap(self, availWidth: float, availHeight: float) -> tuple[float, float]:
+        """测量真实高度，使外层标题绑定逻辑可以正确判断剩余空间。"""
+        self.width, self.height = _listWrapOn(self._content, availWidth, self.canv)
+        return self.width, self.height
+
+    def getSpaceBefore(self) -> float:
+        """把第一个子项的外侧间距交给内容框处理。"""
+        return self._content[0].getSpaceBefore()
+
+    def getSpaceAfter(self) -> float:
+        """把最后一个子项的外侧间距交给内容框处理。"""
+        return self._content[-1].getSpaceAfter()
+
+    def drawOn(self, canv: Canvas, x: float, y: float, _sW: float = 0) -> None:
+        """复用 ReportLab 容器绘制，保持子项对齐、链接及合并间距。"""
+        _Container.drawOn(self, canv, x, y, _sW=_sW)
+
+
+class _MeasuredKeepTogether(_FlowableGroup):
+    """以真实高度参与排版，并在空间不足时委托 KeepTogether 换页。"""
+
+    def split(self, availWidth: float, availHeight: float) -> list[Flowable]:
+        """保留 KeepTogether 对超高内容的降级，避免保护规则导致无限换页。"""
+        group = KeepTogether(self._content)
+        group._frame = getattr(self, "_frame", None)
+        return group.splitOn(self.canv, availWidth, availHeight)
+
+
+def _measure(content: list[Flowable], width: float, canvas: Canvas) -> float:
+    """测量合并相邻间距后的高度，不包含整个容器的外侧间距。"""
+    return _listWrapOn(content, width, canvas)[1] if content else 0.0
+
+
+def _total_height(content: list[Flowable], width: float, canvas: Canvas) -> float:
+    """计算用于保护阈值判断的完整高度，包含首尾外侧间距。"""
+    if not content:
+        return 0.0
+    return _measure(content, width, canvas) + content[0].getSpaceBefore() + content[-1].getSpaceAfter()
+
+
+def protect_paragraphs(content: list[Flowable], *, width: float, height: float, canvas: Canvas) -> list[Flowable]:
+    """逐段保护短文本，避免把整个列表绑定为不可分页的大块。"""
+    return [
+        _MeasuredKeepTogether([item])
+        if isinstance(item, Paragraph) and _total_height([item], width, canvas) <= height * PARAGRAPH_KEEP_RATIO
+        else item
+        for item in content
+    ]
+
+
+def protect_images(content: list[Flowable], *, width: float, height: float, canvas: Canvas) -> list[Flowable]:
+    """绑定图片和简短说明，多图超过整页时按图片主体边界降级分页。"""
+    if not content:
+        return []
+    images = [item for item in content if isinstance(item, Image)]
+    notes = [item for item in content if not isinstance(item, Image)]
+    short_notes = _total_height(notes, width, canvas) <= height * PARAGRAPH_KEEP_RATIO
+    if len(images) == 1 and short_notes:
+        image = images[0]
+        overhead = _total_height(content, width, canvas) - image.drawHeight
+        limit = max(1.0, height - overhead)
+        if image.drawHeight > limit:
+            image.drawWidth *= limit / image.drawHeight
+            image.drawHeight = limit
+    if short_notes and _total_height(content, width, canvas) <= height + 1e-6:
+        return [_MeasuredKeepTogether(content)]
+    if len(images) > 1:
+        result: list[Flowable] = []
+        group: list[Flowable] = []
+        has_image = False
+        for item in content:
+            if isinstance(item, Image) and has_image:
+                result.extend(protect_images(group, width=width, height=height, canvas=canvas))
+                group = []
+            group.append(item)
+            has_image = has_image or isinstance(item, Image)
+        result.extend(protect_images(group, width=width, height=height, canvas=canvas))
+        return result
+    if len(images) == 1:
+        # 超长脚注不应解除图片与相邻短图注的绑定；只把超出预算的说明放回文本流。
+        start = content.index(images[0])
+        end = start + 1
+        selected_notes: list[Flowable] = []
+        while start > 0:
+            candidate = [content[start - 1], *selected_notes]
+            if _total_height(candidate, width, canvas) > height * PARAGRAPH_KEEP_RATIO:
+                break
+            selected_notes = candidate
+            start -= 1
+        while end < len(content):
+            candidate = [*selected_notes, content[end]]
+            if _total_height(candidate, width, canvas) > height * PARAGRAPH_KEEP_RATIO:
+                break
+            selected_notes = candidate
+            end += 1
+        return [
+            *protect_paragraphs(content[:start], width=width, height=height, canvas=canvas),
+            *protect_images(content[start:end], width=width, height=height, canvas=canvas),
+            *protect_paragraphs(content[end:], width=width, height=height, canvas=canvas),
+        ]
+    return protect_paragraphs(content, width=width, height=height, canvas=canvas)
+
+
+class _AnnotatedTable(_FlowableGroup):
+    """让前置说明跟随表格首段，后置说明跟随最后一段。"""
+
+    def __init__(self, table: Table, before: list[Flowable], after: list[Flowable]) -> None:
+        """保存原生表格及说明，继续由 ReportLab 处理表头与合并单元格。"""
+        super().__init__([*before, table, *after])
+        self.table = table
+        self.before = before
+        self.after = after
+
+    def split(self, availWidth: float, availHeight: float) -> list[Flowable]:
+        """分页时只拆表格主体，并为末段保留简短说明所需的高度。"""
+        table_height = self.table.wrapOn(self.canv, availWidth, 0xFFFFFF)[1]
+        before_height = _measure([*self.before, self.table], availWidth, self.canv) - table_height
+        after_height = _measure([self.table, *self.after], availWidth, self.canv) - table_height
+        budget = availHeight - before_height
+        if table_height <= budget + 1e-6:
+            budget -= after_height
+        if budget <= 0:
+            return []
+        # 将容器所在页的位置传给表格，避免在页尾提前拆开普通单元格。
+        previous_frame = getattr(self.table, "_frame", None)
+        self.table._frame = getattr(self, "_frame", None)
+        try:
+            parts = self.table.splitOn(self.canv, availWidth, budget)
+        finally:
+            if previous_frame is None:
+                del self.table._frame
+            else:
+                self.table._frame = previous_frame
+        if len(parts) < 2:
+            return []
+        return [
+            _MeasuredKeepTogether([*self.before, *parts[:-1]]),
+            _AnnotatedTable(parts[-1], [], self.after),
+        ]
+
+
+def protect_tables(content: list[Flowable], *, width: float, height: float, canvas: Canvas) -> list[Flowable]:
+    """保护短表整体，并按表格主体分组处理长表的前后说明。"""
+    if not content:
+        return []
+    if _total_height(content, width, canvas) <= height * TABLE_KEEP_RATIO:
+        return [_MeasuredKeepTogether(content)]
+    result: list[Flowable] = []
+    pending: list[Flowable] = []
+    table: Table | None = None
+    before: list[Flowable] = []
+    for item in [*content, None]:
+        if isinstance(item, Table) or item is None:
+            if table is not None:
+                after = pending
+                if _total_height(after, width, canvas) > height * PARAGRAPH_KEEP_RATIO:
+                    result.append(_AnnotatedTable(table, before, []) if before else table)
+                    result.extend(protect_paragraphs(after, width=width, height=height, canvas=canvas))
+                else:
+                    result.append(_AnnotatedTable(table, before, after) if before or after else table)
+                before = []
+            else:
+                before = pending
+                if _total_height(before, width, canvas) > height * PARAGRAPH_KEEP_RATIO:
+                    result.extend(protect_paragraphs(before, width=width, height=height, canvas=canvas))
+                    before = []
+            table = item
+            pending = []
+        else:
+            pending.append(item)
+    if table is None and before:
+        result.extend(protect_paragraphs(before, width=width, height=height, canvas=canvas))
+    return result

{docvortex-0.4.0 → docvortex-0.4.1}/src/docvortex/render/_internal/pdf/renderer.py

@@ -15,10 +15,12 @@ from reportlab.lib.styles import ParagraphStyle
 from reportlab.lib.units import mm
 from reportlab.pdfgen.canvas import Canvas
 from reportlab.platypus import (
+    BaseDocTemplate,
     Flowable,
+    Frame,
     Image as ReportLabImage,
     Paragraph,
-    SimpleDocTemplate,
+    PageTemplate,
     Spacer,
     Table,
     TableStyle,
@@ -73,7 +75,8 @@ from .formula import (
     split_formula_tag,
 )
 from .inline import PdfAnchorRegistry, PdfInlineContext, build_pdf_paragraph, render_plain_text_markup
-from .styles import BORDER_COLOR, PAGE_MARGIN, SURFACE_COLOR, build_pdf_styles
+from .pagination import protect_images, protect_paragraphs, protect_tables
+from .styles import BORDER_COLOR, FRAME_PADDING, PAGE_MARGIN, SURFACE_COLOR, build_pdf_styles
 from .table import PdfTableError, build_pdf_tables
 
 _HTML_TABLE_RE = re.compile(r"<table\b", re.IGNORECASE)
@@ -166,8 +169,8 @@ class _PdfRenderer:
         self.asset_resolver = asset_resolver
         self.document_title = _resolve_document_title(middle_json, document_title)
         self.styles = build_pdf_styles()
-        self.available_width = A4[0] - 2 * PAGE_MARGIN
-        self.available_height = A4[1] - 2 * PAGE_MARGIN
+        self.available_width = A4[0] - 2 * (PAGE_MARGIN + FRAME_PADDING)
+        self.available_height = A4[1] - 2 * (PAGE_MARGIN + FRAME_PADDING)
         self.inline_context = PdfInlineContext(
             formulas=FormulaRenderer(),
             anchors=PdfAnchorRegistry(_iter_document_anchors(middle_json)),
@@ -176,6 +179,12 @@ class _PdfRenderer:
     def render(self) -> bytes:
         """构造逐页 story，并将确定性 ReportLab 文档序列化为 bytes。"""
         story: list[Flowable] = []
+        measure_canvas = Canvas(BytesIO())
+        pagination_options = {
+            "width": self.available_width,
+            "height": self.available_height,
+            "canvas": measure_canvas,
+        }
         planned_pages = build_render_plan(self.middle_json)
         for planned_blocks in planned_pages:
             for planned in planned_blocks:
@@ -184,12 +193,25 @@ class _PdfRenderer:
                 if planned.block.type in PAGE_AUXILIARY_BLOCK_TYPES:
                     continue
                 rendered = self._render_planned_block(planned)
+                if isinstance(planned.block, (ImageBlock, TableBlock, ChartBlock)):
+                    # 标题计入图表的首段预算，避免满页图片或长表把标题单独留在前页。
+                    while story and isinstance(story[-1], Paragraph) and story[-1].getKeepWithNext():
+                        rendered.insert(0, story.pop())
+                if isinstance(planned.block, (TextBlock, RefTextBlock, ListBlock)):
+                    rendered = protect_paragraphs(rendered, **pagination_options)
+                elif isinstance(planned.block, ImageBlock):
+                    rendered = protect_images(rendered, **pagination_options)
+                elif isinstance(planned.block, (TableBlock, ChartBlock)):
+                    if any(isinstance(item, ReportLabImage) for item in rendered):
+                        rendered = protect_images(rendered, **pagination_options)
+                    else:
+                        rendered = protect_tables(rendered, **pagination_options)
                 story.extend(rendered)
         if not story:
             story.append(Spacer(1, 1))
 
         output = BytesIO()
-        document = SimpleDocTemplate(
+        document = BaseDocTemplate(
             output,
             pagesize=A4,
             leftMargin=PAGE_MARGIN,
@@ -204,6 +226,24 @@ class _PdfRenderer:
             invariant=1,
             pageCompression=1,
         )
+        document.addPageTemplates(
+            PageTemplate(
+                id="normal",
+                frames=[
+                    Frame(
+                        PAGE_MARGIN,
+                        PAGE_MARGIN,
+                        A4[0] - 2 * PAGE_MARGIN,
+                        A4[1] - 2 * PAGE_MARGIN,
+                        leftPadding=FRAME_PADDING,
+                        rightPadding=FRAME_PADDING,
+                        topPadding=FRAME_PADDING,
+                        bottomPadding=FRAME_PADDING,
+                        id="normal",
+                    )
+                ],
+            )
+        )
         document.build(
             story,
             canvasmaker=partial(_PdfCanvas, document_title=self.document_title),
@@ -598,7 +638,7 @@ class _PdfRenderer:
             desired_width = available_width * (block.bbox[2] - block.bbox[0])
         desired_width = max(min(_MIN_IMAGE_WIDTH, available_width), min(desired_width, available_width))
         desired_height = desired_width * prepared.height_px / max(prepared.width_px, 1)
-        max_height = self.available_height
+        max_height = self.available_height - 10
         if desired_height > max_height:
             scale = max_height / desired_height
             desired_width *= scale

{docvortex-0.4.0 → docvortex-0.4.1}/src/docvortex/render/_internal/pdf/styles.py

@@ -14,6 +14,7 @@ from reportlab.pdfbase import cidfonts, pdfmetrics
 from reportlab.pdfbase.ttfonts import TTFont
 
 PAGE_MARGIN = 20 * mm
+FRAME_PADDING = 6.0
 BODY_FONT = "Helvetica"
 BODY_BOLD_FONT = "Helvetica-Bold"
 MONO_FONT = "Courier"
@@ -66,8 +67,8 @@ def build_pdf_styles() -> PdfStyleSet:
         spaceBefore=0,
         spaceAfter=7,
         splitLongWords=True,
-        allowWidows=1,
-        allowOrphans=1,
+        allowWidows=0,
+        allowOrphans=0,
     )
     headings = tuple(
         ParagraphStyle(
@@ -147,6 +148,8 @@ def build_pdf_styles() -> PdfStyleSet:
         leading=11,
         spaceBefore=0,
         spaceAfter=0,
+        allowWidows=1,
+        allowOrphans=1,
     )
     table_header = ParagraphStyle(
         "DocVortex PDF Table Header",
@@ -192,6 +195,7 @@ __all__ = [
     "BODY_BOLD_FONT",
     "BODY_FONT",
     "BORDER_COLOR",
+    "FRAME_PADDING",
     "HAN_FONT",
     "JAPANESE_FONT",
     "KOREAN_FONT",

{docvortex-0.4.0 → docvortex-0.4.1}/src/docvortex/render/_internal/pdf/table.py

@@ -30,6 +30,25 @@ class PdfTableError(HtmlTableError):
     """表示 HTML 表格结构或 PDF 表格几何无法安全物化。"""
 
 
+class _PdfLongTable(LongTable):
+    """优先按整行分页，仅在新页也放不下时拆分超高行。"""
+
+    def split(self, availWidth: float, availHeight: float) -> list[Flowable]:
+        """先禁用行内拆分尝试分页，页首失败后再启用原有兜底能力。"""
+        split_in_row = self.splitInRow
+        self.splitInRow = 0
+        try:
+            parts = super().split(availWidth, availHeight)
+        finally:
+            self.splitInRow = split_in_row
+        for part in parts:
+            part.splitInRow = split_in_row
+        frame = getattr(self, "_frame", None)
+        if not parts and (frame is None or frame._atTop):
+            parts = super().split(availWidth, availHeight)
+        return parts
+
+
 class ParagraphBuilder(Protocol):
     """定义表格单元格创建富文本 Paragraph 的回调。"""
 
@@ -127,7 +146,7 @@ def _build_pdf_table(
     repeat_rows = 0
     while repeat_rows in grid.header_rows:
         repeat_rows += 1
-    table_class = LongTable if depth == 1 else Table
+    table_class = _PdfLongTable if depth == 1 else Table
     table = table_class(
         data,
         colWidths=column_widths,

{docvortex-0.4.0 → docvortex-0.4.1}/src/docvortex/version.py

@@ -1,3 +1,3 @@
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 __all__ = ["__version__"]

{docvortex-0.4.0 → docvortex-0.4.1/src/docvortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.0
+Version: 0.4.1
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex
@@ -177,7 +177,11 @@ DocVortex markers and semantic round trips.
 ## Scope and development
 
 PDF output is a semantic reflow of the document, not a lossless reproduction of
-the original page drawing instructions. Input support for PPTX/XLSX does not imply
+the original page drawing instructions. Short paragraphs (up to a quarter of the
+content area height) and short tables including annotations (up to half) stay
+together when possible. Longer content can paginate; tables repeat existing
+headers, and images scale to fit while keeping short captions on the same page.
+Input support for PPTX/XLSX does not imply
 PPTX/XLSX output support. Rust implementation work is a future stage behind these
 public data and processing boundaries.
 

{docvortex-0.4.0 → docvortex-0.4.1}/src/docvortex.egg-info/SOURCES.txt

@@ -400,6 +400,7 @@ src/docvortex/render/_internal/pdf/__init__.py
 src/docvortex/render/_internal/pdf/assets.py
 src/docvortex/render/_internal/pdf/formula.py
 src/docvortex/render/_internal/pdf/inline.py
+src/docvortex/render/_internal/pdf/pagination.py
 src/docvortex/render/_internal/pdf/renderer.py
 src/docvortex/render/_internal/pdf/styles.py
 src/docvortex/render/_internal/pdf/table.py
@@ -549,6 +550,7 @@ tests/unittest/test_office_parser_regressions.py
 tests/unittest/test_pdf_classify.py
 tests/unittest/test_pdf_demo_links.py
 tests/unittest/test_pdf_document.py
+tests/unittest/test_pdf_pagination.py
 tests/unittest/test_pdf_render.py
 tests/unittest/test_pdf_render_diagnostics.py
 tests/unittest/test_pdf_text_styles.py