exstruct 0.3.1__tar.gz → 0.3.2__tar.gz

{exstruct-0.3.1 → exstruct-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.3.1
+Version: 0.3.2
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -59,14 +59,14 @@ Description-Content-Type: text/markdown
 
 ![ExStruct Image](/docs/assets/icon.webp)
 
-ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, smartart, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
+ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, smartart, merged cell ranges, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
 
 [日本版 README](README.ja.md)
 
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, smartart, table candidates, print areas/views, and auto page-break areas per sheet.
-- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
 - **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested (CLI option appears only when COM is available).
 - **Formats**: JSON (compact by default, `--pretty` available), YAML, TOON (optional dependencies).
 - **Table detection tuning**: adjust heuristics at runtime via API.
@@ -188,8 +188,8 @@ Use higher thresholds to reduce false positives; lower them if true tables are m
 ## Output Modes
 
 - **light**: cells + table candidates (no COM needed).
-- **standard**: texted shapes + arrows, charts (COM if available), table candidates. Hyperlinks are off unless `include_cell_links=True`.
-- **verbose**: all shapes (with width/height), charts, table candidates, cell hyperlinks, and `colors_map`.
+- **standard**: texted shapes + arrows, charts (COM if available), merged cell ranges, table candidates. Hyperlinks are off unless `include_cell_links=True`.
+- **verbose**: all shapes (with width/height), charts, merged cell ranges, table candidates, cell hyperlinks, and `colors_map`.
 
 ## Error Handling / Fallbacks
 
@@ -207,7 +207,7 @@ exstruct input.xlsx --pdf --image --dpi 144
 
 Creates `<output>.pdf` and `<output>_images/` PNGs per sheet.
 
-## Benchmark: Excel Structuring Demo
+## Example 1: Excel Structuring Demo
 
 To show how well exstruct can structure Excel, we parse a workbook that combines three elements on one sheet and share an AI reasoning benchmark that uses the JSON output.
 
@@ -277,6 +277,7 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
           "text": "開始",
           "l": 148,
           "t": 220,
+          "kind": "shape",
           "type": "AutoShape-FlowchartProcess"
         },
         {
@@ -284,12 +285,13 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
           "text": "入力データ読み込み",
           "l": 132,
           "t": 282,
+          "kind": "shape",
           "type": "AutoShape-FlowchartProcess"
         },
         {
           "l": 193,
           "t": 246,
-          "type": "AutoShape-Mixed",
+          "kind": "arrow",
           "begin_arrow_style": 1,
           "end_arrow_style": 2,
           "begin_id": 1,
@@ -389,6 +391,87 @@ flowchart TD
 ```
 ````
 
+## Example 2: General Application Form
+
+### Excel Sheet
+
+![General Application Form Excel](/docs/assets/demo_form.en.png)
+
+### ExStruct JSON
+
+(Truncated for brevity)
+
+```json
+{
+  "book_name": "ja_form.xlsx",
+  "sheets": {
+    "Sheet1": {
+      "rows": [
+        { "r": 1, "c": { "0": "??????????????" } },
+        {
+          "r": 3,
+          "c": { "0": "???", "7": "  ???????????????" }
+        },
+        { "r": 4, "c": { "1": "X???" } },
+        ...
+      ],
+      "table_candidates": ["B25:C26", "C37:D50"],
+      "merged_cells": [
+        {
+          "r1": 55,
+          "c1": 5,
+          "r2": 55,
+          "c2": 10,
+          "v": "?????????????????????????????"
+        },
+        { "r1": 54, "c1": 8, "r2": 54, "c2": 10 },
+        { "r1": 51, "c1": 5, "r2": 52, "c2": 6, "v": "????" },
+        ...
+      ]
+    }
+  }
+}
+```
+
+### LLM reconstruction example
+
+```md
+# ??????????????
+
+????????????????????????  
+X ??
+
+?????????????????????????????????????????
+
+---
+
+## ??????
+
+| ??     | ??             |
+| ------ | -------------- |
+| ????   |                |
+| ?????  |                |
+| ?????? |                |
+| ????   |                |
+| ????   | ?????????????? |
+| ??     |                |
+| ???    |                |
+
+---
+
+## ?????????????
+
+| ??          | ??    |
+| ----------- | ----- |
+| ??????????? |       |
+| ???         |       |
+| ????????    | ????? |
+
+**???????????????????????????????????????**
+
+...
+```
+
 From this we can see:
 
 **exstruct's JSON is already in a format that AI can read and reason over directly.**
@@ -398,6 +481,7 @@ Other LLM inference samples using this library can be found in the following dir
 - [Basic Excel](sample/basic/)
 - [Flowchart](sample/flowchart/)
 - [Gantt Chart](sample/gantt_chart/)
+- [Application forms with many merged cells](sample/forms_with_many_merged_cells/)
 
 ### 4. Summary
 

{exstruct-0.3.1 → exstruct-0.3.2}/README.md

@@ -4,14 +4,14 @@
 
 ![ExStruct Image](/docs/assets/icon.webp)
 
-ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, smartart, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
+ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, smartart, merged cell ranges, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
 
 [日本版 README](README.ja.md)
 
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, smartart, table candidates, print areas/views, and auto page-break areas per sheet.
-- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
 - **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested (CLI option appears only when COM is available).
 - **Formats**: JSON (compact by default, `--pretty` available), YAML, TOON (optional dependencies).
 - **Table detection tuning**: adjust heuristics at runtime via API.
@@ -133,8 +133,8 @@ Use higher thresholds to reduce false positives; lower them if true tables are m
 ## Output Modes
 
 - **light**: cells + table candidates (no COM needed).
-- **standard**: texted shapes + arrows, charts (COM if available), table candidates. Hyperlinks are off unless `include_cell_links=True`.
-- **verbose**: all shapes (with width/height), charts, table candidates, cell hyperlinks, and `colors_map`.
+- **standard**: texted shapes + arrows, charts (COM if available), merged cell ranges, table candidates. Hyperlinks are off unless `include_cell_links=True`.
+- **verbose**: all shapes (with width/height), charts, merged cell ranges, table candidates, cell hyperlinks, and `colors_map`.
 
 ## Error Handling / Fallbacks
 
@@ -152,7 +152,7 @@ exstruct input.xlsx --pdf --image --dpi 144
 
 Creates `<output>.pdf` and `<output>_images/` PNGs per sheet.
 
-## Benchmark: Excel Structuring Demo
+## Example 1: Excel Structuring Demo
 
 To show how well exstruct can structure Excel, we parse a workbook that combines three elements on one sheet and share an AI reasoning benchmark that uses the JSON output.
 
@@ -222,6 +222,7 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
           "text": "開始",
           "l": 148,
           "t": 220,
+          "kind": "shape",
           "type": "AutoShape-FlowchartProcess"
         },
         {
@@ -229,12 +230,13 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
           "text": "入力データ読み込み",
           "l": 132,
           "t": 282,
+          "kind": "shape",
           "type": "AutoShape-FlowchartProcess"
         },
         {
           "l": 193,
           "t": 246,
-          "type": "AutoShape-Mixed",
+          "kind": "arrow",
           "begin_arrow_style": 1,
           "end_arrow_style": 2,
           "begin_id": 1,
@@ -334,6 +336,87 @@ flowchart TD
 ```
 ````
 
+## Example 2: General Application Form
+
+### Excel Sheet
+
+![General Application Form Excel](/docs/assets/demo_form.en.png)
+
+### ExStruct JSON
+
+(Truncated for brevity)
+
+```json
+{
+  "book_name": "ja_form.xlsx",
+  "sheets": {
+    "Sheet1": {
+      "rows": [
+        { "r": 1, "c": { "0": "??????????????" } },
+        {
+          "r": 3,
+          "c": { "0": "???", "7": "  ???????????????" }
+        },
+        { "r": 4, "c": { "1": "X???" } },
+        ...
+      ],
+      "table_candidates": ["B25:C26", "C37:D50"],
+      "merged_cells": [
+        {
+          "r1": 55,
+          "c1": 5,
+          "r2": 55,
+          "c2": 10,
+          "v": "?????????????????????????????"
+        },
+        { "r1": 54, "c1": 8, "r2": 54, "c2": 10 },
+        { "r1": 51, "c1": 5, "r2": 52, "c2": 6, "v": "????" },
+        ...
+      ]
+    }
+  }
+}
+```
+
+### LLM reconstruction example
+
+```md
+# ??????????????
+
+????????????????????????  
+X ??
+
+?????????????????????????????????????????
+
+---
+
+## ??????
+
+| ??     | ??             |
+| ------ | -------------- |
+| ????   |                |
+| ?????  |                |
+| ?????? |                |
+| ????   |                |
+| ????   | ?????????????? |
+| ??     |                |
+| ???    |                |
+
+---
+
+## ?????????????
+
+| ??          | ??    |
+| ----------- | ----- |
+| ??????????? |       |
+| ???         |       |
+| ????????    | ????? |
+
+**???????????????????????????????????????**
+
+...
+```
+
 From this we can see:
 
 **exstruct's JSON is already in a format that AI can read and reason over directly.**
@@ -343,6 +426,7 @@ Other LLM inference samples using this library can be found in the following dir
 - [Basic Excel](sample/basic/)
 - [Flowchart](sample/flowchart/)
 - [Gantt Chart](sample/gantt_chart/)
+- [Application forms with many merged cells](sample/forms_with_many_merged_cells/)
 
 ### 4. Summary
 

{exstruct-0.3.1 → exstruct-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.3.1"
+version = "0.3.2"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/backends/base.py

@@ -3,11 +3,12 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Protocol
 
-from ...models import CellRow, PrintArea
+from ...models import CellRow, MergedCell, PrintArea
 from ..cells import WorkbookColorsMap
 
 CellData = dict[str, list[CellRow]]
 PrintAreaData = dict[str, list[PrintArea]]
+MergedCellData = dict[str, list[MergedCell]]
 
 
 @dataclass(frozen=True)
@@ -36,3 +37,6 @@ class Backend(Protocol):
         self, *, include_default_background: bool, ignore_colors: set[str] | None
     ) -> WorkbookColorsMap | None:
         """Extract colors map from the workbook."""
+
+    def extract_merged_cells(self) -> MergedCellData:
+        """Extract merged cell ranges from the workbook."""

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/backends/com_backend.py

@@ -11,7 +11,7 @@ import xlwings as xw
 from ...models import PrintArea
 from ..cells import WorkbookColorsMap, extract_sheet_colors_map_com
 from ..ranges import parse_range_zero_based
-from .base import PrintAreaData
+from .base import MergedCellData, PrintAreaData
 
 logger = logging.getLogger(__name__)
 
@@ -154,6 +154,10 @@ class ComBackend:
                 continue
         return results
 
+    def extract_merged_cells(self) -> MergedCellData:
+        """Extract merged cell ranges via COM (not implemented)."""
+        raise NotImplementedError("COM merged cell extraction is not implemented.")
+
 
 def _parse_print_area_range(range_str: str) -> tuple[int, int, int, int] | None:
     """Parse an Excel range string into zero-based coordinates.

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/backends/openpyxl_backend.py

@@ -13,10 +13,11 @@ from ..cells import (
     extract_sheet_cells,
     extract_sheet_cells_with_links,
     extract_sheet_colors_map,
+    extract_sheet_merged_cells,
 )
 from ..ranges import parse_range_zero_based
 from ..workbook import openpyxl_workbook
-from .base import CellData, PrintAreaData
+from .base import CellData, MergedCellData, PrintAreaData
 
 logger = logging.getLogger(__name__)
 
@@ -87,6 +88,17 @@ class OpenpyxlBackend:
             )
             return None
 
+    def extract_merged_cells(self) -> MergedCellData:
+        """Extract merged cell ranges per sheet.
+
+        Returns:
+            Mapping of sheet name to merged cell ranges.
+        """
+        try:
+            return extract_sheet_merged_cells(self.file_path)
+        except Exception:
+            return {}
+
     def detect_tables(self, sheet_name: str) -> list[str]:
         """Detect table candidates for a single sheet.
 

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/cells.py

@@ -15,7 +15,7 @@ from openpyxl.worksheet.worksheet import Worksheet
 import pandas as pd
 import xlwings as xw
 
-from ..models import CellRow
+from ..models import CellRow, MergedCell
 from .workbook import openpyxl_workbook
 
 logger = logging.getLogger(__name__)
@@ -526,6 +526,41 @@ def extract_sheet_cells_with_links(file_path: Path) -> dict[str, list[CellRow]]:
     return merged
 
 
+def extract_sheet_merged_cells(file_path: Path) -> dict[str, list[MergedCell]]:
+    """Extract merged cell ranges per sheet via openpyxl.
+
+    Args:
+        file_path: Excel workbook path.
+
+    Returns:
+        Mapping of sheet name to merged cell ranges.
+    """
+    merged_by_sheet: dict[str, list[MergedCell]] = {}
+    with openpyxl_workbook(file_path, data_only=True, read_only=False) as wb:
+        for ws in wb.worksheets:
+            merged_ranges = getattr(ws, "merged_cells", None)
+            if merged_ranges is None:
+                merged_by_sheet[ws.title] = []
+                continue
+            results: list[MergedCell] = []
+            for merged_range in getattr(merged_ranges, "ranges", []):
+                bounds = range_boundaries(str(merged_range))
+                min_col, min_row, max_col, max_row = bounds
+                cell_value = ws.cell(row=min_row, column=min_col).value
+                value_str = "" if cell_value is None else str(cell_value)
+                results.append(
+                    MergedCell(
+                        r1=min_row,
+                        c1=min_col - 1,
+                        r2=max_row,
+                        c2=max_col - 1,
+                        v=value_str,
+                    )
+                )
+            merged_by_sheet[ws.title] = results
+    return merged_by_sheet
+
+
 def shrink_to_content(  # noqa: C901
     sheet: xw.Sheet,
     top: int,

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/integrate.py

@@ -17,6 +17,7 @@ def extract_workbook(  # noqa: C901
     include_colors_map: bool | None = None,
     include_default_background: bool = False,
     ignore_colors: set[str] | None = None,
+    include_merged_cells: bool | None = None,
 ) -> WorkbookData:
     """Extract workbook and return WorkbookData.
 
@@ -31,6 +32,7 @@ def extract_workbook(  # noqa: C901
         include_colors_map: Whether to include colors map; None uses mode defaults.
         include_default_background: Whether to include default background color.
         ignore_colors: Optional set of color keys to ignore.
+        include_merged_cells: Whether to include merged cell ranges; None uses mode defaults.
 
     Returns:
         Extracted WorkbookData.
@@ -47,6 +49,7 @@ def extract_workbook(  # noqa: C901
         include_colors_map=include_colors_map,
         include_default_background=include_default_background,
         ignore_colors=ignore_colors,
+        include_merged_cells=include_merged_cells,
     )
     result = run_extraction_pipeline(inputs)
     return result.workbook

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/modeling.py

@@ -6,6 +6,7 @@ from ..models import (
     Arrow,
     CellRow,
     Chart,
+    MergedCell,
     PrintArea,
     Shape,
     SheetData,
@@ -26,6 +27,7 @@ class SheetRawData:
         print_areas: Extracted print areas.
         auto_print_areas: Extracted auto page-break areas.
         colors_map: Mapping of color keys to (row, column) positions.
+        merged_cells: Extracted merged cell ranges.
     """
 
     rows: list[CellRow]
@@ -35,6 +37,7 @@ class SheetRawData:
     print_areas: list[PrintArea]
     auto_print_areas: list[PrintArea]
     colors_map: dict[str, list[tuple[int, int]]]
+    merged_cells: list[MergedCell]
 
 
 @dataclass(frozen=True)
@@ -67,6 +70,7 @@ def build_sheet_data(raw: SheetRawData) -> SheetData:
         print_areas=raw.print_areas,
         auto_print_areas=raw.auto_print_areas,
         colors_map=raw.colors_map,
+        merged_cells=raw.merged_cells,
     )
 
 

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/core/pipeline.py

@@ -10,7 +10,16 @@ from typing import Literal
 import xlwings as xw
 
 from ..errors import FallbackReason
-from ..models import Arrow, CellRow, Chart, PrintArea, Shape, SmartArt, WorkbookData
+from ..models import (
+    Arrow,
+    CellRow,
+    Chart,
+    MergedCell,
+    PrintArea,
+    Shape,
+    SmartArt,
+    WorkbookData,
+)
 from .backends.com_backend import ComBackend
 from .backends.openpyxl_backend import OpenpyxlBackend
 from .cells import WorkbookColorsMap, detect_tables
@@ -23,6 +32,7 @@ from .workbook import xlwings_workbook
 ExtractionMode = Literal["light", "standard", "verbose"]
 CellData = dict[str, list[CellRow]]
 PrintAreaData = dict[str, list[PrintArea]]
+MergedCellData = dict[str, list[MergedCell]]
 ShapeData = dict[str, list[Shape | Arrow | SmartArt]]
 ChartData = dict[str, list[Chart]]
 
@@ -42,6 +52,7 @@ class ExtractionInputs:
         include_colors_map: Whether to include background colors map.
         include_default_background: Whether to include default background color.
         ignore_colors: Optional set of color keys to ignore.
+        include_merged_cells: Whether to include merged cell ranges.
     """
 
     file_path: Path
@@ -52,6 +63,7 @@ class ExtractionInputs:
     include_colors_map: bool
     include_default_background: bool
     ignore_colors: set[str] | None
+    include_merged_cells: bool
 
 
 @dataclass
@@ -65,6 +77,7 @@ class ExtractionArtifacts:
         colors_map_data: Extracted colors map for workbook sheets.
         shape_data: Extracted shapes per sheet.
         chart_data: Extracted charts per sheet.
+        merged_cell_data: Extracted merged cell ranges per sheet.
     """
 
     cell_data: CellData = field(default_factory=dict)
@@ -73,6 +86,7 @@ class ExtractionArtifacts:
     colors_map_data: WorkbookColorsMap | None = None
     shape_data: ShapeData = field(default_factory=dict)
     chart_data: ChartData = field(default_factory=dict)
+    merged_cell_data: MergedCellData = field(default_factory=dict)
 
 
 ExtractionStep = Callable[[ExtractionInputs, ExtractionArtifacts], None]
@@ -164,6 +178,7 @@ def resolve_extraction_inputs(
     include_colors_map: bool | None,
     include_default_background: bool,
     ignore_colors: set[str] | None,
+    include_merged_cells: bool | None,
 ) -> ExtractionInputs:
     """Resolve include flags and normalize inputs for the pipeline.
 
@@ -176,6 +191,7 @@ def resolve_extraction_inputs(
         include_colors_map: Whether to include background colors; None uses mode defaults.
         include_default_background: Include default background colors when colors_map is enabled.
         ignore_colors: Optional set of colors to ignore when colors_map is enabled.
+        include_merged_cells: Whether to include merged cell ranges; None uses mode defaults.
 
     Returns:
         Resolved ExtractionInputs.
@@ -203,6 +219,9 @@ def resolve_extraction_inputs(
     resolved_ignore_colors = ignore_colors if resolved_colors_map else None
     if resolved_colors_map and resolved_ignore_colors is None:
         resolved_ignore_colors = set()
+    resolved_merged_cells = (
+        include_merged_cells if include_merged_cells is not None else mode != "light"
+    )
 
     return ExtractionInputs(
         file_path=normalized_file_path,
@@ -213,6 +232,7 @@ def resolve_extraction_inputs(
         include_colors_map=resolved_colors_map,
         include_default_background=resolved_default_background,
         ignore_colors=resolved_ignore_colors,
+        include_merged_cells=resolved_merged_cells,
     )
 
 
@@ -258,6 +278,11 @@ def build_pre_com_pipeline(inputs: ExtractionInputs) -> list[ExtractionStep]:
                 step=step_extract_colors_map_openpyxl,
                 enabled=lambda _inputs: _inputs.include_colors_map,
             ),
+            StepConfig(
+                name="merged_cells_openpyxl",
+                step=step_extract_merged_cells_openpyxl,
+                enabled=lambda _inputs: _inputs.include_merged_cells,
+            ),
         ),
         "standard": (
             StepConfig(
@@ -276,6 +301,11 @@ def build_pre_com_pipeline(inputs: ExtractionInputs) -> list[ExtractionStep]:
                 enabled=lambda _inputs: _inputs.include_colors_map
                 and bool(os.getenv("SKIP_COM_TESTS")),
             ),
+            StepConfig(
+                name="merged_cells_openpyxl",
+                step=step_extract_merged_cells_openpyxl,
+                enabled=lambda _inputs: _inputs.include_merged_cells,
+            ),
         ),
         "verbose": (
             StepConfig(
@@ -294,6 +324,11 @@ def build_pre_com_pipeline(inputs: ExtractionInputs) -> list[ExtractionStep]:
                 enabled=lambda _inputs: _inputs.include_colors_map
                 and bool(os.getenv("SKIP_COM_TESTS")),
             ),
+            StepConfig(
+                name="merged_cells_openpyxl",
+                step=step_extract_merged_cells_openpyxl,
+                enabled=lambda _inputs: _inputs.include_merged_cells,
+            ),
         ),
     }
     steps: list[ExtractionStep] = []
@@ -432,6 +467,19 @@ def step_extract_colors_map_openpyxl(
     )
 
 
+def step_extract_merged_cells_openpyxl(
+    inputs: ExtractionInputs, artifacts: ExtractionArtifacts
+) -> None:
+    """Extract merged cell ranges via openpyxl.
+
+    Args:
+        inputs: Pipeline inputs.
+        artifacts: Artifact container to update.
+    """
+    backend = OpenpyxlBackend(inputs.file_path)
+    artifacts.merged_cell_data = backend.extract_merged_cells()
+
+
 def step_extract_shapes_com(
     inputs: ExtractionInputs, artifacts: ExtractionArtifacts, workbook: xw.Book
 ) -> None:
@@ -540,6 +588,7 @@ def collect_sheet_raw_data(
     cell_data: CellData,
     shape_data: ShapeData,
     chart_data: ChartData,
+    merged_cell_data: MergedCellData,
     workbook: xw.Book,
     mode: ExtractionMode = "standard",
     print_area_data: PrintAreaData | None = None,
@@ -552,6 +601,7 @@ def collect_sheet_raw_data(
         cell_data: Extracted cell rows per sheet.
         shape_data: Extracted shapes per sheet.
         chart_data: Extracted charts per sheet.
+        merged_cell_data: Extracted merged cells per sheet.
         workbook: xlwings workbook instance.
         mode: Extraction mode.
         print_area_data: Optional print area data per sheet.
@@ -574,6 +624,7 @@ def collect_sheet_raw_data(
             if auto_page_break_data
             else [],
             colors_map=_resolve_sheet_colors_map(colors_map_data, sheet_name),
+            merged_cells=merged_cell_data.get(sheet_name, []),
         )
         result[sheet_name] = sheet_raw
     return result
@@ -620,6 +671,7 @@ def run_extraction_pipeline(inputs: ExtractionInputs) -> PipelineResult:
                     cell_data=artifacts.cell_data,
                     shape_data=artifacts.shape_data,
                     chart_data=artifacts.chart_data,
+                    merged_cell_data=artifacts.merged_cell_data,
                     workbook=workbook,
                     mode=inputs.mode,
                     print_area_data=artifacts.print_area_data
@@ -691,6 +743,7 @@ def build_cells_tables_workbook(
             else [],
             auto_print_areas=[],
             colors_map=sheet_colors.colors_map if sheet_colors else {},
+            merged_cells=artifacts.merged_cell_data.get(sheet_name, []),
         )
     raw = WorkbookRawData(book_name=inputs.file_path.name, sheets=sheets)
     return build_workbook_data(raw)

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/engine.py

@@ -70,6 +70,7 @@ class StructOptions:
                       before extraction. Use this to tweak table detection heuristics
                       per engine instance without touching global state.
         include_colors_map: Whether to extract background color maps.
+        include_merged_cells: Whether to extract merged cell ranges.
         colors: Color extraction options.
     """
 
@@ -79,6 +80,7 @@ class StructOptions:
     )
     include_cell_links: bool | None = None  # None -> auto: verbose=True, others=False
     include_colors_map: bool | None = None  # None -> auto: verbose=True, others=False
