exstruct 0.2.70__tar.gz → 0.2.80__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.70
+Version: 0.2.80
 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)
 
@@ -404,12 +405,24 @@ 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.
 
+## Enterprise Use
+
+ExStruct is used primarily as a **library**, not a service.
+
+- No official support or SLA is provided
+- Long-term stability is prioritized over rapid feature growth
+- Forking and internal modification are expected in enterprise use
+
+This project is suitable for teams that:
+- need transparency over black-box tools
+- are comfortable maintaining internal forks if necessary
+
 ## 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.
+- 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
@@ -419,3 +432,4 @@ BSD-3-Clause. See `LICENSE` for details.
 ## Documentation
 
 - API Reference (GitHub Pages): https://harumiweb.github.io/exstruct/
+- JSON Schemas: see `schemas/` (one file per model); regenerate via `python scripts/gen_json_schema.py`.

{exstruct-0.2.70 → exstruct-0.2.80}/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)
 
@@ -349,12 +350,24 @@ 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.
 
+## Enterprise Use
+
+ExStruct is used primarily as a **library**, not a service.
+
+- No official support or SLA is provided
+- Long-term stability is prioritized over rapid feature growth
+- Forking and internal modification are expected in enterprise use
+
+This project is suitable for teams that:
+- need transparency over black-box tools
+- are comfortable maintaining internal forks if necessary
+
 ## 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.
+- 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
@@ -364,3 +377,4 @@ BSD-3-Clause. See `LICENSE` for details.
 ## Documentation
 
 - API Reference (GitHub Pages): https://harumiweb.github.io/exstruct/
+- JSON Schemas: see `schemas/` (one file per model); regenerate via `python scripts/gen_json_schema.py`.

{exstruct-0.2.70 → exstruct-0.2.80}/pyproject.toml

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

exstruct-0.2.80/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.80}/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:

{exstruct-0.2.70 → exstruct-0.2.80}/src/exstruct/core/shapes.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from collections.abc import Iterator
-import math
-from typing import SupportsInt, cast
+from collections.abc import Iterator
+import math
+from typing import SupportsInt, cast
 
 import xlwings as xw
 from xlwings import Book
@@ -23,54 +23,54 @@ def angle_to_compass(angle: float) -> str:
     return dirs[idx]
 
 
-def coord_to_cell_by_edges(
-    row_edges: list[float], col_edges: list[float], x: float, y: float
-) -> str | None:
-    """Estimate cell address from coordinates and cumulative edges; return None if out of range."""
-
-    def find_index(edges: list[float], pos: float) -> int | None:
-        for i in range(1, len(edges)):
-            if edges[i - 1] <= pos < edges[i]:
-                return i
-        return None
+def coord_to_cell_by_edges(
+    row_edges: list[float], col_edges: list[float], x: float, y: float
+) -> str | None:
+    """Estimate cell address from coordinates and cumulative edges; return None if out of range."""
+
+    def find_index(edges: list[float], pos: float) -> int | None:
+        for i in range(1, len(edges)):
+            if edges[i - 1] <= pos < edges[i]:
+                return i
+        return None
 
     r = find_index(row_edges, y)
     c = find_index(col_edges, x)
     if r is None or c is None:
         return None
