table-stitcher 0.3.0__py3-none-any.whl

table_stitcher/__init__.py

@@ -0,0 +1,340 @@
+"""
+Table Stitcher — Reassemble tables split across page boundaries.
+
+A parser-agnostic library that detects and merges table fragments produced
+by PDF extraction tools. Ships with a Docling adapter out of the box.
+
+Usage (Docling):
+    from table_stitcher import stitch_tables, MultiPageConfig
+
+    doc = stitch_tables(doc)  # Use defaults
+    doc = stitch_tables(doc, config=MultiPageConfig(max_page_gap=2))
+
+Usage (custom parser):
+    from table_stitcher import TableStitcher
+    from table_stitcher.adapters.base import TableStitcherAdapter
+
+    class MyAdapter:
+        def extract(self, doc, cfg): ...
+        def inject(self, doc, logical_tables): ...
+
+    stitcher = TableStitcher(adapter=MyAdapter())
+    doc = stitcher.stitch(doc)
+"""
+
+import logging
+import time
+from typing import Any, Optional
+
+from .adapters.base import TableStitcherAdapter
+from .merger import merge_multipage_tables
+from .models import LogicalTable, MergeTrace, MultiPageConfig, TableMeta
+
+__version__ = "0.2.0"
+__all__ = [
+    "stitch_tables",
+    "extract_table_meta",
+    "merge_multipage_tables",
+    "TableStitcher",
+    "MultiPageConfig",
+    "LogicalTable",
+    "TableMeta",
+    "MergeTrace",
+    "StitchingError",
+    "TableStitcherAdapter",
+    "__version__",
+]
+
+
+class StitchingError(Exception):
+    """Raised when table stitching fails."""
+
+    pass
+
+
+class TableStitcher:
+    """
+    Detects and merges tables split across multiple pages.
+
+    This class is parser-agnostic. Pass any adapter that implements the
+    ``TableStitcherAdapter`` protocol (two methods: ``extract`` and ``inject``).
+
+    For simple Docling usage, use the ``stitch_tables()`` function instead.
+    """
+
+    def __init__(
+        self,
+        adapter: TableStitcherAdapter,
+        config: Optional[MultiPageConfig] = None,
+    ):
+        self.logger = logging.getLogger("table_stitcher")
+        self.adapter = adapter
+        self.config = config or MultiPageConfig()
+        self._validate_config()
+
+    # -------------------------------------------------------------------------
+    # Logging
+    # -------------------------------------------------------------------------
+
+    def _log_phase_start(self, phase_num: int, phase_name: str):
+        self.logger.info("=" * 70)
+        self.logger.info(f"Phase {phase_num}: {phase_name}")
+        self.logger.info("=" * 70)
+
+    def _log_phase_complete(
+        self, phase_num: int, count: int, duration: float, item_type: str = "items"
+    ):
+        self.logger.info(f"Phase {phase_num} complete: {count} {item_type} [{duration:.1f}s]")
+
+    def _log_section(self, message: str, indent: int = 2):
+        prefix = " " * indent
+        self.logger.info(f"{prefix}{message}")
+
+    def _log_item_progress(self, item_name: str, status: str = "success"):
+        symbol = "+" if status == "success" else "x"
+        self.logger.info(f"  [{symbol}] {item_name}")
+
+    def _log_error(self, context: str, error: Exception):
+        self.logger.error(f"  [x] {context}: {error}")
+
+    # -------------------------------------------------------------------------
+    # Validation
+    # -------------------------------------------------------------------------
+
+    def _validate_config(self) -> None:
+        """Validate configuration values."""
+        errors = []
+        cfg = self.config
+
+        if not (1 <= cfg.max_page_gap <= 10):
+            errors.append(f"max_page_gap must be 1-10, got {cfg.max_page_gap}")
+
+        if cfg.max_width_difference < 0:
+            errors.append(f"max_width_difference must be >= 0, got {cfg.max_width_difference}")
+
+        valid_width_policies = {"preserve_extra", "warn_drop", "fail", "merge_tail"}
+        if cfg.width_overflow_policy not in valid_width_policies:
+            errors.append(
+                "width_overflow_policy must be one of "
+                f"{sorted(valid_width_policies)}, got {cfg.width_overflow_policy!r}"
+            )
+
+        for name, value in [
+            ("header_sim_strict", cfg.header_sim_strict),
+            ("header_sim_loose", cfg.header_sim_loose),
+            ("row_sim_threshold", cfg.row_sim_threshold),
+            ("bottom_band_min", cfg.bottom_band_min),
+            ("top_band_max", cfg.top_band_max),
+        ]:
+            if not (0.0 <= value <= 1.0):
+                errors.append(f"{name} must be 0.0-1.0, got {value}")
+
+        if cfg.max_orphan_rows < 0:
+            errors.append(f"max_orphan_rows must be >= 0, got {cfg.max_orphan_rows}")
+        if cfg.max_data_orphan_rows < 0:
+            errors.append(f"max_data_orphan_rows must be >= 0, got {cfg.max_data_orphan_rows}")
+
+        if errors:
+            raise ValueError("Invalid MultiPageConfig:\n  " + "\n  ".join(errors))
+
+    # -------------------------------------------------------------------------
+    # Core Processing
+    # -------------------------------------------------------------------------
+
+    def stitch(
+        self,
+        doc: Any,
+        raise_on_error: bool = False,
+    ) -> Any:
+        """
+        Detect and merge tables split across multiple pages.
+
+        Args:
+            doc: The parser-native document object.
+            raise_on_error: If True, raise exceptions on processing errors.
+                            If False (default), log errors and return original doc.
+
+        Returns:
+            The document with merged tables.
+        """
+        if doc is None:
+            if raise_on_error:
+                raise StitchingError("Input document is None")
+            self.logger.error("Input document is None")
+            return doc
+
+        # --- Phase 1: Extract Metadata ---
+        self._log_phase_start(1, "Extract Table Metadata")
+        phase_start = time.time()
+
+        try:
+            tables_meta = self.adapter.extract(doc, self.config)
+        except Exception as e:
+            self._log_error("Metadata extraction failed", e)
+            if raise_on_error:
+                raise StitchingError(f"Failed to extract table metadata: {e}") from e
+            return doc
+
+        if not tables_meta:
+            self._log_section("No tables found in document")
+            self._log_phase_complete(1, 0, time.time() - phase_start, "tables")
+            return doc
+
+        # Report extraction coverage — tables that failed extraction
+        # are silently preserved in the original doc (pass-through).
+        total_tables = len(getattr(doc, "tables", []) or [])
+        if total_tables and len(tables_meta) < total_tables:
+            skipped = total_tables - len(tables_meta)
+            self._log_section(
+                f"Extracted {len(tables_meta)}/{total_tables} tables "
+                f"({skipped} skipped — originals preserved)"
+            )
+
+        self._log_phase_complete(
+            1, len(tables_meta), time.time() - phase_start, "table fragments extracted"
+        )
+
+        # --- Phase 2: Analyze & Merge ---
+        self._log_phase_start(2, "Analyze Multi-Page Merges")
+        phase_start = time.time()
+
+        try:
+            logical_tables = merge_multipage_tables(tables_meta, self.config)
+        except Exception as e:
+            self._log_error("Merge analysis failed", e)
+            if raise_on_error:
+                raise StitchingError(f"Failed to merge tables: {e}") from e
+            return doc
+
+        multi_page_tables = [lt for lt in logical_tables if len(lt.pages) > 1]
+
+        if not multi_page_tables:
+            self._log_section("No multi-page tables detected")
+            self._log_phase_complete(2, 0, time.time() - phase_start, "merges")
+            return doc
+
+        for lt in multi_page_tables:
+            reason = f", reason={lt.merge_reason}" if lt.merge_reason else ""
+            self._log_section(
+                f"Found: Table spanning pages {lt.pages} ({len(lt.members)} fragments{reason})"
+            )
+
+        self._log_phase_complete(
+            2, len(multi_page_tables), time.time() - phase_start, "multi-page tables identified"
+        )
+
+        # --- Phase 3: Inject Merged Tables ---
+        self._log_phase_start(3, "Inject Merged Tables")
+        phase_start = time.time()
+
+        try:
+            doc = self.adapter.inject(doc, logical_tables)
+        except Exception as e:
+            self._log_error("Injection failed", e)
+            if raise_on_error:
+                raise StitchingError(f"Failed to inject merged tables: {e}") from e
+            return doc
+
+        for lt in multi_page_tables:
+            self._log_item_progress(f"Merged pages {lt.pages} -> 1 table", "success")
+
+        self._log_phase_complete(
+            3, len(multi_page_tables), time.time() - phase_start, "tables injected"
+        )
+
+        return doc
+
+
+# -----------------------------------------------------------------------------
+# Convenience Function
+# -----------------------------------------------------------------------------
+
+
+def stitch_tables(
+    doc: Any,
+    config: Optional[MultiPageConfig] = None,
+    raise_on_error: bool = False,
+) -> Any:
+    """
+    Detect and merge tables split across multiple pages.
+
+    Convenience function that uses the Docling adapter by default.
+    For other parsers, use ``TableStitcher`` with a custom adapter.
+
+    Args:
+        doc: The input DoclingDocument (already converted from PDF).
+        config: Optional configuration overrides. Uses sensible defaults if None.
+        raise_on_error: If True, raise exceptions on processing errors.
+                        If False (default), log errors and return original doc.
+
+    Returns:
+        The document with merged tables.
+
+    Raises:
+        StitchingError: If raise_on_error=True and processing fails.
+        ValueError: If config values are invalid.
+
+    Example:
+        >>> from docling.document_converter import DocumentConverter
+        >>> from table_stitcher import stitch_tables
+        >>>
+        >>> converter = DocumentConverter()
+        >>> doc = converter.convert("report.pdf").document
+        >>> doc = stitch_tables(doc)
+    """
+    try:
+        from .adapters.docling import DoclingAdapter
+    except ModuleNotFoundError as e:
+        if "docling_core" in str(e):
+            raise ImportError(
+                "The Docling adapter requires docling-core. "
+                "Install it with: pip install table-stitcher[docling]"
+            ) from e
+        raise  # genuine bug inside docling.py — don't mask it
+
+    try:
+        stitcher = TableStitcher(adapter=DoclingAdapter(), config=config)
+        return stitcher.stitch(doc, raise_on_error=raise_on_error)
+    except ValueError:
+        if raise_on_error:
+            raise
+        logging.getLogger("table_stitcher").error(
+            "Invalid configuration, returning original document"
+        )
+        return doc
+
+
+def extract_table_meta(
+    doc: Any,
+    config: Optional[MultiPageConfig] = None,
+) -> list:
+    """
+    Extract table metadata without merging — useful for analysis.
+
+    Convenience function that uses the Docling adapter by default.
+    Returns a list of ``TableMeta`` objects describing each table fragment.
+
+    Args:
+        doc: The input DoclingDocument (already converted from PDF).
+        config: Optional configuration overrides. Uses sensible defaults if None.
+
+    Returns:
+        List of TableMeta objects for each table in the document.
+
+    Example:
+        >>> from table_stitcher import extract_table_meta
+        >>> metas = extract_table_meta(doc)
+        >>> for m in metas:
+        ...     print(f"Table {m.idx}: {m.width} cols, page {m.start_page}")
+    """
+    try:
+        from .adapters.docling import DoclingAdapter
+    except ModuleNotFoundError as e:
+        if "docling_core" in str(e):
+            raise ImportError(
+                "The Docling adapter requires docling-core. "
+                "Install it with: pip install table-stitcher[docling]"
+            ) from e
+        raise
+
+    return DoclingAdapter().extract(doc, config or MultiPageConfig())

