exstruct 0.2.51__tar.gz → 0.2.60__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.51
+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 (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.
+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, table candidates, and print areas/views per sheet.
+- **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.
@@ -101,6 +104,8 @@ 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
@@ -122,27 +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 (nested configs)
-from exstruct import ExStructEngine, StructOptions, OutputOptions, FormatOptions, FilterOptions, DestinationOptions
-
-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")
+# 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.
@@ -382,10 +405,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)
+## 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

{exstruct-0.2.51 → exstruct-0.2.60}/README.md

@@ -4,12 +4,15 @@
 
 ![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.
+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, table candidates, and print areas/views per sheet.
+- **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.
@@ -45,6 +48,8 @@ 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
@@ -66,27 +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 (nested configs)
-from exstruct import ExStructEngine, StructOptions, OutputOptions, FormatOptions, FilterOptions, DestinationOptions
-
-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")
+# 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.
@@ -326,10 +349,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)
+## 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

{exstruct-0.2.51 → exstruct-0.2.60}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.51"
+version = "0.2.60"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -26,6 +26,7 @@ build-backend = "uv_build"
 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",

{exstruct-0.2.51 → exstruct-0.2.60}/src/exstruct/__init__.py

@@ -5,11 +5,18 @@ from typing import Literal, TextIO
 
 from .core.cells import set_table_detection_params
 from .core.integrate import extract_workbook
-from .engine import ExStructEngine, OutputOptions, StructOptions
+from .engine import (
+    DestinationOptions,
+    ExStructEngine,
+    FilterOptions,
+    OutputOptions,
+    StructOptions,
+)
 from .io import (
     save_as_json,
     save_as_toon,
     save_as_yaml,
+    save_auto_page_break_views,
     save_print_area_views,
     save_sheets,
     serialize_workbook,
@@ -32,6 +39,7 @@ __all__ = [
     "export_sheets",
     "export_sheets_as",
     "export_print_areas_as",
+    "export_auto_page_breaks",
     "export_pdf",
     "export_sheet_images",
     "process_excel",
@@ -49,7 +57,10 @@ __all__ = [
     "ExStructEngine",
     "StructOptions",
     "OutputOptions",
+    "FilterOptions",
+    "DestinationOptions",
     "serialize_workbook",
+    "export_auto_page_breaks",
 ]
 
 
@@ -158,6 +169,39 @@ def export_print_areas_as(
     )
 
 
+def export_auto_page_breaks(
+    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 auto page-break areas (COM-computed) as PrintAreaView files.
+
+    Args:
+        data: WorkbookData containing auto_print_areas (COM extraction with auto breaks enabled)
+        dir_path: output directory
+        fmt: json/yaml/yml/toon
+        pretty/indent: JSON formatting options
+        normalize: rebase row/col indices to the area origin when True
+    """
+    if not any(sheet.auto_print_areas for sheet in data.sheets.values()):
+        raise ValueError(
+            "No auto page-break areas found. Enable COM-based auto page breaks before exporting."
+        )
+    return save_auto_page_break_views(
+        data,
+        Path(dir_path),
+        fmt=fmt,
+        pretty=pretty,
+        indent=indent,
+        normalize=normalize,
+    )
+
+
 def process_excel(
     file_path: Path,
     output_path: Path | None = None,
@@ -170,6 +214,7 @@ def process_excel(
     indent: int | None = None,
     sheets_dir: Path | None = None,
     print_areas_dir: Path | None = None,
+    auto_page_breaks_dir: Path | None = None,
     stream: TextIO | None = None,
 ) -> None:
     """
@@ -185,6 +230,7 @@ def process_excel(
         pretty/indent: JSON formatting
         sheets_dir: directory to write per-sheet files
         print_areas_dir: directory to write per-print-area files
+        auto_page_breaks_dir: directory to write per-auto-page-break files (COM only)
         stream: IO override when output_path is None
     """
     engine = ExStructEngine(
@@ -195,6 +241,7 @@ def process_excel(
             indent=indent,
             sheets_dir=sheets_dir,
             print_areas_dir=print_areas_dir,
+            auto_page_breaks_dir=auto_page_breaks_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,
@@ -213,5 +260,6 @@ def process_excel(
         indent=indent,
         sheets_dir=sheets_dir,
         print_areas_dir=print_areas_dir,
+        auto_page_breaks_dir=auto_page_breaks_dir,
         stream=stream,
     )