exstruct 0.2.71__tar.gz → 0.2.80__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.71
+Version: 0.2.80
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -405,6 +405,18 @@ 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.
@@ -420,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.71 → exstruct-0.2.80}/README.md

@@ -350,6 +350,18 @@ 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.
@@ -365,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.71 → exstruct-0.2.80}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.71"
+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.71 → 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.71 → 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)."
     )