exstruct 0.2.61__tar.gz → 0.2.62__tar.gz

{exstruct-0.2.61 → exstruct-0.2.62}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.61
+Version: 0.2.62
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -55,7 +55,7 @@ Description-Content-Type: text/markdown
 
 # ExStruct — Excel Structured Extraction Engine
 
-[![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)
+[![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) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 
 ![ExStruct Image](/docs/assets/icon.webp)
 

{exstruct-0.2.61 → exstruct-0.2.62}/README.md

@@ -1,6 +1,6 @@
 # ExStruct — Excel Structured Extraction Engine
 
-[![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)
+[![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) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 
 ![ExStruct Image](/docs/assets/icon.webp)
 

{exstruct-0.2.61 → exstruct-0.2.62}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.61"
+version = "0.2.62"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -25,6 +25,7 @@ build-backend = "uv_build"
 [dependency-groups]
 dev = [
     "mkdocs-material>=9.7.0",
+    "mkdocstrings-python>=2.0.1",
     "mypy>=1.19.0",
     "pre-commit>=4.5.0",
     "pytest>=9.0.1",

{exstruct-0.2.61 → exstruct-0.2.62}/src/exstruct/__init__.py

@@ -94,6 +94,20 @@ def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> Workboo
             - 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.
+
+    Returns:
+        WorkbookData containing sheets, rows, shapes, charts, and print areas.
+
+    Raises:
+        ValueError: If an invalid mode is provided.
+
+    Examples:
+        Extract with hyperlinks (verbose) and inspect table candidates:
+
+        >>> from exstruct import extract
+        >>> wb = extract("input.xlsx", mode="verbose")
+        >>> wb.sheets["Sheet1"].table_candidates
+        ['A1:B5']
     """
     include_links = True if mode == "verbose" else False
     engine = ExStructEngine(
@@ -119,6 +133,17 @@ def export(
         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)
+
+    Raises:
+        ValueError: If the format is unsupported.
+
+    Examples:
+        Write pretty JSON and YAML (requires pyyaml):
+
+        >>> from exstruct import export, extract
+        >>> wb = extract("input.xlsx")
+        >>> export(wb, "out.json", pretty=True)
+        >>> export(wb, "out.yaml", fmt="yaml")  # doctest: +SKIP
     """
     dest = Path(path)
     format_hint = (fmt or dest.suffix.lstrip(".") or "json").lower()
@@ -139,6 +164,20 @@ def export_sheets(data: WorkbookData, dir_path: str | Path) -> dict[str, Path]:
 
     - Payload: {book_name, sheet_name, sheet: SheetData}
     - Returns: {sheet_name: Path}
+
+    Args:
+        data: WorkbookData to split by sheet.
+        dir_path: Output directory.
+
+    Returns:
+        Mapping from sheet name to written JSON path.
+
+    Examples:
+        >>> from exstruct import export_sheets, extract
+        >>> wb = extract("input.xlsx")
+        >>> paths = export_sheets(wb, "out_sheets")
+        >>> "Sheet1" in paths
+        True
     """
     return save_sheets(data, Path(dir_path), fmt="json")
 
@@ -151,7 +190,29 @@ def export_sheets_as(
     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."""
+    """
+    Export each sheet in the given format (json/yaml/toon); returns sheet name to path map.
+
+    Args:
+        data: WorkbookData to split by sheet.
+        dir_path: Output directory.
+        fmt: Output format; inferred defaults to json.
+        pretty: Pretty-print JSON.
+        indent: JSON indent width (defaults to 2 when pretty=True and indent is None).
+
+    Returns:
+        Mapping from sheet name to written file path.
+
+    Raises:
+        ValueError: If an unsupported format is passed.
+
+    Examples:
+        Export per sheet as YAML (requires pyyaml):
+
+        >>> from exstruct import export_sheets_as, extract
+        >>> wb = extract("input.xlsx")
+        >>> _ = export_sheets_as(wb, "out_yaml", fmt="yaml")  # doctest: +SKIP
+    """
     return save_sheets(data, Path(dir_path), fmt=fmt, pretty=pretty, indent=indent)
 
 
@@ -171,10 +232,21 @@ def export_print_areas_as(
         data: WorkbookData that contains print areas
         dir_path: output directory
         fmt: json/yaml/yml/toon
-        pretty/indent: JSON formatting options
+        pretty: Pretty-print JSON output.
+        indent: JSON indent width (defaults to 2 when pretty is True and indent is None).
         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)
+
+    Examples:
+        Export print areas when present:
+
+        >>> from exstruct import export_print_areas_as, extract
+        >>> wb = extract("input.xlsx", mode="standard")
+        >>> paths = export_print_areas_as(wb, "areas")
+        >>> isinstance(paths, dict)
+        True
     """
     return save_print_area_views(
         data,
@@ -202,8 +274,23 @@ def export_auto_page_breaks(
         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
+        pretty: Pretty-print JSON output.
+        indent: JSON indent width (defaults to 2 when pretty is True and indent is None).
         normalize: rebase row/col indices to the area origin when True
+
+    Returns:
+        dict mapping area key to path (e.g., "Sheet1#1": /.../Sheet1_auto_page1_...json)
+
+    Raises:
+        PrintAreaError: If no auto page-break areas are present.
+
+    Examples:
+        >>> from exstruct import export_auto_page_breaks, extract
+        >>> wb = extract("input.xlsx", mode="standard")
+        >>> try:
+        ...     export_auto_page_breaks(wb, "auto_areas")
+        ... except PrintAreaError:
+        ...     pass
     """
     if not any(sheet.auto_print_areas for sheet in data.sheets.values()):
         message = "No auto page-break areas found. Enable COM-based auto page breaks before exporting."
@@ -220,8 +307,8 @@ def export_auto_page_breaks(
 
 
 def process_excel(
-    file_path: Path,
-    output_path: Path | None = None,
+    file_path: str | Path,
+    output_path: str | Path | None = None,
     out_fmt: str = "json",
     image: bool = False,
     pdf: bool = False,
@@ -229,26 +316,44 @@ def process_excel(
     mode: ExtractionMode = "standard",
     pretty: bool = False,
     indent: int | None = None,
-    sheets_dir: Path | None = None,
-    print_areas_dir: Path | None = None,
-    auto_page_breaks_dir: Path | None = None,
+    sheets_dir: str | Path | None = None,
+    print_areas_dir: str | Path | None = None,
+    auto_page_breaks_dir: str | Path | None = None,
     stream: TextIO | None = None,
 ) -> None:
     """
-    Convenience wrapper: extract → serialize (file or stdout) → optional PDF/PNG.
+    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
-        auto_page_breaks_dir: directory to write per-auto-page-break files (COM only)
-        stream: IO override when output_path is None
+        file_path: Input Excel workbook (path string or Path).
+        output_path: None for stdout; otherwise, write to file (string or Path).
+        out_fmt: json/yaml/yml/toon.
+        image: True to also output PNGs (requires Excel + COM + pypdfium2).
+        pdf: True to also output PDF (requires Excel + COM + pypdfium2).
+        dpi: DPI for image output.
+        mode: light/standard/verbose (same meaning as `extract`).
+        pretty: Pretty-print JSON.
+        indent: JSON indent width.
+        sheets_dir: Directory to write per-sheet files (string or Path).
+        print_areas_dir: Directory to write per-print-area files (string or Path).
+        auto_page_breaks_dir: Directory to write per-auto-page-break files (COM only).
+        stream: IO override when output_path is None.
+
+    Raises:
+        ValueError: If an unsupported format or mode is given.
+        PrintAreaError: When exporting auto page breaks without available data.
+        RenderError: When rendering fails (Excel/COM/pypdfium2 issues).
+
+    Examples:
+        Extract and write JSON to stdout, plus per-sheet files:
+
+        >>> from pathlib import Path
+        >>> from exstruct import process_excel
+        >>> process_excel(Path("input.xlsx"), output_path=None, sheets_dir=Path("sheets"))
+
+        Render PDF only (COM + Excel required):
+
+        >>> process_excel(Path("input.xlsx"), output_path=Path("out.json"), pdf=True)  # doctest: +SKIP
     """
     engine = ExStructEngine(
         options=StructOptions(mode=mode),

{exstruct-0.2.61 → exstruct-0.2.62}/src/exstruct/cli/main.py

@@ -1,97 +1,97 @@
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from exstruct import process_excel
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        description="Dev-only CLI stub for ExStruct extraction."
-    )
-    parser.add_argument("input", type=Path, help="Excel file (.xlsx/.xlsm/.xls)")
-    parser.add_argument(
-        "-o",
-        "--output",
-        type=Path,
-        help="Output path. If omitted, writes to stdout.",
-    )
-    parser.add_argument(
-        "-f",
-        "--format",
-        default="json",
-        choices=["json", "yaml", "yml", "toon"],
-        help="Export format",
-    )
-    parser.add_argument(
-        "--image",
-        action="store_true",
-        help="(placeholder) Render PNG alongside JSON",
-    )
-    parser.add_argument(
-        "--pdf",
-        action="store_true",
-        help="(placeholder) Render PDF alongside JSON",
-    )
-    parser.add_argument(
-        "--dpi",
-        type=int,
-        default=144,
-        help="DPI for image rendering (placeholder)",
-    )
-    parser.add_argument(
-        "-m",
-        "--mode",
-        default="standard",
-        choices=["light", "standard", "verbose"],
-        help="Extraction detail level",
-    )
-    parser.add_argument(
-        "--pretty",
-        action="store_true",
-        help="Pretty-print JSON output (indent=2). Default is compact JSON.",
-    )
-    parser.add_argument(
-        "--sheets-dir",
-        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
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = build_parser()
-    args = parser.parse_args(argv)
-
-    input_path: Path = args.input
-    if not input_path.exists():
-        print(f"File not found: {input_path}")
-        return 0
-
-    try:
-        process_excel(
-            file_path=input_path,
-            output_path=args.output,
-            out_fmt=args.format,
-            image=args.image,
-            pdf=args.pdf,
-            dpi=args.dpi,
-            mode=args.mode,
-            pretty=args.pretty,
-            sheets_dir=args.sheets_dir,
-            print_areas_dir=args.print_areas_dir,
-        )
-        return 0
-    except Exception as e:
-        print(f"Error: {e}")
-        return 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from exstruct import process_excel
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Dev-only CLI stub for ExStruct extraction."
+    )
+    parser.add_argument("input", type=Path, help="Excel file (.xlsx/.xlsm/.xls)")
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Output path. If omitted, writes to stdout.",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        default="json",
+        choices=["json", "yaml", "yml", "toon"],
+        help="Export format",
+    )
+    parser.add_argument(
+        "--image",
+        action="store_true",
+        help="(placeholder) Render PNG alongside JSON",
+    )
+    parser.add_argument(
+        "--pdf",
+        action="store_true",
+        help="(placeholder) Render PDF alongside JSON",
+    )
+    parser.add_argument(
+        "--dpi",
+        type=int,
+        default=144,
+        help="DPI for image rendering (placeholder)",
+    )
+    parser.add_argument(
+        "-m",
+        "--mode",
+        default="standard",
+        choices=["light", "standard", "verbose"],
+        help="Extraction detail level",
+    )
+    parser.add_argument(
+        "--pretty",
+        action="store_true",
+        help="Pretty-print JSON output (indent=2). Default is compact JSON.",
+    )
+    parser.add_argument(
+        "--sheets-dir",
+        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
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    input_path: Path = args.input
+    if not input_path.exists():
+        print(f"File not found: {input_path}", flush=True)
+        return 0
+
+    try:
+        process_excel(
+            file_path=input_path,
+            output_path=args.output,
+            out_fmt=args.format,
+            image=args.image,
+            pdf=args.pdf,
+            dpi=args.dpi,
+            mode=args.mode,
+            pretty=args.pretty,
+            sheets_dir=args.sheets_dir,
+            print_areas_dir=args.print_areas_dir,
+        )
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", flush=True)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{exstruct-0.2.61 → exstruct-0.2.62}/src/exstruct/core/integrate.py

@@ -288,7 +288,7 @@ def integrate_sheet_content(
 
 
 def extract_workbook(  # noqa: C901
-    file_path: Path,
+    file_path: str | Path,
     mode: Literal["light", "standard", "verbose"] = "standard",
     *,
     include_cell_links: bool = False,
@@ -299,21 +299,23 @@ def extract_workbook(  # noqa: C901
     if mode not in _ALLOWED_MODES:
         raise ValueError(f"Unsupported mode: {mode}")
 
+    normalized_file_path = file_path if isinstance(file_path, Path) else Path(file_path)
+
     cell_data = (
-        extract_sheet_cells_with_links(file_path)
+        extract_sheet_cells_with_links(normalized_file_path)
         if include_cell_links
-        else extract_sheet_cells(file_path)
+        else extract_sheet_cells(normalized_file_path)
     )
     print_area_data: dict[str, list[PrintArea]] = {}
     if include_print_areas:
-        print_area_data = _extract_print_areas_openpyxl(file_path)
+        print_area_data = _extract_print_areas_openpyxl(normalized_file_path)
     auto_page_break_data: dict[str, list[PrintArea]] = {}
 
     def _cells_and_tables_only(reason: str) -> WorkbookData:
         sheets: dict[str, SheetData] = {}
         for sheet_name, rows in cell_data.items():
             try:
-                tables = detect_tables_openpyxl(file_path, sheet_name)
+                tables = detect_tables_openpyxl(normalized_file_path, sheet_name)
             except Exception:
                 tables = []
             sheets[sheet_name] = SheetData(
@@ -330,7 +332,7 @@ def extract_workbook(  # noqa: C901
             "%s Falling back to cells+tables only; shapes and charts will be empty.",
             reason,
         )
-        return WorkbookData(book_name=file_path.name, sheets=sheets)
+        return WorkbookData(book_name=normalized_file_path.name, sheets=sheets)
 
     if mode == "light":
         return _cells_and_tables_only("Light mode selected.")
@@ -341,7 +343,7 @@ def extract_workbook(  # noqa: C901
         )
 
     try:
-        wb, close_app = _open_workbook(file_path)
+        wb, close_app = _open_workbook(normalized_file_path)
     except Exception as e:
         return _cells_and_tables_only(f"xlwings/Excel COM is unavailable. ({e!r})")
 
@@ -369,7 +371,7 @@ def extract_workbook(  # noqa: C901
                 if include_auto_page_breaks
                 else None,
             )
-            return WorkbookData(book_name=file_path.name, sheets=merged)
+            return WorkbookData(book_name=normalized_file_path.name, sheets=merged)
         except Exception as e:
             logger.warning(
                 "Shape extraction failed; falling back to cells+tables. (%r)", e