sap-alv-parser 0.1.0__tar.gz

sap_alv_parser-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: sap-alv-parser
+Version: 0.1.0
+Summary: Parser for SAP ALV fixed-width `|`-delimited reports
+Keywords: sap,alv,parser,fixed-width,text-export
+Author: vccddd
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing
+Requires-Dist: numpy>=2.5.2
+Requires-Dist: pandas>=3.0.5
+Requires-Dist: prettytable>=3.18.0
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/vccddd/sap-alv-parser
+Description-Content-Type: text/markdown
+
+# sap-alv-parser
+
+Parser for SAP ALV fixed-width `|`-delimited reports. It turns "unconverted" /
+text-format SAP exports into one or more wide tables, merges pagination
+automatically, and hard-codes no column names, column counts, or column widths.
+
+## Features
+
+- **Zero configuration** — column boundaries, headers, and pagination are all
+  inferred automatically; no column names, widths, or counts need to be supplied.
+- **Multiple blocks** — a file's sort-criteria block, data-statistics block, and
+  main data table are each parsed into their own table.
+- **CJK friendly** — full-width characters (CJK) are normalized by display width
+  (2 columns), so CJK names do not shift column positions.
+- **`|` inside cells** — multi-value fields (e.g. shifts) that use `|` internally
+  are not confused with column separators.
+- **Multi-line cells** — cells containing newlines (e.g. multi-line remarks) are
+  reassembled correctly, whether the newline falls at the start, middle, or end
+  of the cell.
+- **DataFrame-style interface** — every block is a `Table` that can be converted
+  to a pandas DataFrame via `to_pandas()`.
+
+## Install
+
+```bash
+uv add sap-alv-parser       # as a dependency
+# or, for local development
+uv sync                 # installs dependencies (pandas / numpy / pytest)
+```
+
+Requirements: Python ≥ 3.13, `pandas`, `numpy`.
+
+## Quick start
+
+```python
+from sap_alv_parser import parse_blocks, parse_table
+
+# parse all blocks (each becomes a wide table)
+tables = parse_blocks("report.txt")
+for t in tables:
+    print(t.shape, t.columns)
+
+# get the main table (the one with the most rows)
+main = parse_table("report.txt")
+df = main.to_pandas()          # pandas.DataFrame
+```
+
+Command line:
+
+```bash
+uv run sap-alv-parse report.txt -o output.csv --all
+```
+
+## Recognized grammar
+
+These exports are a sequence of *blocks*, each following the same pattern:
+
+```
+report := stats_block? page+
+page   := sep_line header_line sep_line data_line+
+sep    := '-'+ | '|' '-'+ | '|' '-'+ '|'
+header := '|' label ('|' label)*
+data   := '|' field ('|' field)*      # fixed-width field, may itself contain '|'
+```
+
+## How it works
+
+1. **Single-block parsing** — normalize by display width → infer column boundaries
+   from `|` coverage → drop the phantom column created by a trailing edge `|`.
+2. **Multi-block recognition** — a header is the `|` line sandwiched between two
+   separator lines and immediately followed by a data line (content-independent);
+   blocks sharing the same header (pagination) are merged into one table.
+3. **Record reassembly** — records whose cells contain newlines span several
+   physical lines; a record is complete once a `|` appears at every column
+   boundary position.
+
+## `Table` interface
+
+| Capability | Usage | Description |
+|---|---|---|
+| Columns | `t.columns` | `list[str]` |
+| Shape | `t.shape` | `(rows, cols)` |
+| Length | `len(t)` | `int` |
+| Select column | `t['Amount']` | `list[str]` |
+| Select columns | `t[['A','B']]` | sub-`Table` |
+| Head | `t.head(3)` | first 3 rows |
+| Records | `t.to_dict()` | `list[dict]` |
+| Export | `t.to_csv('x.csv')` | CSV file |
+| DataFrame | `t.to_pandas()` | `pandas.DataFrame` |
+
+## Scope and limitations
+
+Supports SAP ALV grid "unconverted" / text exports in the `|`-delimited
+fixed-width format.
+
+**Not automatically covered** (requires separate adapters):
+
+- tab-delimited, HTML, or XLSX exports
+- fixed-width text with no `|` delimiters (space-aligned)
+
+## Testing
+
+> **Note:** the real SAP export files used as test fixtures have been removed
+> from this repository because they contained sensitive production data. All
+> tests now build synthetic fixtures inline and run without any external data.
+
+```bash
+uv run pytest
+```
+
+## Project structure
+
+```
+src/sap_alv_parser/
+├── __init__.py     # exports Table / parse_blocks / parse_table
+├── parser.py       # core parsing logic
+└── cli.py          # sap-alv-parse command line
+tests/
+└── test_parser.py  # tests (synthetic fixtures only)
+```

