exstruct 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.1
+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,51 +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)
-
-# 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)
-
+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
 
 engine = ExStructEngine(
-    options=StructOptions(mode="standard"),
+    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
-```
+
+# 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
 
@@ -139,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
 
@@ -170,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
 
@@ -364,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.1 → 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,51 +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)
-
-# 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)
-
+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
 
 engine = ExStructEngine(
-    options=StructOptions(mode="standard"),
+    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
-```
+
+# 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
 
@@ -84,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
 
@@ -115,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
 
@@ -309,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.1 → exstruct-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.1"
+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.1 → exstruct-0.2.2}/src/exstruct/__init__.py

@@ -36,7 +36,8 @@ ExtractionMode = Literal["light", "standard", "verbose"]
 
 def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> WorkbookData:
     """Extract workbook semantic structure and return WorkbookData."""
-    engine = ExStructEngine(options=StructOptions(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)
 
 

{exstruct-0.2.1 → 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.1 → 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.1 → exstruct-0.2.2}/src/exstruct/engine.py

@@ -3,8 +3,10 @@ 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
@@ -30,6 +32,7 @@ class StructOptions:
 
     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)
@@ -96,6 +99,21 @@ class ExStructEngine:
         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 [],
@@ -116,8 +134,13 @@ class ExStructEngine:
         chosen_mode = mode or self.options.mode
         if chosen_mode not in ("light", "standard", "verbose"):
             raise ValueError(f"Unsupported mode: {chosen_mode}")
-        self._apply_table_params()
-        return extract_workbook(Path(file_path), 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,

{exstruct-0.2.1 → 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):

{exstruct-0.2.1 → 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"