exstruct 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.0
+Version: 0.2.1
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -112,6 +112,16 @@ for name, sheet in wb:               # __iter__ yields (name, SheetData)
 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
 ```
 
 ## Table Detection Tuning

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

@@ -57,6 +57,16 @@ for name, sheet in wb:               # __iter__ yields (name, SheetData)
 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
 ```
 
 ## Table Detection Tuning

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

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.0"
+version = "0.2.1"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }

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

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

exstruct-0.2.1/src/exstruct/engine.py

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

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

@@ -163,9 +163,17 @@ class WorkbookData(BaseModel):
             case _:
                 raise ValueError(f"Unsupported export format: {fmt}")
         return dest
+
+    def __getitem__(self, sheet_name: str) -> SheetData:
+        """Return the SheetData for the given sheet name."""
+        return self.sheets[sheet_name]
+
+    def __iter__(self):
+        """Iterate over (sheet_name, SheetData) pairs in order."""
+        return iter(self.sheets.items())
     
     def __iter__(self):
         return iter(self.sheets.items())
     
     def __getitem__(self, sheet_name: str) -> SheetData:
-        return self.sheets[sheet_name]
+        return self.sheets[sheet_name]