exstruct 0.2.21__tar.gz → 0.2.60__tar.gz

{exstruct-0.2.21 → exstruct-0.2.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.21
+Version: 0.2.60
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -60,12 +60,15 @@ Description-Content-Type: text/markdown
 
 ![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.
+ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
+
+[日本版README](README.ja.md)
 
 ## Features
 
-- **Excel → Structured JSON**: cells, shapes, charts, and table candidates per sheet.
-- **Output modes**: `light` (cells + table candidates only), `standard` (texted shapes + arrows, charts), `verbose` (all shapes with width/height). Verbose also emits cell hyperlinks.
+- **Excel → Structured JSON**: cells, shapes, charts, table candidates, print areas/views, and auto page-break areas per sheet.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks. Size output is flag-controlled.
+- **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested.
 - **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.
@@ -85,7 +88,8 @@ Optional extras:
 - 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` safely.
+
+- Full extraction (shapes/charts) targets Windows + Excel (COM via xlwings). On other platforms, use `mode=light` to get cells + `table_candidates`.
 
 ## Quick Start (CLI)
 
@@ -95,10 +99,13 @@ 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)
 ```
 
+Auto page-break exports are API-only (Excel/COM): set `DestinationOptions.auto_page_breaks_dir` or call `export_auto_page_breaks(...)`.
+
 ## Quick Start (Python)
 
 ```python
@@ -112,7 +119,7 @@ set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
 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
+# 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))
@@ -120,19 +127,45 @@ 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")
+# ExStructEngine: per-instance options (nested configs)
+from exstruct import (
+    DestinationOptions,
+    ExStructEngine,
+    FilterOptions,
+    FormatOptions,
+    OutputOptions,
+    StructOptions,
+    export_auto_page_breaks,
+)
+
+engine = ExStructEngine(
+    options=StructOptions(mode="verbose"),  # verbose includes hyperlinks by default
+    output=OutputOptions(
+        format=FormatOptions(pretty=True),
+        filters=FilterOptions(include_shapes=False),  # drop shapes in output
+        destinations=DestinationOptions(sheets_dir=Path("out_sheets")),  # also write per-sheet files
+    ),
+)
+wb2 = engine.extract("input.xlsx")
+engine.export(wb2, Path("out_filtered.json"))  # drops shapes via filters
+
+# 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)
+
+# Auto page-break extraction/output (COM only; raises if no auto breaks exist)
+engine_auto = ExStructEngine(
+    output=OutputOptions(
+        destinations=DestinationOptions(auto_page_breaks_dir=Path("auto_areas"))
+    )
+)
+wb_auto = engine_auto.extract("input.xlsx")  # includes SheetData.auto_print_areas
+engine_auto.export(wb_auto, Path("out_with_auto.json"))  # also writes auto_areas/*
+export_auto_page_breaks(wb_auto, "auto_areas", fmt="json", pretty=True)  # manual writer
 ```
 
 **Note (non-COM environments):** If Excel COM is unavailable, extraction still runs and returns cells + `table_candidates`; `shapes`/`charts` will be empty.
@@ -152,11 +185,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. Hyperlinks are off unless `include_cell_links=True`.
-- **verbose**: all shapes (with width/height), charts, table candidates, and cell hyperlinks.
+## 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
 
@@ -185,6 +218,7 @@ To show how well exstruct can structure Excel, we parse a workbook that combines
 (Screenshot below is the actual sample Excel sheet)
 ![Sample Excel](/docs/assets/demo_sheet.png)
 Sample workbook: `sample/sample.xlsx`
+Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -371,6 +405,14 @@ 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 and Auto Page Breaks (PrintArea / PrintAreaView)
+
+- `SheetData.print_areas` holds print areas (cell coordinates) in light/standard/verbose.
+- `SheetData.auto_print_areas` holds Excel COM-computed auto page-break areas when auto page-break extraction is enabled (COM only).
+- Use `export_print_areas_as(...)` or CLI `--print-areas-dir` to write one file per print area (nothing is written if none exist).
+- Use `DestinationOptions.auto_page_breaks_dir` (preferred) or `export_auto_page_breaks(...)` to write per-auto-page-break files; the API raises `ValueError` if no auto page breaks 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.
@@ -378,18 +420,3 @@ 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.21 → exstruct-0.2.60}/README.md

@@ -4,12 +4,15 @@
 
 ![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.
+ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
+
+[日本版README](README.ja.md)
 
 ## Features
 
-- **Excel → Structured JSON**: cells, shapes, charts, and table candidates per sheet.
-- **Output modes**: `light` (cells + table candidates only), `standard` (texted shapes + arrows, charts), `verbose` (all shapes with width/height). Verbose also emits cell hyperlinks.
+- **Excel → Structured JSON**: cells, shapes, charts, table candidates, print areas/views, and auto page-break areas per sheet.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks. Size output is flag-controlled.
+- **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested.
 - **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.
@@ -29,7 +32,8 @@ Optional extras:
 - 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` safely.
+
+- Full extraction (shapes/charts) targets Windows + Excel (COM via xlwings). On other platforms, use `mode=light` to get cells + `table_candidates`.
 
 ## Quick Start (CLI)
 
@@ -39,10 +43,13 @@ 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)
 ```
 
+Auto page-break exports are API-only (Excel/COM): set `DestinationOptions.auto_page_breaks_dir` or call `export_auto_page_breaks(...)`.
+
 ## Quick Start (Python)
 
 ```python
@@ -56,7 +63,7 @@ set_table_detection_params(table_score_threshold=0.3, density_min=0.04)
 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
+# 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))
@@ -64,19 +71,45 @@ 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")
+# ExStructEngine: per-instance options (nested configs)
+from exstruct import (
+    DestinationOptions,
+    ExStructEngine,
+    FilterOptions,
+    FormatOptions,
+    OutputOptions,
+    StructOptions,
+    export_auto_page_breaks,
+)
+
+engine = ExStructEngine(
+    options=StructOptions(mode="verbose"),  # verbose includes hyperlinks by default
+    output=OutputOptions(
+        format=FormatOptions(pretty=True),
+        filters=FilterOptions(include_shapes=False),  # drop shapes in output
+        destinations=DestinationOptions(sheets_dir=Path("out_sheets")),  # also write per-sheet files
+    ),
+)
+wb2 = engine.extract("input.xlsx")
+engine.export(wb2, Path("out_filtered.json"))  # drops shapes via filters
+
+# 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)
+
+# Auto page-break extraction/output (COM only; raises if no auto breaks exist)
+engine_auto = ExStructEngine(
+    output=OutputOptions(
+        destinations=DestinationOptions(auto_page_breaks_dir=Path("auto_areas"))
+    )
+)
+wb_auto = engine_auto.extract("input.xlsx")  # includes SheetData.auto_print_areas
+engine_auto.export(wb_auto, Path("out_with_auto.json"))  # also writes auto_areas/*
+export_auto_page_breaks(wb_auto, "auto_areas", fmt="json", pretty=True)  # manual writer
 ```
 
 **Note (non-COM environments):** If Excel COM is unavailable, extraction still runs and returns cells + `table_candidates`; `shapes`/`charts` will be empty.
@@ -96,11 +129,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. Hyperlinks are off unless `include_cell_links=True`.
-- **verbose**: all shapes (with width/height), charts, table candidates, and cell hyperlinks.
+## 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
 
@@ -129,6 +162,7 @@ To show how well exstruct can structure Excel, we parse a workbook that combines
 (Screenshot below is the actual sample Excel sheet)
 ![Sample Excel](/docs/assets/demo_sheet.png)
 Sample workbook: `sample/sample.xlsx`
+Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -315,6 +349,14 @@ 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 and Auto Page Breaks (PrintArea / PrintAreaView)
+
+- `SheetData.print_areas` holds print areas (cell coordinates) in light/standard/verbose.
+- `SheetData.auto_print_areas` holds Excel COM-computed auto page-break areas when auto page-break extraction is enabled (COM only).
+- Use `export_print_areas_as(...)` or CLI `--print-areas-dir` to write one file per print area (nothing is written if none exist).
+- Use `DestinationOptions.auto_page_breaks_dir` (preferred) or `export_auto_page_breaks(...)` to write per-auto-page-break files; the API raises `ValueError` if no auto page breaks 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.
@@ -322,18 +364,3 @@ 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.60/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "exstruct"
+version = "0.2.60"
+description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
+readme = "README.md"
+license = { file = "LICENSE" }
+keywords = ["excel", "structure", "data", "exstruct"]
+authors = [
+    { name = "harumiWeb", email = "ganaharumi@outlook.jp" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=2.3.5",
+    "openpyxl>=3.1.5",
+    "pandas>=2.3.3",
+    "pydantic>=2.12.5",
+    "scipy>=1.16.3",
+    "xlwings>=0.33.16",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.7.0",
+    "mypy>=1.19.0",
+    "pre-commit>=4.5.0",
+    "pytest>=9.0.1",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.14.8",
+]
+
+[project.optional-dependencies]
+yaml = ["pyyaml>=6.0.3"]
+toon = ["python-toon>=0.1.3"]
+render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
+
+[project.scripts]
+exstruct = "exstruct.cli.main:main"
+
+[project.urls]
+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/*",
+]
+
+[tool.ruff]
+target-version = "py311"
+src = ["exstruct"]
+
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # import sorting
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "N",   # naming
+    "C90", # complexity
+    "A",   # flake8-builtins
+    "ANN", # type annotations
+]
+
+ignore = [
+    "E501",   # 行長は許容（Excel JSON は長くなりがち）
+    "B008",   # Pydantic の default_factory を誤検知するため
+    "ANN101", # self に型を要求されてしまうため
+    "ANN102", # cls も同様
+]
+
+fix = true
+
+# 型ヒントのスタイル
+[tool.ruff.lint]
+extend-select = ["ANN"]
+
+# import の並び替え設定
+[tool.ruff.isort]
+combine-as-imports = true
+known-first-party = ["exstruct"]
+force-sort-within-sections = true
+
+# 複雑度チェック（関数の最大複雑度）
+[tool.ruff.mccabe]
+max-complexity = 12
+
+[tool.ruff.per-file-ignores]
+"tests/**/*.py" = ["N802", "N803", "N806"]
+
+
+[tool.mypy]
+packages = ["exstruct"]
+python_version = "3.11"
+
+# 外部ライブラリは一切チェックしない
+ignore_missing_imports = true
+
+# 自作コードは厳密にチェックする
+strict = true
+
+# Pydantic v2 向け
+plugins = ["pydantic.mypy"]