sap_alv_parser-0.1.0/README.md

@@ -0,0 +1,120 @@
+# sap-alv-parser
+
+Parser for SAP ALV fixed-width `|`-delimited reports. It turns "unconverted" /
+text-format SAP exports into one or more wide tables, merges pagination
+automatically, and hard-codes no column names, column counts, or column widths.
+
+## Features
+
+- **Zero configuration** — column boundaries, headers, and pagination are all
+  inferred automatically; no column names, widths, or counts need to be supplied.
+- **Multiple blocks** — a file's sort-criteria block, data-statistics block, and
+  main data table are each parsed into their own table.
+- **CJK friendly** — full-width characters (CJK) are normalized by display width
+  (2 columns), so CJK names do not shift column positions.
+- **`|` inside cells** — multi-value fields (e.g. shifts) that use `|` internally
+  are not confused with column separators.
+- **Multi-line cells** — cells containing newlines (e.g. multi-line remarks) are
+  reassembled correctly, whether the newline falls at the start, middle, or end
+  of the cell.
+- **DataFrame-style interface** — every block is a `Table` that can be converted
+  to a pandas DataFrame via `to_pandas()`.
+
+## Install
+
+```bash
+uv add sap-alv-parser       # as a dependency
+# or, for local development
+uv sync                 # installs dependencies (pandas / numpy / pytest)
+```
+
+Requirements: Python ≥ 3.13, `pandas`, `numpy`.
+
+## Quick start
+
+```python
+from sap_alv_parser import parse_blocks, parse_table
+
+# parse all blocks (each becomes a wide table)
+tables = parse_blocks("report.txt")
+for t in tables:
+    print(t.shape, t.columns)
+
+# get the main table (the one with the most rows)
+main = parse_table("report.txt")
+df = main.to_pandas()          # pandas.DataFrame
+```
+
+Command line:
+
+```bash
+uv run sap-alv-parse report.txt -o output.csv --all
+```
+
+## Recognized grammar
+
+These exports are a sequence of *blocks*, each following the same pattern:
+
+```
+report := stats_block? page+
+page   := sep_line header_line sep_line data_line+
+sep    := '-'+ | '|' '-'+ | '|' '-'+ '|'
+header := '|' label ('|' label)*
+data   := '|' field ('|' field)*      # fixed-width field, may itself contain '|'
+```
+
+## How it works
+
+1. **Single-block parsing** — normalize by display width → infer column boundaries
+   from `|` coverage → drop the phantom column created by a trailing edge `|`.
+2. **Multi-block recognition** — a header is the `|` line sandwiched between two
+   separator lines and immediately followed by a data line (content-independent);
+   blocks sharing the same header (pagination) are merged into one table.
+3. **Record reassembly** — records whose cells contain newlines span several
+   physical lines; a record is complete once a `|` appears at every column
+   boundary position.
+
+## `Table` interface
+
+| Capability | Usage | Description |
+|---|---|---|
+| Columns | `t.columns` | `list[str]` |
+| Shape | `t.shape` | `(rows, cols)` |
+| Length | `len(t)` | `int` |
+| Select column | `t['Amount']` | `list[str]` |
+| Select columns | `t[['A','B']]` | sub-`Table` |
+| Head | `t.head(3)` | first 3 rows |
+| Records | `t.to_dict()` | `list[dict]` |
+| Export | `t.to_csv('x.csv')` | CSV file |
+| DataFrame | `t.to_pandas()` | `pandas.DataFrame` |
+
+## Scope and limitations
+
+Supports SAP ALV grid "unconverted" / text exports in the `|`-delimited
+fixed-width format.
+
+**Not automatically covered** (requires separate adapters):
+
+- tab-delimited, HTML, or XLSX exports
+- fixed-width text with no `|` delimiters (space-aligned)
+
+## Testing
+
+> **Note:** the real SAP export files used as test fixtures have been removed
+> from this repository because they contained sensitive production data. All
+> tests now build synthetic fixtures inline and run without any external data.
+
+```bash
+uv run pytest
+```
+
+## Project structure
+
+```
+src/sap_alv_parser/
+├── __init__.py     # exports Table / parse_blocks / parse_table
+├── parser.py       # core parsing logic
+└── cli.py          # sap-alv-parse command line
+tests/
+└── test_parser.py  # tests (synthetic fixtures only)
+```

