exstruct 0.2.70__tar.gz → 0.2.71__tar.gz

{exstruct-0.2.70 → exstruct-0.2.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.70
+Version: 0.2.71
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -67,7 +67,7 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 
 - **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.
+- **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested (CLI option appears only when COM is available).
 - **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.
@@ -99,11 +99,12 @@ 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 --auto-page-breaks-dir auto_areas/  # COM only; option appears when available
 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(...)`.
+Auto page-break exports are available via API and CLI when Excel/COM is available; the CLI exposes `--auto-page-breaks-dir` only in COM-capable environments.
 
 ## Quick Start (Python)
 
@@ -409,7 +410,7 @@ In short, **exstruct = “an engine that converts Excel into a format AI can und
 - `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.
+- Use CLI `--auto-page-breaks-dir` (COM only), `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.70 → exstruct-0.2.71}/README.md

@@ -12,7 +12,7 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 
 - **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.
+- **Auto page-break export (COM only)**: capture Excel-computed auto page breaks and write per-area JSON/YAML/TOON when requested (CLI option appears only when COM is available).
 - **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.
@@ -44,11 +44,12 @@ 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 --auto-page-breaks-dir auto_areas/  # COM only; option appears when available
 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(...)`.
+Auto page-break exports are available via API and CLI when Excel/COM is available; the CLI exposes `--auto-page-breaks-dir` only in COM-capable environments.
 
 ## Quick Start (Python)
 
@@ -354,7 +355,7 @@ In short, **exstruct = “an engine that converts Excel into a format AI can und
 - `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.
+- Use CLI `--auto-page-breaks-dir` (COM only), `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.70 → exstruct-0.2.71}/pyproject.toml

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

exstruct-0.2.71/src/exstruct/cli/availability.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+from pydantic import BaseModel, Field
+import xlwings as xw
+
+logger = logging.getLogger(__name__)
+
+
+class ComAvailability(BaseModel):
+    """Availability information for Excel COM-dependent features."""
+
+    available: bool = Field(
+        ..., description="True when Excel COM can be used from this environment."
+    )
+    reason: str | None = Field(
+        default=None, description="Reason COM features are unavailable."
+    )
+
+
+def get_com_availability() -> ComAvailability:
+    """Detect whether Excel COM is available for CLI features.
+
+    Returns:
+        ComAvailability describing whether COM features can be used.
+    """
+    if os.getenv("SKIP_COM_TESTS"):
+        return ComAvailability(available=False, reason="SKIP_COM_TESTS is set.")
+
+    if sys.platform != "win32":
+        return ComAvailability(available=False, reason="Non-Windows platform.")
+
+    try:
+        app = xw.App(add_book=False, visible=False)
+    except Exception as exc:
+        return ComAvailability(
+            available=False,
+            reason=f"Excel COM is unavailable ({exc.__class__.__name__}).",
+        )
+
+    try:
+        app.quit()
+    except Exception:
+        logger.warning("Failed to quit Excel during COM availability check.")
+
+    return ComAvailability(available=True, reason=None)

{exstruct-0.2.70 → exstruct-0.2.71}/src/exstruct/cli/main.py

@@ -4,9 +4,33 @@ import argparse
 from pathlib import Path
 
 from exstruct import process_excel
+from exstruct.cli.availability import ComAvailability, get_com_availability
 
 
-def build_parser() -> argparse.ArgumentParser:
+def _add_auto_page_breaks_argument(
+    parser: argparse.ArgumentParser, availability: ComAvailability
+) -> None:
+    """Add auto page-break export option when COM is available."""
+    if not availability.available:
+        return
+    parser.add_argument(
+        "--auto-page-breaks-dir",
+        type=Path,
+        help="Optional directory to write one file per auto page-break area (COM only).",
+    )
+
+
+def build_parser(
+    availability: ComAvailability | None = None,
+) -> argparse.ArgumentParser:
+    """Build the CLI argument parser.
+
+    Args:
+        availability: Optional COM availability for tests or overrides.
+
+    Returns:
+        Configured argument parser.
+    """
     parser = argparse.ArgumentParser(
         description="Dev-only CLI stub for ExStruct extraction."
     )
@@ -62,10 +86,22 @@ def build_parser() -> argparse.ArgumentParser:
         type=Path,
         help="Optional directory to write one file per print area (format follows --format).",
     )
+    resolved_availability = (
+        availability if availability is not None else get_com_availability()
+    )
+    _add_auto_page_breaks_argument(parser, resolved_availability)
     return parser
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Run the CLI entrypoint.
+
+    Args:
+        argv: Optional argument list for testing.
+
+    Returns:
+        Exit code (0 for success, 1 for failure).
+    """
     parser = build_parser()
     args = parser.parse_args(argv)
 
@@ -86,6 +122,7 @@ def main(argv: list[str] | None = None) -> int:
             pretty=args.pretty,
             sheets_dir=args.sheets_dir,
             print_areas_dir=args.print_areas_dir,
+            auto_page_breaks_dir=getattr(args, "auto_page_breaks_dir", None),
         )
         return 0
     except Exception as e: