exstruct 0.1.0__tar.gz

exstruct-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, ExStruct Contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

exstruct-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.3
+Name: exstruct
+Version: 0.1.0
+Summary: Add your description here
+Keywords: excel,structure,data,exstruct
+Author: harumiWeb
+Author-email: harumiWeb <ganaharumi@outlook.jp>
+License: BSD 3-Clause License
+         
+         Copyright (c) 2025, ExStruct Contributors
+         All rights reserved.
+         
+         Redistribution and use in source and binary forms, with or without
+         modification, are permitted provided that the following conditions are met:
+         
+         1. Redistributions of source code must retain the above copyright notice, this
+            list of conditions and the following disclaimer.
+         
+         2. Redistributions in binary form must reproduce the above copyright notice,
+            this list of conditions and the following disclaimer in the documentation
+            and/or other materials provided with the distribution.
+         
+         3. Neither the name of the copyright holder nor the names of its
+            contributors may be used to endorse or promote products derived from
+            this software without specific prior written permission.
+         
+         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.3.3
+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: python-toon>=0.1.3 ; extra == 'toon'
+Requires-Dist: pyyaml>=6.0.3 ; extra == 'yaml'
+Requires-Python: >=3.12
+Project-URL: Documentation, https://harumiweb.github.io/exstruct/
+Project-URL: Homepage, https://harumiweb.github.io/exstruct/
+Project-URL: Issues, https://github.com/harumiWeb/exstruct/issues
+Project-URL: Repository, https://github.com/harumiWeb/exstruct
+Provides-Extra: render
+Provides-Extra: toon
+Provides-Extra: yaml
+Description-Content-Type: text/markdown
+
+# ExStruct — Excel Structured Extraction Engine
+
+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.
+
+## 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).
+- **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.
+- **Graceful fallback**: if Excel COM is unavailable, extraction falls back to cells + table candidates without crashing.
+
+## Installation
+
+```bash
+pip install exstruct
+```
+
+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                # compact JSON (default)
+exstruct input.xlsx --pretty       # pretty-printed JSON
+exstruct input.xlsx --format yaml  # YAML (needs pyyaml)
+exstruct input.xlsx --format toon  # TOON (needs python-toon)
+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
+```
+
+## Table Detection Tuning
+
+```python
+from exstruct import set_table_detection_params
+
+set_table_detection_params(
+    table_score_threshold=0.35,  # increase to be stricter
+    density_min=0.05,
+    coverage_min=0.2,
+    min_nonempty_cells=3,
+)
+```
+
+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.
+- **verbose**: all shapes (with width/height), charts, table candidates.
+
+## Error Handling / Fallbacks
+
+- Excel COM unavailable → falls back to cells + table candidates; shapes/charts empty.
+- Shape extraction failure → logs warning, still returns cells + table candidates.
+- CLI prints errors to stdout/stderr and returns non-zero on failures.
+
+## Optional Rendering
+
+Requires Excel and `pypdfium2`.
+
+```bash
+exstruct input.xlsx --pdf --image --dpi 144
+```
+
+Creates `<output>.pdf` and `<output>_images/` PNGs per sheet.
+
+## Notes
+
+- Default JSON is compact to reduce tokens; use `--pretty` or `pretty=True` when readability matters.
+- Field `table_candidates` replaces `tables`; adjust downstream consumers accordingly.
+
+## License
+
+BSD-3-Clause. See `LICENSE` for details.
+
+## Documentation
+
+- API Reference (GitHub Pages): https://harumiweb.github.io/exstruct/

exstruct-0.1.0/README.md

@@ -0,0 +1,99 @@
+# ExStruct — Excel Structured Extraction Engine
+
+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.
+
+## 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).
+- **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.
+- **Graceful fallback**: if Excel COM is unavailable, extraction falls back to cells + table candidates without crashing.
+
+## Installation
+
+```bash
+pip install exstruct
+```
+
+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                # compact JSON (default)
+exstruct input.xlsx --pretty       # pretty-printed JSON
+exstruct input.xlsx --format yaml  # YAML (needs pyyaml)
+exstruct input.xlsx --format toon  # TOON (needs python-toon)
+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
+```
+
+## Table Detection Tuning
+
+```python
+from exstruct import set_table_detection_params
+
+set_table_detection_params(
+    table_score_threshold=0.35,  # increase to be stricter
+    density_min=0.05,
+    coverage_min=0.2,
+    min_nonempty_cells=3,
+)
+```
+
+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.
+- **verbose**: all shapes (with width/height), charts, table candidates.
+
+## Error Handling / Fallbacks
+
+- Excel COM unavailable → falls back to cells + table candidates; shapes/charts empty.
+- Shape extraction failure → logs warning, still returns cells + table candidates.
+- CLI prints errors to stdout/stderr and returns non-zero on failures.
+
+## Optional Rendering
+
+Requires Excel and `pypdfium2`.
+
+```bash
+exstruct input.xlsx --pdf --image --dpi 144
+```
+
+Creates `<output>.pdf` and `<output>_images/` PNGs per sheet.
+
+## Notes
+
+- Default JSON is compact to reduce tokens; use `--pretty` or `pretty=True` when readability matters.
+- Field `table_candidates` replaces `tables`; adjust downstream consumers accordingly.
+
+## License
+
+BSD-3-Clause. See `LICENSE` for details.
+
+## Documentation
+
+- API Reference (GitHub Pages): https://harumiweb.github.io/exstruct/