sap_alv_parser-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "sap-alv-parser"
+version = "0.1.0"
+description = "Parser for SAP ALV fixed-width `|`-delimited reports"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+keywords = [
+    "sap",
+    "alv",
+    "parser",
+    "fixed-width",
+    "text-export",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Text Processing",
+]
+dependencies = [
+    "numpy>=2.5.2",
+    "pandas>=3.0.5",
+    "prettytable>=3.18.0",
+]
+
+[[project.authors]]
+name = "vccddd"
+
+[project.urls]
+Repository = "https://github.com/vccddd/sap-alv-parser"
+
+[project.scripts]
+sap-alv-parse = "sap_alv_parser.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.27,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+]

sap_alv_parser-0.1.0/pyproject.toml.orig

@@ -0,0 +1,38 @@
+[project]
+name = "sap-alv-parser"
+version = "0.1.0"
+description = "Parser for SAP ALV fixed-width `|`-delimited reports"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [
+    { name = "vccddd" },
+]
+keywords = ["sap", "alv", "parser", "fixed-width", "text-export"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Text Processing",
+]
+dependencies = [
+    "numpy>=2.5.2",
+    "pandas>=3.0.5",
+    "prettytable>=3.18.0",
+]
+
+[project.urls]
+Repository = "https://github.com/vccddd/sap-alv-parser"
+
+[project.scripts]
+sap-alv-parse = "sap_alv_parser.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.27,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+]

sap_alv_parser-0.1.0/src/sap_alv_parser/__init__.py

@@ -0,0 +1,5 @@
+"""Parser for SAP ALV fixed-width `|`-delimited reports."""
+
+from .parser import DEFAULT_THRESHOLD, Table, parse_blocks, parse_table
+
+__all__ = ["Table", "parse_blocks", "parse_table", "DEFAULT_THRESHOLD"]

sap_alv_parser-0.1.0/src/sap_alv_parser/cli.py