table_stitcher/adapters/README.md

@@ -0,0 +1,173 @@
+# Adapters
+
+`table-stitcher`'s core is parser-agnostic. Adapters bridge a specific
+document parser (docling, pdfplumber, unstructured, …) to the
+`TableMeta` / `LogicalTable` contract the merger operates on.
+
+Adapter-specific notes — version compatibility, OCR backend behavior,
+known upstream workarounds — live here rather than in the main README,
+so the top-level docs stay agnostic and each adapter can document its
+own quirks.
+
+## Adapter protocol
+
+Any adapter implements two methods:
+
+```python
+class MyAdapter:
+    def extract(self, doc, cfg: MultiPageConfig) -> list[TableMeta]:
+        """Read tables from the parser's native document type and produce
+        TableMeta records for each fragment."""
+
+    def inject(self, doc, logical_tables: list[LogicalTable]):
+        """Write merged tables back into the native document, pruning the
+        now-redundant satellite fragments from the body tree and clearing
+        their cell content. Return the modified document."""
+```
+
+A skeleton custom adapter appears in the top-level README. The merger
+never imports parser-specific types — it only reads from the `TableMeta`
+fields and writes to a pandas DataFrame, which the adapter then converts
+back into the parser's native table representation during `inject`.
+Each `LogicalTable` also carries `merge_reason`, `merge_traces`, and
+`warnings`; adapters can ignore them, log them, or surface them in their
+native document metadata.
+
+---
+
+## Docling adapter (`docling.py`)
+
+### How the docling adapter prunes satellites
+
+When `inject()` folds multiple fragments into one logical table, the
+satellite fragments (members after the anchor) are handled in two places:
+
+1. **Body tree** — references to satellite tables in `doc.body` (and any
+   groups) are removed, so rendered output contains only the merged
+   anchor.
+2. **`doc.tables` list** — the `Table` objects at the satellite indices
+   are *cleared in place*: `data` becomes an empty `TableData`
+   (`num_rows=0, num_cols=0`), `prov` becomes `[]`. The `Table`
+   wrapper stays at its list position because docling uses
+   position-based `self_ref` strings (`#/tables/N`) — removing entries
+   would invalidate every reference that points to a later index.
+
+**If your downstream code iterates `doc.tables` directly** (instead of
+traversing the body tree), skip empty-shell tables explicitly:
+
+```python
+for t in doc.tables:
+    if t.data and t.data.num_rows > 0:
+        ...  # real content
+```
+
+For most users the body tree is the right thing to iterate — it already
+reflects the merged view.
+
+### Version compatibility
+
+Tested against **docling 2.64, docling-core 2.54**. The project pins a
+compatible range in `pyproject.toml`:
+
+```
+docling>=2.60,<3
+docling-core>=2.50,<3
+```
+
+If you need to test against a dev docling build:
+
+```bash
+pip install -e <path/to/docling-checkout>
+pytest tests/integration/
+```
+
+Breaking changes in a 3.x release will need adapter updates — the adapter
+touches `DoclingDocument`, `TableData`, `TableCell`, and table `prov`
+entries (for page-number and bounding-box info).
+
+### OCR backend
+
+Docling auto-selects an OCR engine at runtime based on the host
+(`ocrmac` on Apple Silicon, `easyocr` / `tesserocr` / `rapidocr`
+otherwise). Cell text on image-backed PDFs (e.g. our bundled
+PubTables-v2 fixtures) differs very slightly across backends.
+
+The `first_row` / `last_row` assertions in integration fixtures have
+been stable in practice but may flap if the CI host's OCR backend
+differs from the one used to author the YAML. Re-running
+`tests/integration/_tools/regenerate_expected.py` produces a clean
+baseline for the new backend.
+
+### Adapter detection thresholds
+
+A few structural constants live at the top of `docling.py` rather than
+in `MultiPageConfig`:
+
+```python
+_MAX_HEADER_CELL_LEN = 30    # header cells typically short; data cells longer
+_DATA_PATTERNS            # regex list for "this cell is data, not header"
+_AUTO_COLNAME_RE          # "Column_N" / "Unnamed: N" parser placeholders
+```
+
+These are **adapter-intrinsic** — tuning them changes how the adapter
+classifies first rows as header-or-data. User-tunable thresholds
+(page gap, width tolerance, Jaccard cutoffs) live in `MultiPageConfig`
+instead.
+
+### Known upstream workarounds
+
+The adapter compensates for a handful of docling extraction patterns
+that produce fragments the merger would otherwise mis-group:
+
+- **Data-as-headers** — when docling extracts a page where the real
+  header row got collapsed into the first data row, the fragment's
+  "column names" look like `['Column_0', 'Am Fds Trgt Dte Rtm 2055',
+  '13,085.03']`. The adapter's `_looks_like_data` regex list catches
+  comma-grouped decimals, stat ranges (`280 (176, 404)`), and scientific
+  notation (`7.0 x 10-7`) as data patterns, and flags the fragment
+  `is_headerless=True` so the merger's width-match path handles it.
+  An upstream fix that correctly identifies the collapsed header row
+  would make this heuristic unnecessary.
+
+- **Long-cell first rows** — fragments where the majority of first-row
+  cells are >30 chars are flagged headerless too. Real headers are
+  typically short; a row of sentence-long strings is almost certainly
+  data.
+
+- **Orphan-header fragments with truncated width** — when a new table's
+  header row has empty trailing cells that the parser drops, the
+  fragment's width is less than its data continuation's. The adapter
+  flags these as `is_header_orphan` structurally (small + header-shaped
+  cells, no data patterns), and the merger's "header-orphan → headerless
+  data" path trusts the data fragment's width on the join.
+
+These workarounds are structural, not vocabulary-based — they reason
+about cell shapes (length, regex patterns, auto-label form) rather than
+specific words, so they generalize across domains and languages.
+
+### Layout data availability
+
+The merger's layout-confirmation rules (`bottom_band_min`, `top_band_max`,
+width-drift tolerance) rely on `vert_top` / `vert_bottom` from the
+adapter. Docling provides these via `prov[*].bbox` on `DoclingDocument`
+tables. If a document lacks layout info (e.g. a text-only extraction),
+the merger falls back to structural signals only and the layout-gated
+rules don't fire.
+
+---
+
+## Adding a new adapter
+
+1. Create `src/table_stitcher/adapters/<parser>.py`.
+2. Implement the two methods above. Read a fragment's pandas DataFrame
+   plus its `prov` / layout metadata into `TableMeta`; write a merged
+   DataFrame back into the parser's native table type during `inject`.
+3. Add a section to this README documenting version compat, any OCR or
+   extraction quirks, and workarounds.
+4. Add a unit test file `tests/test_<parser>_adapter.py` exercising
+   `_grid_to_dataframe`-equivalent and `_dataframe_to_*_data`-equivalent
+   conversion on stub inputs.
+5. (Optional but valuable) Re-run the integration fixtures through the
+   new adapter. Fixtures are parser-agnostic; anything your adapter can
+   convert to `TableMeta` with reasonable fidelity will exercise the
+   same merger rules as docling.