-    return f"{xw.utils.col_name(c)}{r}"
-
-
-def has_arrow(style_val: object) -> bool:
-    """Return True if Excel arrow style value indicates an arrowhead."""
-    try:
-        v = int(cast(SupportsInt, style_val))
-        return v != 0
-    except Exception:
-        return False
-
-
-def iter_shapes_recursive(shp: xw.Shape) -> Iterator[xw.Shape]:
-    """Yield shapes recursively, including group children."""
-    yield shp
-    try:
-        if shp.api.Type == 6:
-            items = shp.api.GroupItems
-            for i in range(1, items.Count + 1):
-                inner = items.Item(i)
-                try:
-                    name = inner.Name
-                    xl_shape = shp.parent.shapes[name]
-                except Exception:
-                    xl_shape = None
-
-                if xl_shape is not None:
-                    yield from iter_shapes_recursive(xl_shape)
-    except Exception:
-        pass
-
-
-def _should_include_shape(
+    return f"{xw.utils.col_name(c)}{r}"
+
+
+def has_arrow(style_val: object) -> bool:
+    """Return True if Excel arrow style value indicates an arrowhead."""
+    try:
+        v = int(cast(SupportsInt, style_val))
+        return v != 0
+    except Exception:
+        return False
+
+
+def iter_shapes_recursive(shp: xw.Shape) -> Iterator[xw.Shape]:
+    """Yield shapes recursively, including group children."""
+    yield shp
+    try:
+        if shp.api.Type == 6:
+            items = shp.api.GroupItems
+            for i in range(1, items.Count + 1):
+                inner = items.Item(i)
+                try:
+                    name = inner.Name
+                    xl_shape = shp.parent.shapes[name]
+                except Exception:
+                    xl_shape = None
+
+                if xl_shape is not None:
+                    yield from iter_shapes_recursive(xl_shape)
+    except Exception:
+        pass
+
+
+def _should_include_shape(
     *,
     text: str,
     shape_type_num: int | None,
@@ -108,13 +108,16 @@ def _should_include_shape(
     return True
 
 
-def get_shapes_with_position(  # noqa: C901
-    workbook: Book, mode: str = "standard"
-) -> dict[str, list[Shape]]:
+def get_shapes_with_position(  # noqa: C901
+    workbook: Book, mode: str = "standard"
+) -> dict[str, list[Shape]]:
     """Scan shapes in a workbook and return per-sheet Shape lists with position info."""
     shape_data: dict[str, list[Shape]] = {}
     for sheet in workbook.sheets:
         shapes: list[Shape] = []
+        excel_names: list[tuple[str, int]] = []
+        node_index = 0
+        pending_connections: list[tuple[Shape, str | None, str | None]] = []
         for root in sheet.shapes:
             for shp in iter_shapes_recursive(root):
                 try:
@@ -168,7 +171,29 @@ def get_shapes_with_position(  # noqa: C901
                         else (shape_type_str or shape_name or "Unknown")
                     )
 
+                is_relationship_geom = False
+                if type_num in (3, 9):
+                    is_relationship_geom = True
+                if autoshape_type_str and (
+                    "Arrow" in autoshape_type_str or "Connector" in autoshape_type_str
+                ):
+                    is_relationship_geom = True
+                if shape_type_str and (
+                    "Connector" in shape_type_str or shape_type_str in ("Line", "ConnectLine")
+                ):
+                    is_relationship_geom = True
+                if shape_name and ("Connector" in shape_name or "Line" in shape_name):
+                    is_relationship_geom = True
+
+                shape_id = None
+                if not is_relationship_geom:
+                    node_index += 1
+                    shape_id = node_index
+
+                excel_name = shape_name if isinstance(shape_name, str) else None
+
                 shape_obj = Shape(
+                    id=shape_id,
                     text=text,
                     l=int(shp.left),
                     t=int(shp.top),
@@ -180,25 +205,12 @@ def get_shapes_with_position(  # noqa: C901
                     else None,
                     type=type_label,
                 )
+                if excel_name:
+                    if shape_id is not None:
+                        excel_names.append((excel_name, shape_id))
                 try:
-                    is_relationship_geom = False
-                    if type_num in (3, 9):
-                        is_relationship_geom = True
-                    if autoshape_type_str and (
-                        "Arrow" in autoshape_type_str
-                        or "Connector" in autoshape_type_str
-                    ):
-                        is_relationship_geom = True
-                    if shape_type_str and (
-                        "Connector" in shape_type_str
-                        or shape_type_str in ("Line", "ConnectLine")
-                    ):
-                        is_relationship_geom = True
-                    if shape_name and (
-                        "Connector" in shape_name or "Line" in shape_name
-                    ):
-                        is_relationship_geom = True
-
+                    begin_name: str | None = None
+                    end_name: str | None = None
                     if is_relationship_geom:
                         angle = compute_line_angle_deg(
                             float(shp.width), float(shp.height)
@@ -217,6 +229,28 @@ def get_shapes_with_position(  # noqa: C901
                             shape_obj.end_arrow_style = end_style
                         except Exception:
                             pass
+                        # Connector begin/end connected shapes (if this shape is a connector).
+                        try:
+                            connector = shp.api.ConnectorFormat
+                            try:
+                                begin_shape = connector.BeginConnectedShape
+                                if begin_shape is not None:
+                                    name = getattr(begin_shape, "Name", None)
+                                    if isinstance(name, str):
+                                        begin_name = name
+                            except Exception:
+                                pass
+                            try:
+                                end_shape = connector.EndConnectedShape
+                                if end_shape is not None:
+                                    name = getattr(end_shape, "Name", None)
+                                    if isinstance(name, str):
+                                        end_name = name
+                            except Exception:
+                                pass
+                        except Exception:
+                            # Not a connector or ConnectorFormat is unavailable.
+                            pass
                     elif type_num == 1 and (
                         autoshape_type_str and "Arrow" in autoshape_type_str
                     ):
@@ -228,6 +262,14 @@ def get_shapes_with_position(  # noqa: C901
                             pass
                 except Exception:
                     pass
+                pending_connections.append((shape_obj, begin_name, end_name))
                 shapes.append(shape_obj)
+        if pending_connections:
+            name_to_id = {name: sid for name, sid in excel_names}
+            for shape_obj, begin_name, end_name in pending_connections:
+                if begin_name:
+                    shape_obj.begin_id = name_to_id.get(begin_name)
+                if end_name:
+                    shape_obj.end_id = name_to_id.get(end_name)
         shape_data[sheet.name] = shapes
     return shape_data

{exstruct-0.2.70 → exstruct-0.2.80}/src/exstruct/models/__init__.py

@@ -11,6 +11,9 @@ from pydantic import BaseModel, Field
 class Shape(BaseModel):
     """Shape metadata (position, size, text, and styling)."""
 
+    id: int | None = Field(
+        default=None, description="Sequential shape id within the sheet (if applicable)."
+    )
     text: str = Field(description="Visible text content of the shape.")
     l: int = Field(description="Left offset (Excel units).")  # noqa: E741
     t: int = Field(description="Top offset (Excel units).")
@@ -26,6 +29,18 @@ class Shape(BaseModel):
     end_arrow_style: int | None = Field(
         default=None, description="Arrow style enum for the end of a connector."
     )
+    begin_id: int | None = Field(
+        default=None,
+        description=(
+            "Shape id at the start of a connector (ConnectorFormat.BeginConnectedShape)."
+        ),
+    )
+    end_id: int | None = Field(
+        default=None,
+        description=(
+            "Shape id at the end of a connector (ConnectorFormat.EndConnectedShape)."
+        ),
+    )
     direction: Literal["E", "SE", "S", "SW", "W", "NW", "N", "NE"] | None = Field(
         default=None, description="Connector direction (compass heading)."
     )