@@ -0,0 +1,43 @@
+"""CLI entry point: parse a SAP export file into multiple wide tables."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+from .parser import DEFAULT_THRESHOLD, parse_blocks
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description="Parse SAP ALV fixed-width `|` reports into multiple blocks"
+    )
+    ap.add_argument("input", help="input file path")
+    ap.add_argument("-o", "--output", default="table.csv", help="CSV path for the largest table")
+    ap.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD,
+                    help="coverage threshold for column boundary inference (default %(default)s)")
+    ap.add_argument("--all", action="store_true", help="write each block to a separate CSV")
+    args = ap.parse_args()
+
+    tables = parse_blocks(args.input, threshold=args.threshold)
+    if not tables:
+        raise SystemExit("no data blocks parsed.")
+
+    print(f"Found {len(tables)} block group(s):")
+    for i, t in enumerate(tables):
+        print(f"  [{i}] {t.shape[0]} rows x {t.shape[1]} cols  columns: {t.columns}")
+
+    main = max(tables, key=len)
+    main.to_csv(args.output)
+    print(f"\nLargest table -> {args.output}: {main.shape[0]} rows x {main.shape[1]} cols")
+
+    if args.all:
+        stem, ext = os.path.splitext(args.output)
+        for i, t in enumerate(tables):
+            p = f"{stem}.block{i}{ext}"
+            t.to_csv(p)
+            print(f"  block {i} -> {p}")
+
+
+if __name__ == "__main__":
+    main()

sap_alv_parser-0.1.0/src/sap_alv_parser/parser.py

@@ -0,0 +1,325 @@
+"""Parser for SAP ALV fixed-width `|`-delimited reports, yielding multiple wide tables.
+
+The export is a sequence of *blocks*, each following the same pattern::
+
+    block := sep_line  header_line  sep_line  data_line+
+
+    sep_line := '-'+ | '|' '-'+ | '|' '-'+ '|'
+    header   := '|' label ('|' label)*
+    data     := '|' field ('|' field)*        # fixed-width field, may itself contain '|'
+
+A file may contain several blocks (sort criteria, data statistics, and the
+paginated main table). Each block is parsed independently; blocks sharing the
+same header (pagination) are merged into a single table.
+
+Cells may contain newlines (e.g. multi-line remarks): a record then spans several
+physical lines, and a continuation line may or may not start with `|`. Record
+boundaries are therefore detected by *column-boundary completeness* — a record is
+complete once a `|` appears at every boundary position — rather than by whether a
+line starts with `|`. Control characters (newlines etc.) count as zero-width.
+
+Column alignment is auto-detected per block: some exports align by *display width*
+(full-width CJK counts as 2 columns), others by *code points* (CJK counts as 1).
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+DEFAULT_THRESHOLD: float = 0.95  # coverage threshold for boundary inference
+
+
+class Table:
+    """A lightweight wide table: column names + rows; exports to CSV or pandas.
+
+    DataFrame-like interface: ``t.columns`` / ``t.shape`` / ``len(t)`` / ``t['col']`` /
+    ``t[['a','b']]`` / ``t.head()`` / ``t.to_dict()`` / ``t.to_csv()`` / ``t.to_pandas()``.
+    """
+
+    def __init__(
+        self,
+        columns: Sequence[str],
+        rows: Sequence[Sequence[str]],
+        meta: dict[str, object] | None = None,
+    ) -> None:
+        self.columns: list[str] = list(columns)
+        self.rows: list[list[str]] = [list(r) for r in rows]
+        self.meta: dict[str, object] = meta or {}
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def __repr__(self) -> str:
+        return f"Table(shape={self.shape}, columns={self.columns})"
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return (len(self.rows), len(self.columns))
+
+    def head(self, n: int = 5) -> Table:
+        return Table(self.columns, self.rows[:n], self.meta)
+
+    @overload
+    def __getitem__(self, key: str) -> list[str]: ...
+
+    @overload
+    def __getitem__(self, key: list[str] | tuple[str, ...]) -> Table: ...
+
+    def __getitem__(self, key: str | list[str] | tuple[str, ...]) -> list[str] | Table:
+        """Select by column name: ``t['col']`` -> values, ``t[['a','b']]`` -> sub-table."""
+        if isinstance(key, str):
+            return [r[self.columns.index(key)] for r in self.rows]
+        if isinstance(key, (list, tuple)):
+            idx = [self.columns.index(k) for k in key]
+            return Table(
+                [self.columns[i] for i in idx],
+                [[r[i] for i in idx] for r in self.rows],
+                self.meta,
+            )
+        raise TypeError("key must be a column name or a list of column names")
+
+    def to_dict(self) -> list[dict[str, str]]:
+        """Return rows as ``list[dict]`` (records orientation)."""
+        return [dict(zip(self.columns, r)) for r in self.rows]
+
+    def to_csv(self, path: str | Path) -> str:
+        import csv
+
+        with open(path, "w", newline="", encoding="utf-8-sig") as f:
+            w = csv.writer(f)
+            w.writerow(self.columns)
+            w.writerows(self.rows)
+        return str(path)
+
+    def to_pandas(self) -> pd.DataFrame:
+        """Convert to a pandas DataFrame."""
+        import pandas as pd
+
+        return pd.DataFrame(self.rows, columns=self.columns)
+
+    def to_prettytable(self, replace_pipe: str | None = None, **kwargs):
+        """Convert to a prettytable.PrettyTable.
+
+        ``replace_pipe``, when given, substitutes cell-internal ``|`` (used to
+        separate multi-segment values) so it does not visually collide with the
+        table's own column separators. Extra ``**kwargs`` go to ``PrettyTable``.
+        """
+        import prettytable
+
+        pt = prettytable.PrettyTable(field_names=self.columns, **kwargs)
+        for row in self.rows:
+            if replace_pipe is not None:
+                row = [c.replace("|", replace_pipe) for c in row]
+            pt.add_row(row)
+        return pt
+
+
+
+def _char_width(c: str, mode: str = "display") -> int:
+    if ord(c) < 32:  # control characters (\n \r \t) are zero-width
+        return 0
+    if mode == "display" and unicodedata.east_asian_width(c) in ("F", "W"):
+        return 2
+    return 1
+
+
+def display_width(s: str) -> int:
+    return sum(_char_width(c) for c in s)
+
+
+def is_separator(line: str) -> bool:
+    """A separator line consists only of '-'/'|' and contains at least one '-'."""
+    s = line.strip()
+    return bool(s) and ("-" in s) and all(c in "-|" for c in s)
+
+
+def header_labels(header_line: str) -> list[str]:
+    return [t.strip() for t in header_line.split("|") if t.strip()]
+
+
+def _pipe_positions(line: str, mode: str = "display") -> list[int]:
+    """Positions of every '|' in a line, in the given width mode (ascending)."""
+    positions: list[int] = []
+    disp = 0
+    for ch in line:
+        if ch == "|":
+            positions.append(disp)
+        disp += _char_width(ch, mode)
+    return positions
+
+
+
+def _display_to_code(
+    line: str, positions: Sequence[int], mode: str = "display"
+) -> dict[int, int]:
+    """Map boundary positions to the nearest '|' code index (±1 tolerance)."""
+    mapping: dict[int, int] = {}
+    pipes: list[tuple[int, int]] = []  # (position, code index)
+    disp = 0
+    for j, ch in enumerate(line):
+        if ch == "|":
+            pipes.append((disp, j))
+        disp += _char_width(ch, mode)
+    for b in positions:
+        best = min(pipes, key=lambda pj: abs(pj[0] - b), default=None)
+        if best is not None and abs(best[0] - b) <= 1:
+            mapping[b] = best[1]
+    return mapping
+
+
+def split_row(line: str, boundaries: Sequence[int], mode: str = "display") -> list[str]:
+    """Split one line into cells by boundary positions (stripped)."""
+    code = _display_to_code(line, boundaries, mode)
+    cols: list[str] = []
+    for k in range(len(boundaries) - 1):
+        cols.append(line[code[boundaries[k]] + 1 : code[boundaries[k + 1]]].strip())
+    cols.append(line[code[boundaries[-1]] + 1 :].strip())
+    return cols
+
+
+def _reassemble(
+    data_lines: Sequence[str], boundaries: Sequence[int], mode: str = "display"
+) -> list[str]:
+    """Reassemble physical lines into complete records.
+
+    A record is complete once a `|` appears near every boundary position.
+    A multi-line cell makes a record span several physical lines, and the
+    continuation line may or may not start with `|`, so we cannot rely on "line
+    starts with `|`" — we rely on boundary completeness instead.
+    """
+    boundaries_sorted = sorted(set(boundaries))
+    records: list[str] = []
+    current: str | None = None
+    for line in data_lines:
+        current = line if current is None else current + "\n" + line
+        positions = set(_pipe_positions(current, mode))
+        # every boundary position must have a `|` nearby (±1), tolerating padding drift
+        if all(any(abs(b - p) <= 1 for p in positions) for b in boundaries_sorted):
+            records.append(current)
+            current = None
+    if current is not None:  # trailing incomplete record (kept as-is)
+        records.append(current)
+    return records
+
+
+def _detect_mode(header_line: str, data_lines: Sequence[str]) -> str:
+    """Detect the alignment convention by comparing header vs a data record start.
+
+    Some exports align columns by display width (CJK counts as 2), others by code
+    points (CJK counts as 1). The header and data agree in the correct convention,
+    so compare their leading `|` positions in each convention and keep the one
+    with more matches. Uses the header (single-line, clean) so it works even when
+    every row is a multi-line cell.
+    """
+    starts = [l for l in data_lines if l.startswith("|")]
+    if not starts:
+        return "display"
+    ref = starts[0]
+    best_mode, best_score = "display", -1
+    for mode in ("code", "display"):
+        hp = _pipe_positions(header_line, mode)
+        dp = _pipe_positions(ref, mode)
+        m = min(len(hp), len(dp))
+        score = sum(1 for k in range(m) if hp[k] == dp[k])
+        if score > best_score:
+            best_mode, best_score = mode, score
+    return best_mode
+
+
+def _parse_single_block(
+    header_line: str, data_lines: Sequence[str], threshold: float
+) -> Table | None:
+    """Parse a single block (header + its data lines) into a Table."""
+    if not data_lines:
+        return None
+
+    mode = _detect_mode(header_line, data_lines)
+    boundaries = _pipe_positions(header_line, mode)
+    if not boundaries:
+        return None
+
+    records = _reassemble(data_lines, boundaries, mode)
+    rows = [split_row(r, boundaries, mode) for r in records]
+
+    # trailing edge `|` creates a phantom column: drop it if empty in every row
+    if rows and all(r[-1] == "" for r in rows):
+        boundaries = boundaries[:-1]
+        rows = [r[:-1] for r in rows]
+
+    ncols = len(boundaries)
+    labels = header_labels(header_line)
+    if len(labels) != ncols:
+        labels = [f"col_{i}" for i in range(ncols)]
+    return Table(labels, rows)
+
+
+def split_into_blocks(
+    lines: Sequence[str], sep: Sequence[bool]
+) -> list[tuple[str, list[str]]]:
+    """Split a file into blocks, each ``(header_line, data_lines)``."""
+    n = len(lines)
+
+    # A header is a `|` line sandwiched between two separators whose closing
+    # separator is immediately followed by a data line. The last condition
+    # distinguishes the header from the lone data row of a single-row block.
+    header_idx: list[int] = []
+    for i in range(1, n - 2):
+        l = lines[i]
+        if (
+            l.startswith("|")
+            and not sep[i]
+            and sep[i - 1]
+            and sep[i + 1]
+            and lines[i + 2].startswith("|")
+            and not sep[i + 2]
+        ):
+            header_idx.append(i)
+
+    header_set = set(header_idx)
+    blocks: list[tuple[str, list[str]]] = []
+    for k, hi in enumerate(header_idx):
+        end = header_idx[k + 1] if k + 1 < len(header_idx) else n
+        # collect all non-separator, non-blank lines (including multi-line continuations)
+        data = [
+            lines[j]
+            for j in range(hi + 1, end)
+            if not sep[j] and lines[j].strip() and j not in header_set
+        ]
+        blocks.append((lines[hi], data))
+    return blocks
+
+
+def parse_blocks(path: str | Path, threshold: float = DEFAULT_THRESHOLD) -> list[Table]:
+    """Parse all blocks in a file, returning one Table per distinct header (pages merged)."""
+    with open(path, "rb") as f:
+        raw = f.read().decode("utf-8")
+    lines = raw.split("\r\n") if "\r\n" in raw else raw.split("\n")
+    sep = [is_separator(l) for l in lines]
+
+    blocks = split_into_blocks(lines, sep)
+
+    grouped: dict[tuple[str, ...], Table] = {}  # column-name signature -> Table
+    for header_line, data_lines in blocks:
+        t = _parse_single_block(header_line, data_lines, threshold)
+        if t is None:
+            continue
+        key = tuple(t.columns)
+        if key in grouped:
+            grouped[key].rows.extend(t.rows)
+        else:
+            grouped[key] = t
+    return list(grouped.values())
+
+
+def parse_table(path: str | Path, threshold: float = DEFAULT_THRESHOLD) -> Table:
+    """Return the table with the most rows (usually the main data table)."""
+    tables = parse_blocks(path, threshold)
+    if not tables:
+        raise ValueError(f"no data blocks parsed from {path}")
+    return max(tables, key=len)