+    include_merged_cells: bool | None = None  # None -> auto: light=False, others=True
     colors: ColorsOptions = field(default_factory=ColorsOptions)
 
 
@@ -121,6 +123,9 @@ class FilterOptions(BaseModel):
     include_auto_print_areas: bool = Field(
         default=False, description="Include COM-computed auto page-break areas."
     )
+    include_merged_cells: bool = Field(
+        default=True, description="Include merged cell ranges."
+    )
 
 
 class DestinationOptions(BaseModel):
@@ -279,6 +284,9 @@ class ExStructEngine:
             colors_map=sheet.colors_map,
             print_areas=sheet.print_areas if include_print_areas else [],
             auto_print_areas=sheet.auto_print_areas if include_auto_print_areas else [],
+            merged_cells=sheet.merged_cells
+            if self.output.filters.include_merged_cells
+            else [],
         )
 
     def _filter_workbook(
@@ -348,6 +356,7 @@ class ExStructEngine:
                 include_colors_map=self.options.include_colors_map,
                 include_default_background=self.options.colors.include_default_background,
                 ignore_colors=self.options.colors.ignore_colors_set(),
+                include_merged_cells=self.options.include_merged_cells,
             )
 
     def serialize(

{exstruct-0.3.1 → exstruct-0.3.2}/src/exstruct/models/__init__.py

@@ -76,6 +76,16 @@ class SmartArt(BaseShape):
     )
 
 
+class MergedCell(BaseModel):
+    """Metadata for a merged cell range."""
+
+    r1: int = Field(description="Start row (1-based).")
+    c1: int = Field(description="Start column (0-based).")
+    r2: int = Field(description="End row (1-based, inclusive).")
+    c2: int = Field(description="End column (0-based, inclusive).")
+    v: str = ""
+
+
 class CellRow(BaseModel):
     """A single row of cells with optional hyperlinks."""
 
@@ -160,6 +170,9 @@ class SheetData(BaseModel):
             "where row is 1-based and column is 0-based."
         ),
     )
+    merged_cells: list[MergedCell] = Field(
+        default_factory=list, description="Merged cell ranges on the sheet."
+    )
 
     def _as_payload(self) -> dict[str, object]:
         from ..io import dict_without_empty_values