exstruct 0.2.1__tar.gz → 0.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.1
+Version: 0.2.3
 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 (cells, table candidates, shapes, charts, print areas/views, 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.
 
 ## 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).
+- **Excel → Structured JSON**: cells, shapes, charts, table candidates, and print areas/views per sheet.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks. Size output is flag-controlled.
 - **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,67 @@ 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`.
+
+## 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 --print-areas-dir areas/  # split per print area (if any)
+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)
-
-# ExStructEngine: per-instance options for extraction/output
-from exstruct import ExStructEngine, StructOptions, OutputOptions
-
-engine = ExStructEngine(
-    options=StructOptions(mode="standard"),
-    output=OutputOptions(include_shapes=False, pretty=True),
-)
-wb2 = engine.extract("input.xlsx")
-engine.export(wb2, Path("out_filtered.json"))  # drops shapes via OutputOptions
-```
+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
+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="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")
+
+# Export per print area (if print areas exist)
+from exstruct import export_print_areas_as
+export_print_areas_as(wb, "areas", fmt="json", pretty=True)
+```
+
+**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
 
@@ -142,8 +161,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.
-- **verbose**: all shapes (with width/height), charts, table candidates.
+- **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 +189,9 @@ 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`
+Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -357,6 +378,12 @@ In short, **exstruct = “an engine that converts Excel into a format AI can und
 - Default JSON is compact to reduce tokens; use `--pretty` or `pretty=True` when readability matters.
 - Field `table_candidates` replaces `tables`; adjust downstream consumers accordingly.
 
+## Print Areas (PrintArea / PrintAreaView)
+
+- `SheetData.print_areas` holds print areas (cell coordinates) in light/standard/verbose.
+- Use `export_print_areas_as(...)` or CLI `--print-areas-dir` to write one file per print area (nothing is written if none exist).
+- `PrintAreaView` includes rows and table candidates inside the area, plus shapes/charts that overlap the area (size-less shapes are treated as points). `normalize=True` rebases row/col indices to the area origin.
+
 ## License
 
 BSD-3-Clause. See `LICENSE` for details.

{exstruct-0.2.1 → exstruct-0.2.3}/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 (cells, table candidates, shapes, charts, print areas/views, 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.
 
 ## 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).
+- **Excel → Structured JSON**: cells, shapes, charts, table candidates, and print areas/views per sheet.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks. Size output is flag-controlled.
 - **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,67 @@ Optional extras:
 
 - YAML: `pip install pyyaml`
 - TOON: `pip install python-toon`
-- Rendering (PDF/PNG): Excel + `pip install pypdfium2`
-
-## 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)
-```
+- Rendering (PDF/PNG): Excel + `pip install pypdfium2 pillow`
+- All extras at once: `pip install exstruct[yaml,toon,render]`
+
+Platform note:
+
+- Full extraction (shapes/charts) targets Windows + Excel (COM via xlwings). On other platforms, use `mode=light` to get cells + `table_candidates`.
+
+## 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 --print-areas-dir areas/  # split per print area (if any)
+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)
-
-# ExStructEngine: per-instance options for extraction/output
-from exstruct import ExStructEngine, StructOptions, OutputOptions
-
-engine = ExStructEngine(
-    options=StructOptions(mode="standard"),
-    output=OutputOptions(include_shapes=False, pretty=True),
-)
-wb2 = engine.extract("input.xlsx")
-engine.export(wb2, Path("out_filtered.json"))  # drops shapes via OutputOptions
-```
+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
+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="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")
+
+# Export per print area (if print areas exist)
+from exstruct import export_print_areas_as
+export_print_areas_as(wb, "areas", fmt="json", pretty=True)
+```
+
+**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
 
@@ -87,8 +105,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.
-- **verbose**: all shapes (with width/height), charts, table candidates.
+- **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 +133,9 @@ 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`
+Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -302,6 +322,12 @@ In short, **exstruct = “an engine that converts Excel into a format AI can und
 - Default JSON is compact to reduce tokens; use `--pretty` or `pretty=True` when readability matters.
 - Field `table_candidates` replaces `tables`; adjust downstream consumers accordingly.
 