exstruct-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "exstruct"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+license = { file = "LICENSE" }
+keywords = ["excel", "structure", "data", "exstruct"]
+authors = [
+    { name = "harumiWeb", email = "ganaharumi@outlook.jp" }
+]
+requires-python = ">=3.12"
+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",
+    "pytest>=9.0.1",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
+]
+
+[project.optional-dependencies]
+yaml = ["pyyaml>=6.0.3"]
+toon = ["python-toon>=0.1.3"]
+render = ["pypdfium2>=5.1.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/"

exstruct-0.1.0/src/exstruct/__init__.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional
+
+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
+from .models import CellRow, Chart, ChartSeries, Shape, SheetData, WorkbookData
+from .render import export_pdf, export_sheet_images
+
+__all__ = [
+    "extract",
+    "export",
+    "export_sheets",
+    "export_pdf",
+    "export_sheet_images",
+    "process_excel",
+    "ExtractionMode",
+    "CellRow",
+    "Shape",
+    "ChartSeries",
+    "Chart",
+    "SheetData",
+    "WorkbookData",
+    "set_table_detection_params",
+]
+
+
+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)
+
+
+def export(
+    data: WorkbookData,
+    path: str | Path,
+    fmt: Optional[Literal["json", "yaml", "yml", "toon"]] = None,
+    *,
+    pretty: bool = False,
+    indent: int | None = None,
+) -> None:
+    """Export WorkbookData to supported file formats (json/yaml/toon)."""
+    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 a JSON file (book_name + SheetData) into a directory.
+    Returns a mapping of sheet name to written 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), including book_name and SheetData; returns sheet name → path map.
+    """
+    return save_sheets(data, Path(dir_path), fmt=fmt, pretty=pretty, indent=indent)
+
+
+def process_excel(
+    file_path: Path,
+    output_path: Path,
+    out_fmt: str = "json",
+    image: bool = False,
+    pdf: bool = False,
+    dpi: int = 72,
+    mode: ExtractionMode = "standard",
+    pretty: bool = False,
+    indent: int | None = None,
+) -> None:
+    """Convenience wrapper for CLI: export workbook and optionally PDF/PNG images (Excel required for rendering)."""
+    if mode not in ("light", "standard", "verbose"):
+        raise ValueError(f"Unsupported mode: {mode}")
+    workbook_model = extract(file_path, mode=mode)
+    match out_fmt:
+        case "json":
+            save_as_json(workbook_model, output_path, pretty=pretty, indent=indent)
+        case "yaml" | "yml":
+            save_as_yaml(workbook_model, output_path)
+        case "toon":
+            save_as_toon(workbook_model, output_path)
+        case _:
+            raise ValueError(f"Unsupported export format: {out_fmt}")
+
+    if pdf or image:
+        pdf_path = output_path.with_suffix(".pdf")
+        export_pdf(file_path, pdf_path)
+        if image:
+            images_dir = output_path.parent / f"{output_path.stem}_images"
+            export_sheet_images(file_path, images_dir, dpi=dpi)
+
+    print(f"{file_path.name} -> {output_path} completed.")

exstruct-0.1.0/src/exstruct/cli/main.py

@@ -0,0 +1,93 @@
+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 (defaults to <input>.json)",
+    )
+    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.",
+    )
+    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
+
+    suffix = ".json"
+    if args.format in ("yaml", "yml"):
+        suffix = ".yaml"
+    elif args.format == "toon":
+        suffix = ".toon"
+
+    output_path: Path = args.output or input_path.with_suffix(suffix)
+
+    try:
+        process_excel(
+            file_path=input_path,
+            output_path=output_path,
+            out_fmt=args.format,
+            image=args.image,
+            pdf=args.pdf,
+            dpi=args.dpi,
+            mode=args.mode,
+            pretty=args.pretty,
+        )
+        return 0
+    except Exception as e:
+        print(f"Error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())