table_stitcher/adapters/__init__.py

@@ -0,0 +1,11 @@
+from .base import TableStitcherAdapter
+
+try:
+    from .docling import DoclingAdapter
+except ModuleNotFoundError as e:
+    if "docling_core" in str(e):
+        DoclingAdapter = None  # docling-core not installed; use core-only mode
+    else:
+        raise  # genuine missing dependency inside docling.py — don't swallow
+
+__all__ = ["TableStitcherAdapter", "DoclingAdapter"]

table_stitcher/adapters/base.py

@@ -0,0 +1,42 @@
+"""
+Adapter protocol for table-stitcher.
+
+Any PDF parser can integrate with table-stitcher by implementing these
+two methods. The merge engine only ever sees TableMeta objects — it never
+touches parser-native document structures.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+from ..models import LogicalTable, MultiPageConfig, TableMeta
+
+
+@runtime_checkable
+class TableStitcherAdapter(Protocol):
+    """
+    Minimal interface a parser must implement to plug into table-stitcher.
+
+    Implement ``extract`` to read table fragments from your document format,
+    and ``inject`` to write merged results back.
+    """
+
+    def extract(self, doc: Any, cfg: MultiPageConfig) -> list[TableMeta]:
+        """
+        Read all table fragments from the parser-native document object.
+
+        Returns a list of TableMeta, one per table fragment found in the doc.
+        The merger engine only ever sees these — it never touches ``doc``.
+        """
+        ...
+
+    def inject(self, doc: Any, logical_tables: list[LogicalTable]) -> Any:
+        """
+        Write merged results back into the parser-native document object.
+
+        Receives the original doc and the full list of LogicalTable objects
+        (including single-fragment tables that were not merged — the adapter
+        decides whether to skip or handle them).
+
+        Returns the (potentially modified) doc.
+        """
+        ...