+## Print Areas (PrintArea / PrintAreaView)
+
+- `SheetData.print_areas` holds print areas (cell coordinates) in light/standard/verbose.
+- Use `export_print_areas_as(...)` or CLI `--print-areas-dir` to write one file per print area (nothing is written if none exist).
+- `PrintAreaView` includes rows and table candidates inside the area, plus shapes/charts that overlap the area (size-less shapes are treated as points). `normalize=True` rebases row/col indices to the area origin.
+
 ## License
 
 BSD-3-Clause. See `LICENSE` for details.

{exstruct-0.2.1 → exstruct-0.2.3}/pyproject.toml

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

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional, TextIO
+
+from .core.cells import set_table_detection_params
+from .core.integrate import extract_workbook
+from .engine import ExStructEngine, OutputOptions, StructOptions
+from .io import (
+    save_as_json,
+    save_as_toon,
+    save_as_yaml,
+    save_print_area_views,
+    save_sheets,
+    serialize_workbook,
+)
+from .models import (
+    CellRow,
+    Chart,
+    ChartSeries,
+    PrintArea,
+    PrintAreaView,
+    Shape,
+    SheetData,
+    WorkbookData,
+)
+from .render import export_pdf, export_sheet_images
+
+__all__ = [
+    "extract",
+    "export",
+    "export_sheets",
+    "export_sheets_as",
+    "export_print_areas_as",
+    "export_pdf",
+    "export_sheet_images",
+    "process_excel",
+    "ExtractionMode",
+    "CellRow",
+    "Shape",
+    "ChartSeries",
+    "Chart",
+    "SheetData",
+    "WorkbookData",
+    "PrintArea",
+    "PrintAreaView",
+    "set_table_detection_params",
+    "ExStructEngine",
+    "StructOptions",
+    "OutputOptions",
+]
+
+
+ExtractionMode = Literal["light", "standard", "verbose"]
+
+
+def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> WorkbookData:
+    """
+    Extract an Excel workbook into WorkbookData.
+
+    Args:
+        file_path: Path to .xlsx/.xlsm/.xls.
+        mode: "light" / "standard" / "verbose"
+            - light: cells + table detection only (no COM, shapes/charts empty). Print areas via openpyxl.
+            - standard: texted shapes + arrows + charts (COM if available), print areas included. Shape/chart size is kept but hidden by default in output.
+            - verbose: all shapes (including textless) with size, charts with size.
+    """
+    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(
+    data: WorkbookData,
+    path: str | Path,
+    fmt: Optional[Literal["json", "yaml", "yml", "toon"]] = None,
+    *,
+    pretty: bool = False,
+    indent: int | None = None,
+) -> None:
+    """
+    Save WorkbookData to a file (format inferred from extension).
+
+    Args:
+        data: WorkbookData from `extract` or similar
+        path: destination path; extension is used to infer format
+        fmt: explicitly set format if desired (json/yaml/yml/toon)
+        pretty: pretty-print JSON
+        indent: JSON indent width (defaults to 2 when pretty=True and indent is None)
+    """
+    dest = Path(path)
+    format_hint = (fmt or dest.suffix.lstrip(".") or "json").lower()
+    match format_hint:
+        case "json":
+            save_as_json(data, dest, pretty=pretty, indent=indent)
+        case "yaml" | "yml":
+            save_as_yaml(data, dest)
+        case "toon":
+            save_as_toon(data, dest)
+        case _:
+            raise ValueError(f"Unsupported export format: {format_hint}")
+
+
+def export_sheets(data: WorkbookData, dir_path: str | Path) -> dict[str, Path]:
+    """
+    Export each sheet as an individual JSON file.
+
+    - Payload: {book_name, sheet_name, sheet: SheetData}
+    - Returns: {sheet_name: Path}
+    """
+    return save_sheets(data, Path(dir_path), fmt="json")
+
+
+def export_sheets_as(
+    data: WorkbookData,
+    dir_path: str | Path,
+    fmt: Literal["json", "yaml", "yml", "toon"] = "json",
+    *,
+    pretty: bool = False,
+    indent: int | None = None,
+) -> dict[str, Path]:
+    """Export each sheet in the given format (json/yaml/toon); returns sheet name to path map."""
+    return save_sheets(data, Path(dir_path), fmt=fmt, pretty=pretty, indent=indent)
+
+
+def export_print_areas_as(
+    data: WorkbookData,
+    dir_path: str | Path,
+    fmt: Literal["json", "yaml", "yml", "toon"] = "json",
+    *,
+    pretty: bool = False,
+    indent: int | None = None,
+    normalize: bool = False,
+) -> dict[str, Path]:
+    """
+    Export each print area as a PrintAreaView.
+
+    Args:
+        data: WorkbookData that contains print areas
+        dir_path: output directory
+        fmt: json/yaml/yml/toon
+        pretty/indent: JSON formatting options
+        normalize: rebase row/col indices to the print-area origin when True
+    Returns:
+        dict mapping area key to path (e.g., "Sheet1#1": /.../Sheet1_area1_...json)
+    """
+    return save_print_area_views(
+        data,
+        Path(dir_path),
+        fmt=fmt,
+        pretty=pretty,
+        indent=indent,
+        normalize=normalize,
+    )
+
+
+def process_excel(
+    file_path: Path,
+    output_path: Path | None = None,
+    out_fmt: str = "json",
+    image: bool = False,
+    pdf: bool = False,
+    dpi: int = 72,
+    mode: ExtractionMode = "standard",
+    pretty: bool = False,
+    indent: int | None = None,
+    sheets_dir: Path | None = None,
+    print_areas_dir: Path | None = None,
+    stream: TextIO | None = None,
+) -> None:
+    """
+    Convenience wrapper: extract → serialize (file or stdout) → optional PDF/PNG.
+
+    Args:
+        file_path: input Excel
+        output_path: None for stdout; otherwise, write to file
+        out_fmt: json/yaml/yml/toon
+        image/pdf: True to also output PNG/PDF (requires Excel + pypdfium2)
+        dpi: DPI for image output
+        mode: light/standard/verbose (same meaning as `extract`)
+        pretty/indent: JSON formatting
+        sheets_dir: directory to write per-sheet files
+        print_areas_dir: directory to write per-print-area files
+        stream: IO override when output_path is None
+    """
+    engine = ExStructEngine(
+        options=StructOptions(mode=mode),
+        output=OutputOptions(
+            fmt=out_fmt,
+            pretty=pretty,
+            indent=indent,
+            sheets_dir=sheets_dir,
+            print_areas_dir=print_areas_dir,
+            include_print_areas=None if mode == "light" else True,
+            include_shape_size=True if mode == "verbose" else False,
+            include_chart_size=True if mode == "verbose" else False,
+            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,
+        print_areas_dir=print_areas_dir,
+        stream=stream,
+    )

{exstruct-0.2.1 → exstruct-0.2.3}/src/exstruct/cli/main.py

@@ -57,6 +57,11 @@ def build_parser() -> argparse.ArgumentParser:
         type=Path,
         help="Optional directory to write one file per sheet (format follows --format).",
     )
+    parser.add_argument(
+        "--print-areas-dir",
+        type=Path,
+        help="Optional directory to write one file per print area (format follows --format).",
+    )
     return parser
 
 
@@ -80,6 +85,7 @@ def main(argv: list[str] | None = None) -> int:
             mode=args.mode,
             pretty=args.pretty,
             sheets_dir=args.sheets_dir,
+            print_areas_dir=args.print_areas_dir,
         )
         return 0
     except Exception as e: