exstruct 0.2.0__tar.gz → 0.2.2__tar.gz

{exstruct-0.2.0 → exstruct-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.0
+Version: 0.2.2
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -41,6 +41,7 @@ Requires-Dist: pydantic>=2.12.5
 Requires-Dist: scipy>=1.16.3
 Requires-Dist: xlwings>=0.33.16
 Requires-Dist: pypdfium2>=5.1.0 ; extra == 'render'
+Requires-Dist: pillow>=12.0.0 ; extra == 'render'
 Requires-Dist: python-toon>=0.1.3 ; extra == 'toon'
 Requires-Dist: pyyaml>=6.0.3 ; extra == 'yaml'
 Requires-Python: >=3.11
@@ -55,14 +56,16 @@ Description-Content-Type: text/markdown
 
 # ExStruct — Excel Structured Extraction Engine
 
-<img width="3168" height="1344" alt="Gemini_Generated_Image_nlwx0bnlwx0bnlwx" src="https://github.com/user-attachments/assets/90231682-fb42-428e-bf01-4389e8116b65" />
+[![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml)
 
-ExStruct reads Excel workbooks and outputs structured data (tables, shapes, charts) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
+![ExStruct Image](/docs/assets/icon.webp)
+
+ExStruct reads Excel workbooks and outputs structured data (tables, shapes, charts, 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), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
 
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, and table candidates per sheet.
-- **Output modes**: `light` (cells + table candidates only), `standard` (texted shapes + arrows, charts), `verbose` (all shapes with width/height).
+- **Output modes**: `light` (cells + table candidates only), `standard` (texted shapes + arrows, charts), `verbose` (all shapes with width/height). Verbose also emits cell hyperlinks.
 - **Formats**: JSON (compact by default, `--pretty` available), YAML, TOON (optional dependencies).
 - **Table detection tuning**: adjust heuristics at runtime via API.
 - **CLI rendering** (Excel required): optional PDF and per-sheet PNGs.
@@ -78,41 +81,61 @@ Optional extras:
 
 - YAML: `pip install pyyaml`
 - TOON: `pip install python-toon`
-- Rendering (PDF/PNG): Excel + `pip install pypdfium2`
+- Rendering (PDF/PNG): Excel + `pip install pypdfium2 pillow`
+- All extras at once: `pip install exstruct[yaml,toon,render]`
 
-## Quick Start (CLI)
-
-```bash
-exstruct input.xlsx > output.json          # compact JSON to stdout (default)
-exstruct input.xlsx -o out.json --pretty   # pretty JSON to a file
-exstruct input.xlsx --format yaml          # YAML (needs pyyaml)
-exstruct input.xlsx --format toon          # TOON (needs python-toon)
-exstruct input.xlsx --sheets-dir sheets/   # split per sheet in chosen format
-exstruct input.xlsx --mode light           # cells + table candidates only
-exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
-```
+Platform note:
+- Full extraction (shapes/charts) targets Windows + Excel (COM via xlwings). On other platforms, use `mode=light` to get cells + `table_candidates` safely.
+
+## Quick Start (CLI)
+
+```bash
+exstruct input.xlsx > output.json          # compact JSON to stdout (default)
+exstruct input.xlsx -o out.json --pretty   # pretty JSON to a file
+exstruct input.xlsx --format yaml          # YAML (needs pyyaml)
+exstruct input.xlsx --format toon          # TOON (needs python-toon)
+exstruct input.xlsx --sheets-dir sheets/   # split per sheet in chosen format
+exstruct input.xlsx --mode light           # cells + table candidates only
+exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
+```
 
 ## Quick Start (Python)
 
 ```python
 from pathlib import Path
-from exstruct import extract, export, set_table_detection_params
-
-# Tune table detection (optional)
-set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
+from exstruct import extract, export, set_table_detection_params
+
+# Tune table detection (optional)
+set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
+
+# Extract with modes: "light", "standard", "verbose"
+wb = extract("input.xlsx", mode="standard")
+export(wb, Path("out.json"), pretty=False)  # compact JSON
+
+# Model helpers: iterate, index, and serialize directly from the models
+first_sheet = wb["Sheet1"]           # __getitem__ access
+for name, sheet in wb:               # __iter__ yields (name, SheetData)
+    print(name, len(sheet.rows))
+wb.save("out.json", pretty=True)     # WorkbookData → file (by extension)
+first_sheet.save("sheet.json")       # SheetData → file (by extension)
+print(first_sheet.to_yaml())         # YAML text (requires pyyaml)
+
+# ExStructEngine: per-instance options for extraction/output
+from exstruct import ExStructEngine, StructOptions, OutputOptions
 
-# Extract with modes: "light", "standard", "verbose"
-wb = extract("input.xlsx", mode="standard")
-export(wb, Path("out.json"), pretty=False)  # compact JSON
+engine = ExStructEngine(
+    options=StructOptions(mode="verbose"),  # verbose includes hyperlinks by default
+    output=OutputOptions(include_shapes=False, pretty=True),
+)
+wb2 = engine.extract("input.xlsx")
+engine.export(wb2, Path("out_filtered.json"))  # drops shapes via OutputOptions
 
-# Model helpers: iterate, index, and serialize directly from the models
-first_sheet = wb["Sheet1"]           # __getitem__ access
-for name, sheet in wb:               # __iter__ yields (name, SheetData)
-    print(name, len(sheet.rows))
-wb.save("out.json", pretty=True)     # WorkbookData → file (by extension)
-first_sheet.save("sheet.json")       # SheetData → file (by extension)
-print(first_sheet.to_yaml())         # YAML text (requires pyyaml)
-```
+# Enable hyperlinks in other modes
+engine_links = ExStructEngine(options=StructOptions(mode="standard", include_cell_links=True))
+with_links = engine_links.extract("input.xlsx")
+```
+
+**Note (non-COM environments):** If Excel COM is unavailable, extraction still runs and returns cells + `table_candidates`; `shapes`/`charts` will be empty.
 
 ## Table Detection Tuning
 
@@ -129,11 +152,11 @@ set_table_detection_params(
 
 Use higher thresholds to reduce false positives; lower them if true tables are missed.
 
-## Output Modes
-
-- **light**: cells + table candidates (no COM needed).
-- **standard**: texted shapes + arrows, charts (COM if available), table candidates.
-- **verbose**: all shapes (with width/height), charts, table candidates.
+## 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, and cell hyperlinks.
 
 ## Error Handling / Fallbacks
 
@@ -160,7 +183,8 @@ To show how well exstruct can structure Excel, we parse a workbook that combines
 - Flowchart built only with shapes
 
 (Screenshot below is the actual sample Excel sheet)
-<img width="1842" height="1242" alt="スクリーンショット 2025-12-04 221252" src="https://github.com/user-attachments/assets/37ffcb3d-121e-47c1-a59f-0497337c85d9" />
+![Sample Excel](/docs/assets/demo_sheet.png)
+Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -354,3 +378,18 @@ BSD-3-Clause. See `LICENSE` for details.
 ## Documentation
 
 - API Reference (GitHub Pages): https://harumiweb.github.io/exstruct/
+# Engine option cheat sheet
+
+| Option class   | Field               | Meaning |
+| -------------- | ------------------- | ------- |
+| StructOptions  | mode                | "light"/"standard"/"verbose" |
+|                | table_params        | Dict passed to `set_table_detection_params` (table_score_threshold, density_min, coverage_min, min_nonempty_cells) |
+|                | include_cell_links  | Include cell hyperlinks in `rows[*].links` (None -> auto: verbose=True, others=False) |
+| OutputOptions  | fmt                 | Default format ("json"/"yaml"/"yml"/"toon") |
+|                | pretty / indent     | Pretty-print JSON and control indent |
+|                | include_rows        | Include rows (False to drop) |
+|                | include_shapes      | Include shapes |
+|                | include_charts      | Include charts |
+|                | include_tables      | Include table_candidates |
+|                | sheets_dir          | Optional directory for per-sheet exports |
+|                | stream              | Default stream when output_path is None |

{exstruct-0.2.0 → exstruct-0.2.2}/README.md

@@ -1,13 +1,15 @@
 # ExStruct — Excel Structured Extraction Engine
 
-<img width="3168" height="1344" alt="Gemini_Generated_Image_nlwx0bnlwx0bnlwx" src="https://github.com/user-attachments/assets/90231682-fb42-428e-bf01-4389e8116b65" />
+[![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml)
 
-ExStruct reads Excel workbooks and outputs structured data (tables, shapes, charts) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
+![ExStruct Image](/docs/assets/icon.webp)
+
+ExStruct reads Excel workbooks and outputs structured data (tables, shapes, charts, 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), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
 
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, and table candidates per sheet.
-- **Output modes**: `light` (cells + table candidates only), `standard` (texted shapes + arrows, charts), `verbose` (all shapes with width/height).
+- **Output modes**: `light` (cells + table candidates only), `standard` (texted shapes + arrows, charts), `verbose` (all shapes with width/height). Verbose also emits cell hyperlinks.
 - **Formats**: JSON (compact by default, `--pretty` available), YAML, TOON (optional dependencies).
 - **Table detection tuning**: adjust heuristics at runtime via API.
 - **CLI rendering** (Excel required): optional PDF and per-sheet PNGs.
@@ -23,41 +25,61 @@ Optional extras:
 
 - YAML: `pip install pyyaml`
 - TOON: `pip install python-toon`
-- Rendering (PDF/PNG): Excel + `pip install pypdfium2`
+- Rendering (PDF/PNG): Excel + `pip install pypdfium2 pillow`
+- All extras at once: `pip install exstruct[yaml,toon,render]`
 
-## Quick Start (CLI)
-
-```bash
-exstruct input.xlsx > output.json          # compact JSON to stdout (default)
-exstruct input.xlsx -o out.json --pretty   # pretty JSON to a file
-exstruct input.xlsx --format yaml          # YAML (needs pyyaml)
-exstruct input.xlsx --format toon          # TOON (needs python-toon)
-exstruct input.xlsx --sheets-dir sheets/   # split per sheet in chosen format
-exstruct input.xlsx --mode light           # cells + table candidates only
-exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
-```
+Platform note:
+- Full extraction (shapes/charts) targets Windows + Excel (COM via xlwings). On other platforms, use `mode=light` to get cells + `table_candidates` safely.
+
+## Quick Start (CLI)
+
+```bash
+exstruct input.xlsx > output.json          # compact JSON to stdout (default)
+exstruct input.xlsx -o out.json --pretty   # pretty JSON to a file
+exstruct input.xlsx --format yaml          # YAML (needs pyyaml)
+exstruct input.xlsx --format toon          # TOON (needs python-toon)
+exstruct input.xlsx --sheets-dir sheets/   # split per sheet in chosen format
+exstruct input.xlsx --mode light           # cells + table candidates only
+exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
+```
 
 ## Quick Start (Python)
 
 ```python
 from pathlib import Path
-from exstruct import extract, export, set_table_detection_params
-
-# Tune table detection (optional)
-set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
+from exstruct import extract, export, set_table_detection_params
+
+# Tune table detection (optional)
+set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
+
+# Extract with modes: "light", "standard", "verbose"
+wb = extract("input.xlsx", mode="standard")
+export(wb, Path("out.json"), pretty=False)  # compact JSON
+
+# Model helpers: iterate, index, and serialize directly from the models
+first_sheet = wb["Sheet1"]           # __getitem__ access
+for name, sheet in wb:               # __iter__ yields (name, SheetData)
+    print(name, len(sheet.rows))
+wb.save("out.json", pretty=True)     # WorkbookData → file (by extension)
+first_sheet.save("sheet.json")       # SheetData → file (by extension)
+print(first_sheet.to_yaml())         # YAML text (requires pyyaml)
+
+# ExStructEngine: per-instance options for extraction/output
+from exstruct import ExStructEngine, StructOptions, OutputOptions
 
-# Extract with modes: "light", "standard", "verbose"
-wb = extract("input.xlsx", mode="standard")
-export(wb, Path("out.json"), pretty=False)  # compact JSON
+engine = ExStructEngine(
+    options=StructOptions(mode="verbose"),  # verbose includes hyperlinks by default
+    output=OutputOptions(include_shapes=False, pretty=True),
+)
+wb2 = engine.extract("input.xlsx")
+engine.export(wb2, Path("out_filtered.json"))  # drops shapes via OutputOptions
 
-# Model helpers: iterate, index, and serialize directly from the models
-first_sheet = wb["Sheet1"]           # __getitem__ access
-for name, sheet in wb:               # __iter__ yields (name, SheetData)
-    print(name, len(sheet.rows))
-wb.save("out.json", pretty=True)     # WorkbookData → file (by extension)
-first_sheet.save("sheet.json")       # SheetData → file (by extension)
-print(first_sheet.to_yaml())         # YAML text (requires pyyaml)
-```
+# Enable hyperlinks in other modes
+engine_links = ExStructEngine(options=StructOptions(mode="standard", include_cell_links=True))
+with_links = engine_links.extract("input.xlsx")
+```
+
+**Note (non-COM environments):** If Excel COM is unavailable, extraction still runs and returns cells + `table_candidates`; `shapes`/`charts` will be empty.
 
 ## Table Detection Tuning
 
@@ -74,11 +96,11 @@ set_table_detection_params(
 
 Use higher thresholds to reduce false positives; lower them if true tables are missed.
 
-## Output Modes
-
-- **light**: cells + table candidates (no COM needed).
-- **standard**: texted shapes + arrows, charts (COM if available), table candidates.
-- **verbose**: all shapes (with width/height), charts, table candidates.
+## 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, and cell hyperlinks.
 
 ## Error Handling / Fallbacks
 
@@ -105,7 +127,8 @@ To show how well exstruct can structure Excel, we parse a workbook that combines
 - Flowchart built only with shapes
 
 (Screenshot below is the actual sample Excel sheet)
-<img width="1842" height="1242" alt="スクリーンショット 2025-12-04 221252" src="https://github.com/user-attachments/assets/37ffcb3d-121e-47c1-a59f-0497337c85d9" />
+![Sample Excel](/docs/assets/demo_sheet.png)
+Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -299,3 +322,18 @@ BSD-3-Clause. See `LICENSE` for details.
 ## Documentation
 
 - API Reference (GitHub Pages): https://harumiweb.github.io/exstruct/
+# Engine option cheat sheet
+
+| Option class   | Field               | Meaning |
+| -------------- | ------------------- | ------- |
+| StructOptions  | mode                | "light"/"standard"/"verbose" |
+|                | table_params        | Dict passed to `set_table_detection_params` (table_score_threshold, density_min, coverage_min, min_nonempty_cells) |
+|                | include_cell_links  | Include cell hyperlinks in `rows[*].links` (None -> auto: verbose=True, others=False) |
+| OutputOptions  | fmt                 | Default format ("json"/"yaml"/"yml"/"toon") |
+|                | pretty / indent     | Pretty-print JSON and control indent |
+|                | include_rows        | Include rows (False to drop) |
+|                | include_shapes      | Include shapes |
+|                | include_charts      | Include charts |
+|                | include_tables      | Include table_candidates |
+|                | sheets_dir          | Optional directory for per-sheet exports |
+|                | stream              | Default stream when output_path is None |

{exstruct-0.2.0 → exstruct-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.0"
+version = "0.2.2"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -33,7 +33,7 @@ dev = [
 [project.optional-dependencies]
 yaml = ["pyyaml>=6.0.3"]
 toon = ["python-toon>=0.1.3"]
-render = ["pypdfium2>=5.1.0"]
+render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
 
 [project.scripts]
 exstruct = "exstruct.cli.main:main"
@@ -43,3 +43,10 @@ Homepage = "https://harumiweb.github.io/exstruct/"
 Repository = "https://github.com/harumiWeb/exstruct"
 Issues = "https://github.com/harumiWeb/exstruct/issues"
 Documentation = "https://harumiweb.github.io/exstruct/"
+
+[tool.coverage.run]
+omit = [
+    "tests/*",
+    "*/test_*.py",
+    "*/gen_py/*",
+]

{exstruct-0.2.0 → exstruct-0.2.2}/src/exstruct/__init__.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
-from pathlib import Path
+from pathlib import Path
 from typing import Literal, Optional, TextIO
 
 from .core.integrate import extract_workbook
 from .core.cells import set_table_detection_params
+from .engine import ExStructEngine, OutputOptions, StructOptions
 from .io import save_as_json, save_as_toon, save_as_yaml, save_sheets, serialize_workbook
 from .models import CellRow, Chart, ChartSeries, Shape, SheetData, WorkbookData
 from .render import export_pdf, export_sheet_images
@@ -24,6 +25,9 @@ __all__ = [
     "SheetData",
     "WorkbookData",
     "set_table_detection_params",
+    "ExStructEngine",
+    "StructOptions",
+    "OutputOptions",
 ]
 
 
@@ -32,9 +36,9 @@ ExtractionMode = Literal["light", "standard", "verbose"]
 
 def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> WorkbookData:
     """Extract workbook semantic structure and return WorkbookData."""
-    if mode not in ("light", "standard", "verbose"):
-        raise ValueError(f"Unsupported mode: {mode}")
-    return extract_workbook(Path(file_path), mode=mode)
+    include_links = True if mode == "verbose" else False
+    engine = ExStructEngine(options=StructOptions(mode=mode, include_cell_links=include_links))
+    return engine.extract(file_path, mode=mode)
 
 
 def export(
@@ -99,45 +103,20 @@ def process_excel(
     - If output_path is None, writes the serialized workbook to stdout (or provided stream).
     - If sheets_dir is given, also writes per-sheet files into that directory.
     """
-    if mode not in ("light", "standard", "verbose"):
-        raise ValueError(f"Unsupported mode: {mode}")
-    workbook_model = extract(file_path, mode=mode)
-    text = serialize_workbook(workbook_model, fmt=out_fmt, pretty=pretty, indent=indent)
-    target_stream = stream
-
-    def _suffix_for(fmt: str) -> str:
-        if fmt in ("yaml", "yml"):
-            return ".yaml"
-        if fmt == "toon":
-            return ".toon"
-        if fmt == "json":
-            return ".json"
-        raise ValueError(f"Unsupported export format: {fmt}")
-
-    if output_path is not None:
-        output_path.write_text(text, encoding="utf-8")
-    else:
-        if target_stream is None:
-            import sys
-
-            target_stream = sys.stdout
-        target_stream.write(text)
-        if not text.endswith("\n"):
-            target_stream.write("\n")
-
-    if sheets_dir is not None:
-        save_sheets(
-            workbook_model,
-            sheets_dir,
-            fmt=out_fmt,
-            pretty=pretty,
-            indent=indent,
-        )
-
-    if pdf or image:
-        base_target = output_path or file_path.with_suffix(_suffix_for(out_fmt))
-        pdf_path = base_target.with_suffix(".pdf")
-        export_pdf(file_path, pdf_path)
-        if image:
-            images_dir = pdf_path.parent / f"{pdf_path.stem}_images"
-            export_sheet_images(file_path, images_dir, dpi=dpi)
+    engine = ExStructEngine(
+        options=StructOptions(mode=mode),
+        output=OutputOptions(fmt=out_fmt, pretty=pretty, indent=indent, sheets_dir=sheets_dir, stream=stream),
+    )
+    engine.process(
+        file_path=file_path,
+        output_path=output_path,
+        out_fmt=out_fmt,
+        image=image,
+        pdf=pdf,
+        dpi=dpi,
+        mode=mode,
+        pretty=pretty,
+        indent=indent,
+        sheets_dir=sheets_dir,
+        stream=stream,
+    )

{exstruct-0.2.0 → exstruct-0.2.2}/src/exstruct/core/cells.py

@@ -33,25 +33,64 @@ def warn_once(key: str, message: str) -> None:
         _warned_keys.add(key)
 
 
-def extract_sheet_cells(file_path: Path) -> Dict[str, List[CellRow]]:
-    """Read all sheets via pandas and convert to CellRow list while skipping empty cells."""
-    dfs = pd.read_excel(file_path, header=None, sheet_name=None, dtype=str)
-    result: Dict[str, List[CellRow]] = {}
-    for sheet_name, df in dfs.items():
-        df = df.fillna("")
-        rows: List[CellRow] = []
-        for excel_row, row in enumerate(df.itertuples(index=False, name=None), start=1):
-            filtered: Dict[str, int | float | str] = {}
-            for j, v in enumerate(row):
-                s = "" if v is None else str(v)
-                if s.strip() == "":
-                    continue
-                filtered[str(j)] = _coerce_numeric_preserve_format(s)
-            if not filtered:
-                continue
-            rows.append(CellRow(r=excel_row, c=filtered))
-        result[sheet_name] = rows
-    return result
+def extract_sheet_cells(file_path: Path) -> Dict[str, List[CellRow]]:
+    """Read all sheets via pandas and convert to CellRow list while skipping empty cells."""
+    dfs = pd.read_excel(file_path, header=None, sheet_name=None, dtype=str)
+    result: Dict[str, List[CellRow]] = {}
+    for sheet_name, df in dfs.items():
+        df = df.fillna("")
+        rows: List[CellRow] = []
+        for excel_row, row in enumerate(df.itertuples(index=False, name=None), start=1):
+            filtered: Dict[str, int | float | str] = {}
+            for j, v in enumerate(row):
+                s = "" if v is None else str(v)
+                if s.strip() == "":
+                    continue
+                filtered[str(j)] = _coerce_numeric_preserve_format(s)
+            if not filtered:
+                continue
+            rows.append(CellRow(r=excel_row, c=filtered))
+        result[sheet_name] = rows
+    return result
+
+
+def extract_sheet_cells_with_links(file_path: Path) -> Dict[str, List[CellRow]]:
+    """
+    Extract cells and hyperlinks per sheet.
+
+    Returns:
+        {sheet_name: [CellRow(r=..., c=..., links={"col_index": url, ...}), ...]}
+
+    Notes:
+        - Uses pandas extraction for values (same filtering as extract_sheet_cells).
+        - Collects hyperlinks via openpyxl (requires read_only=False because border maps/hyperlinks need full objects).
+        - Links are mapped by column index string (e.g., "0") to hyperlink.target.
+    """
+    cell_rows = extract_sheet_cells(file_path)
+    wb = load_workbook(file_path, data_only=True, read_only=False)
+    links_by_sheet: Dict[str, Dict[int, Dict[str, str]]] = {}
+    for ws in wb.worksheets:
+        sheet_links: Dict[int, Dict[str, str]] = {}
+        for row in ws.iter_rows():
+            for cell in row:
+                link = getattr(cell, "hyperlink", None)
+                target = getattr(link, "target", None) if link else None
+                if not target:
+                    continue
+                col_str = str(cell.col_idx - 1)  # zero-based to align with extract_sheet_cells
+                sheet_links.setdefault(cell.row, {})[col_str] = target
+        links_by_sheet[ws.title] = sheet_links
+
+    merged: Dict[str, List[CellRow]] = {}
+    for sheet_name, rows in cell_rows.items():
+        sheet_links = links_by_sheet.get(sheet_name, {})
+        merged_rows: List[CellRow] = []
+        for row in rows:
+            links = sheet_links.get(row.r, {})
+            merged_rows.append(CellRow(r=row.r, c=row.c, links=links or None))
+        merged[sheet_name] = merged_rows
+    wb.close()
+    return merged
 
 
 def shrink_to_content(

{exstruct-0.2.0 → exstruct-0.2.2}/src/exstruct/core/integrate.py

@@ -4,15 +4,17 @@ from pathlib import Path
 from typing import Dict, List, Literal
 
 import logging
+import os
 
 import xlwings as xw
 
 from ..models import CellRow, Shape, SheetData, WorkbookData
-from .cells import (
-    detect_tables,
-    detect_tables_openpyxl,
-    extract_sheet_cells,
-)
+from .cells import (
+    detect_tables,
+    detect_tables_openpyxl,
+    extract_sheet_cells,
+    extract_sheet_cells_with_links,
+)
 from .charts import get_charts
 from .shapes import get_shapes_with_position
 
@@ -74,13 +76,16 @@ def integrate_sheet_content(
 
 
 def extract_workbook(
-    file_path: Path, mode: Literal["light", "standard", "verbose"] = "standard"
+    file_path: Path,
+    mode: Literal["light", "standard", "verbose"] = "standard",
+    *,
+    include_cell_links: bool = False,
 ) -> WorkbookData:
     """Extract workbook and return WorkbookData; fallback to cells+tables if Excel COM is unavailable."""
     if mode not in _ALLOWED_MODES:
         raise ValueError(f"Unsupported mode: {mode}")
 
-    cell_data = extract_sheet_cells(file_path)
+    cell_data = extract_sheet_cells_with_links(file_path) if include_cell_links else extract_sheet_cells(file_path)
 
     def _cells_and_tables_only(reason: str) -> WorkbookData:
         sheets: Dict[str, SheetData] = {}
@@ -104,6 +109,9 @@ def extract_workbook(
     if mode == "light":
         return _cells_and_tables_only("Light mode selected.")
 
+    if os.getenv("SKIP_COM_TESTS"):
+        return _cells_and_tables_only("SKIP_COM_TESTS is set; skipping COM/xlwings access.")
+
     try:
         wb, close_app = _open_workbook(file_path)
     except Exception as e:

exstruct-0.2.2/src/exstruct/engine.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional, TextIO
+from contextlib import contextmanager
+
+from .core.integrate import extract_workbook
+from .core import cells as _cells
+from .core.cells import set_table_detection_params
+from .io import save_as_json, save_as_toon, save_as_yaml, save_sheets, serialize_workbook
+from .models import SheetData, WorkbookData
+from .render import export_pdf, export_sheet_images
+
+ExtractionMode = Literal["light", "standard", "verbose"]
+
+
+@dataclass(frozen=True)
+class StructOptions:
+    """
+    Extraction-time options for ExStructEngine.
+
+    Attributes:
+        mode: Extraction mode. One of "light", "standard", "verbose".
+              - light: cells + table candidates only (no COM, shapes/charts empty)
+              - standard: texted shapes + arrows + charts (if COM available)
+              - verbose: all shapes (width/height), charts, table candidates
+        table_params: Optional dict passed to `set_table_detection_params(**table_params)`
+                      before extraction. Use this to tweak table detection heuristics
+                      per engine instance without touching global state.
+    """
+
+    mode: ExtractionMode = "standard"
+    table_params: Optional[dict] = None  # forwarded to set_table_detection_params if provided
+    include_cell_links: Optional[bool] = None  # None → auto: verbose=True, others=False
+
+
+@dataclass(frozen=True)
+class OutputOptions:
+    """
+    Output-time options for ExStructEngine.
+
+    Attributes:
+        fmt: Default export format. One of "json", "yaml", "yml", "toon".
+        pretty: Whether to pretty-print JSON; default False (compact).
+        indent: Explicit indent size. If None and pretty=True, indent=2 for JSON.
+        include_rows: Include SheetData.rows in output (set False to drop).
+        include_shapes: Include SheetData.shapes in output.
+        include_charts: Include SheetData.charts in output.
+        include_tables: Include SheetData.table_candidates in output.
+        sheets_dir: Optional directory to write per-sheet files (in the chosen fmt).
+        stream: Optional default stream for stdout output when output_path is None.
+    """
+
+    fmt: Literal["json", "yaml", "yml", "toon"] = "json"
+    pretty: bool = False
+    indent: int | None = None
+    include_rows: bool = True
+    include_shapes: bool = True
+    include_charts: bool = True
+    include_tables: bool = True
+    sheets_dir: Path | None = None
+    stream: TextIO | None = None
+
+
+class ExStructEngine:
+    """
+    Configurable engine for ExStruct extraction and export.
+
+    Instances are immutable; override options per call if needed.
+
+    Key behaviors:
+        - Uses StructOptions for extraction defaults (mode, table_params).
+        - Uses OutputOptions for serialization defaults (fmt, pretty/indent, include* filters).
+        - Methods:
+            extract(path, mode=None) -> WorkbookData
+            serialize(workbook, fmt=None, pretty=None, indent=None) -> str
+            export(workbook, output_path=None, fmt=None, pretty=None, indent=None,
+                   sheets_dir=None, stream=None) -> None
+            process(file_path, output_path=None, out_fmt=None, image=False, pdf=False,
+                    dpi=72, mode=None, pretty=None, indent=None, sheets_dir=None,
+                    stream=None) -> None
+    """
+
+    def __init__(
+        self,
+        options: StructOptions | None = None,
+        output: OutputOptions | None = None,
+    ) -> None:
+        self.options = options or StructOptions()
+        self.output = output or OutputOptions()
+
+    @staticmethod
+    def from_defaults() -> "ExStructEngine":
+        """Factory to create an engine with default options."""
+        return ExStructEngine()
+
+    def _apply_table_params(self) -> None:
+        if self.options.table_params:
+            set_table_detection_params(**self.options.table_params)
+
+    @contextmanager
+    def _table_params_scope(self):
+        """
+        Temporarily apply table_params and restore previous global config afterward.
+        """
+        if not self.options.table_params:
+            yield
+            return
+        prev = dict(_cells._DETECTION_CONFIG)  # type: ignore[attr-defined]
+        set_table_detection_params(**self.options.table_params)
+        try:
+            yield
+        finally:
+            set_table_detection_params(**prev)
+
+    def _filter_sheet(self, sheet: SheetData) -> SheetData:
+        return SheetData(
+            rows=sheet.rows if self.output.include_rows else [],
+            shapes=sheet.shapes if self.output.include_shapes else [],
+            charts=sheet.charts if self.output.include_charts else [],
+            table_candidates=sheet.table_candidates if self.output.include_tables else [],
+        )
+
+    def _filter_workbook(self, wb: WorkbookData) -> WorkbookData:
+        filtered = {
+            name: self._filter_sheet(sheet)
+            for name, sheet in wb.sheets.items()
+        }
+        return WorkbookData(book_name=wb.book_name, sheets=filtered)
+
+    def extract(self, file_path: str | Path, *, mode: ExtractionMode | None = None) -> WorkbookData:
+        """Extract workbook semantic structure with the configured options."""
+        chosen_mode = mode or self.options.mode
+        if chosen_mode not in ("light", "standard", "verbose"):
+            raise ValueError(f"Unsupported mode: {chosen_mode}")
+        include_links = (
+            self.options.include_cell_links
+            if self.options.include_cell_links is not None
+            else chosen_mode == "verbose"
+        )
+        with self._table_params_scope():
+            return extract_workbook(Path(file_path), mode=chosen_mode, include_cell_links=include_links)
+
+    def serialize(
+        self,
+        data: WorkbookData,
+        *,
+        fmt: Optional[Literal["json", "yaml", "yml", "toon"]] = None,
+        pretty: Optional[bool] = None,
+        indent: int | None = None,
+    ) -> str:
+        """
+        Serialize WorkbookData using configured output defaults, applying include/exclude filters.
+        """
+        filtered = self._filter_workbook(data)
+        use_fmt = (fmt or self.output.fmt)
+        use_pretty = self.output.pretty if pretty is None else pretty
+        use_indent = self.output.indent if indent is None else indent
+        return serialize_workbook(filtered, fmt=use_fmt, pretty=use_pretty, indent=use_indent)
+
+    def export(
+        self,
+        data: WorkbookData,
+        output_path: Path | None = None,
+        *,
+        fmt: Optional[Literal["json", "yaml", "yml", "toon"]] = None,
+        pretty: Optional[bool] = None,
+        indent: int | None = None,
+        sheets_dir: Path | None = None,
+        stream: TextIO | None = None,
+    ) -> None:
+        """
+        Write WorkbookData to disk or stdout (when output_path is None).
+        Applies include/exclude filters before serialization.
+        """
+        text = self.serialize(data, fmt=fmt, pretty=pretty, indent=indent)
+        target_stream = stream or self.output.stream
+        chosen_fmt = (fmt or self.output.fmt)
+        chosen_sheets_dir = sheets_dir if sheets_dir is not None else self.output.sheets_dir
+
+        def _suffix_for(fmt_val: str) -> str:
+            if fmt_val in ("yaml", "yml"):
+                return ".yaml"
+            if fmt_val == "toon":
+                return ".toon"
+            if fmt_val == "json":
+                return ".json"
+            raise ValueError(f"Unsupported export format: {fmt_val}")
+
+        if output_path is not None:
+            output_path.write_text(text, encoding="utf-8")
+        else:
+            import sys
+
+            stream_target = target_stream or sys.stdout
+            stream_target.write(text)
+            if not text.endswith("\n"):
+                stream_target.write("\n")
+
+        if chosen_sheets_dir is not None:
+            filtered = self._filter_workbook(data)
+            save_sheets(
+                filtered,
+                chosen_sheets_dir,
+                fmt=chosen_fmt,
+                pretty=self.output.pretty if pretty is None else pretty,
+                indent=self.output.indent if indent is None else indent,
+            )
+
+        return None
+
+    def process(
+        self,
+        file_path: Path,
+        output_path: Path | None = None,
+        *,
+        out_fmt: Optional[str] = None,
+        image: bool = False,
+        pdf: bool = False,
+        dpi: int = 72,
+        mode: ExtractionMode | None = None,
+        pretty: bool | None = None,
+        indent: int | None = None,
+        sheets_dir: Path | None = None,
+        stream: TextIO | None = None,
+    ) -> None:
+        """
+        Convenience wrapper: extract, export (to file or stdout), and optionally render PDF/PNG.
+        """
+        wb = self.extract(file_path, mode=mode)
+        chosen_fmt = out_fmt or self.output.fmt
+        self.export(
+            wb,
+            output_path=output_path,
+            fmt=chosen_fmt,  # type: ignore[arg-type]
+            pretty=pretty,
+            indent=indent,
+            sheets_dir=sheets_dir,
+            stream=stream,
+        )
+
+        if pdf or image:
+            base_target = output_path or file_path.with_suffix(
+                ".yaml" if chosen_fmt in ("yaml", "yml") else ".toon" if chosen_fmt == "toon" else ".json"
+            )
+            pdf_path = base_target.with_suffix(".pdf")
+            export_pdf(file_path, pdf_path)
+            if image:
+                images_dir = pdf_path.parent / f"{pdf_path.stem}_images"
+                export_sheet_images(file_path, images_dir, dpi=dpi)

{exstruct-0.2.0 → exstruct-0.2.2}/src/exstruct/models/__init__.py

@@ -23,6 +23,7 @@ class Shape(BaseModel):
 class CellRow(BaseModel):
     r: int
     c: Dict[str, int | float | str]
+    links: Optional[Dict[str, str]] = None
 
 
 class ChartSeries(BaseModel):
@@ -163,9 +164,17 @@ class WorkbookData(BaseModel):
             case _:
                 raise ValueError(f"Unsupported export format: {fmt}")
         return dest
+
+    def __getitem__(self, sheet_name: str) -> SheetData:
+        """Return the SheetData for the given sheet name."""
+        return self.sheets[sheet_name]
+
+    def __iter__(self):
+        """Iterate over (sheet_name, SheetData) pairs in order."""
+        return iter(self.sheets.items())
     
     def __iter__(self):
         return iter(self.sheets.items())
     
     def __getitem__(self, sheet_name: str) -> SheetData:
-        return self.sheets[sheet_name]
+        return self.sheets[sheet_name]

{exstruct-0.2.0 → exstruct-0.2.2}/src/exstruct/render/__init__.py

@@ -54,12 +54,14 @@ def _require_pdfium():
         import pypdfium2 as pdfium  # type: ignore
     except ImportError as e:
         raise RuntimeError(
-            "Image rendering requires pypdfium2. Install it via `pip install pypdfium2` or add the 'render' extra."
+            "Image rendering requires pypdfium2. Install it via `pip install pypdfium2 pillow` or add the 'render' extra."
         ) from e
     return pdfium
 
 
-def export_sheet_images(excel_path: Path, output_dir: Path, dpi: int = 144) -> List[Path]:
+def export_sheet_images(
+    excel_path: Path, output_dir: Path, dpi: int = 144
+) -> List[Path]:
     """Export each sheet as PNG (via PDF then pypdfium2 rasterization) and return paths in sheet order."""
     pdfium = _require_pdfium()
     output_dir.mkdir(parents=True, exist_ok=True)
@@ -73,7 +75,7 @@ def export_sheet_images(excel_path: Path, output_dir: Path, dpi: int = 144) -> L
         with pdfium.PdfDocument(str(tmp_pdf)) as pdf:  # type: ignore
             for i, sheet_name in enumerate(sheet_names):
                 page = pdf[i]
-                bitmap = page.render(scale=scale) # type: ignore
+                bitmap = page.render(scale=scale)  # type: ignore
                 pil_image = bitmap.to_pil()  # type: ignore
                 safe_name = _sanitize_sheet_filename(sheet_name)
                 img_path = output_dir / f"{i+1:02d}_{safe_name}.png"