exstruct 0.2.80__py3-none-any.whl → 0.3.2__py3-none-any.whl

exstruct/core/ranges.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from openpyxl.utils import range_boundaries
+
+
+@dataclass(frozen=True)
+class RangeBounds:
+    """Normalized range bounds.
+
+    Attributes:
+        r1: Top row (zero-based).
+        c1: Left column (zero-based).
+        r2: Bottom row (zero-based).
+        c2: Right column (zero-based).
+    """
+
+    r1: int
+    c1: int
+    r2: int
+    c2: int
+
+
+def parse_range_zero_based(range_str: str) -> RangeBounds | None:
+    """Parse an Excel range string into zero-based bounds.
+
+    Args:
+        range_str: Excel range string (e.g., "Sheet1!A1:B2").
+
+    Returns:
+        RangeBounds in zero-based coordinates, or None on failure.
+    """
+    cleaned = range_str.strip()
+    if not cleaned:
+        return None
+    if "!" in cleaned:
+        cleaned = cleaned.split("!", 1)[1]
+    try:
+        min_col, min_row, max_col, max_row = range_boundaries(cleaned)
+    except Exception:
+        return None
+    return RangeBounds(
+        r1=min_row - 1,
+        c1=min_col - 1,
+        r2=max_row - 1,
+        c2=max_col - 1,
+    )

exstruct/core/shapes.py

@@ -1,32 +1,64 @@
 from __future__ import annotations
 
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
 import math
-from typing import SupportsInt, cast
+from typing import Literal, Protocol, SupportsInt, cast, runtime_checkable
 
 import xlwings as xw
 from xlwings import Book
 
-from ..models import Shape
+from ..models import Arrow, Shape, SmartArt, SmartArtNode
 from ..models.maps import MSO_AUTO_SHAPE_TYPE_MAP, MSO_SHAPE_TYPE_MAP
 
 
 def compute_line_angle_deg(w: float, h: float) -> float:
-    """Compute clockwise angle in Excel coordinates where 0 deg points East."""
+    """
+    Compute the clockwise angle (in degrees) in Excel coordinates where 0° points East.
+
+    Parameters:
+        w (float): Horizontal delta (width, positive to the right).
+        h (float): Vertical delta (height, positive downward).
+
+    Returns:
+        float: Angle in degrees measured clockwise from East (e.g., 0° = East, 90° = South).
+    """
     return math.degrees(math.atan2(h, w)) % 360.0
 
 
-def angle_to_compass(angle: float) -> str:
-    """Convert angle to 8-point compass direction (0deg=E, 45deg=NE, 90deg=N, etc)."""
+def angle_to_compass(
+    angle: float,
+) -> Literal["E", "SE", "S", "SW", "W", "NW", "N", "NE"]:
+    """
+    Map an angle in degrees to one of eight compass directions.
+
+    The angle is interpreted with 0 degrees at East and increasing values rotating counterclockwise (45 -> NE, 90 -> N).
+
+    Parameters:
+        angle (float): Angle in degrees.
+
+    Returns:
+        str: One of `"E"`, `"SE"`, `"S"`, `"SW"`, `"W"`, `"NW"`, `"N"`, or `"NE"` corresponding to the nearest 8-point compass direction.
+    """
     dirs = ["E", "NE", "N", "NW", "W", "SW", "S", "SE"]
     idx = int(((angle + 22.5) % 360) // 45)
-    return dirs[idx]
+    return cast(Literal["E", "SE", "S", "SW", "W", "NW", "N", "NE"], 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."""
+    """
+    Estimate the Excel A1-style cell that contains a point given cumulative row and column edge coordinates.
+
+    Parameters:
+        row_edges (list[float]): Monotonic list of cumulative vertical edges (top-to-bottom). Consecutive entries define row spans.
+        col_edges (list[float]): Monotonic list of cumulative horizontal edges (left-to-right). Consecutive entries define column spans.
+        x (float): Horizontal coordinate (same coordinate system as col_edges).
+        y (float): Vertical coordinate (same coordinate system as row_edges).
+
+    Returns:
+        str | None: A1-style cell address (e.g., "B3") if the point falls inside the grid; `None` if the point is outside the provided edge ranges. Intervals are treated as left-inclusive and right-exclusive: [edge_i, edge_{i+1}).
+    """
 
     def find_index(edges: list[float], pos: float) -> int | None:
         for i in range(1, len(edges)):
@@ -80,10 +112,18 @@ def _should_include_shape(
     output_mode: str = "standard",
 ) -> bool:
     """
-    Decide whether to emit a shape given output mode.
-    - standard: emit if text exists OR the shape is an arrow/line/connector.
-    - light: suppress shapes entirely (handled upstream, but guard defensively).
-    - verbose: include all (except already-filtered chart/comment/picture/form controls).
+    Determine whether a shape should be included in the output based on its properties and the selected output mode.
+
+    Modes:
+    - "light": always exclude shapes.
+    - "standard": include when the shape has text or represents a relationship (line/connector).
+    - "verbose": include all shapes (other global exclusions are handled elsewhere).
+
+    Parameters:
+        output_mode (str): One of "light", "standard", or "verbose"; controls inclusion rules.
+
+    Returns:
+        bool: `True` if the shape should be emitted, `False` otherwise.
     """
     if output_mode == "light":
         return False
@@ -108,16 +148,179 @@ def _should_include_shape(
     return True
 
 
+@runtime_checkable
+class _TextRangeLike(Protocol):
+    """Text range interface for SmartArt nodes."""
+
+    Text: str | None
+
+
+@runtime_checkable
+class _TextFrameLike(Protocol):
+    """Text frame interface for SmartArt nodes."""
+
+    HasText: bool
+    TextRange: _TextRangeLike
+
+
+@runtime_checkable
+class _SmartArtNodeLike(Protocol):
+    """SmartArt node interface."""
+
+    Level: int
+    TextFrame2: _TextFrameLike
+
+
+@runtime_checkable
+class _SmartArtLike(Protocol):
+    """SmartArt interface."""
+
+    Layout: object
+    AllNodes: Iterable[_SmartArtNodeLike]
+
+
+def _shape_has_smartart(shp: xw.Shape) -> bool:
+    """
+    Determine whether a shape exposes SmartArt content.
+
+    Returns:
+        bool: `True` if the shape exposes SmartArt (i.e., has an accessible `HasSmartArt` attribute), `False` otherwise.
+    """
+    try:
+        api = shp.api
+    except Exception:
+        return False
+    try:
+        return bool(api.HasSmartArt)
+    except Exception:
+        return False
+
+
+def _get_smartart_layout_name(smartart: _SmartArtLike | None) -> str:
+    """
+    Get the SmartArt layout name or "Unknown" if it cannot be determined.
+
+    Returns:
+        layout_name (str): The layout name from `smartart.Layout.Name`, or "Unknown" when `smartart` is None or the name cannot be retrieved.
+    """
+    if smartart is None:
+        return "Unknown"
+    try:
+        layout = getattr(smartart, "Layout", None)
+        name = getattr(layout, "Name", None)
+        return str(name) if name is not None else "Unknown"
+    except Exception:
+        return "Unknown"
+
+
+def _collect_smartart_node_info(
+    smartart: _SmartArtLike | None,
+) -> list[tuple[int, str]]:
+    """
+    Extract a list of (level, text) tuples for each node present in the given SmartArt.
+
+    Parameters:
+        smartart (_SmartArtLike | None): A SmartArt-like COM object or `None`. If `None` or inaccessible, no nodes are collected.
+
+    Returns:
+        list[tuple[int, str]]: A list of tuples where each tuple is (node level, node text). Returns an empty list if the SmartArt is `None`, inaccessible, or if nodes lack a numeric level.
+    """
+    nodes_info: list[tuple[int, str]] = []
+    if smartart is None:
+        return nodes_info
+    try:
+        all_nodes = smartart.AllNodes
+    except Exception:
+        return nodes_info
+
+    for node in all_nodes:
+        level = _get_smartart_node_level(node)
+        if level is None:
+            continue
+        text = ""
+        try:
+            text_frame = node.TextFrame2
+            if text_frame.HasText:
+                text_value = text_frame.TextRange.Text
+                text = str(text_value) if text_value is not None else ""
+        except Exception:
+            text = ""
+        nodes_info.append((level, text))
+    return nodes_info
+
+
+def _get_smartart_node_level(node: _SmartArtNodeLike) -> int | None:
+    """
+    Get the numerical level of a SmartArt node.
+
+    Returns:
+        int | None: The node's level as an integer, or `None` if the level is missing or cannot be converted to an integer.
+    """
+    try:
+        return int(node.Level)
+    except Exception:
+        return None
+
+
+def _build_smartart_tree(nodes_info: list[tuple[int, str]]) -> list[SmartArtNode]:
+    """
+    Build a nested tree of SmartArtNode objects from a flat list of (level, text) tuples.
+
+    Parameters:
+        nodes_info (list[tuple[int, str]]): Ordered tuples where each tuple is (level, text);
+            `level` is the hierarchical depth (integer) and `text` is the node label.
+
+    Returns:
+        roots (list[SmartArtNode]): Top-level SmartArtNode instances whose `kids` lists
+            contain their nested child nodes according to the provided levels.
+    """
+    roots: list[SmartArtNode] = []
+    stack: list[tuple[int, SmartArtNode]] = []
+    for level, text in nodes_info:
+        node = SmartArtNode(text=text, kids=[])
+        while stack and stack[-1][0] >= level:
+            stack.pop()
+        if stack:
+            stack[-1][1].kids.append(node)
+        else:
+            roots.append(node)
+        stack.append((level, node))
+    return roots
+
+
+def _extract_smartart_nodes(smartart: _SmartArtLike | None) -> list[SmartArtNode]:
+    """
+    Convert a SmartArt COM object into a list of root SmartArtNode trees.
+
+    Parameters:
+        smartart (_SmartArtLike | None): SmartArt-like COM object to extract nodes from; pass `None` to produce an empty list.
+
+    Returns:
+        list[SmartArtNode]: Root nodes representing the hierarchical SmartArt structure (each node contains its text and children).
+    """
+    nodes_info = _collect_smartart_node_info(smartart)
+    return _build_smartart_tree(nodes_info)
+
+
 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]] = {}
+) -> dict[str, list[Shape | Arrow | SmartArt]]:
+    """
+    Scan all shapes in each worksheet and collect their positional and metadata information.
+
+    Parameters:
+        workbook (Book): The xlwings workbook to scan.
+        mode (str): Output detail level; "light" skips most shapes, "standard" includes shapes with text or relationships, and "verbose" includes full size/rotation details.
+
+    Returns:
+        dict[str, list[Shape | Arrow | SmartArt]]: Mapping of sheet name to a list of collected shape objects (Shape, Arrow, or SmartArt) containing position (left/top), optional size (width/height), textual content, and other captured metadata (ids, directions, connections, layout/nodes for SmartArt).
+    """
+    shape_data: dict[str, list[Shape | Arrow | SmartArt]] = {}
     for sheet in workbook.sheets:
-        shapes: list[Shape] = []
+        shapes: list[Shape | Arrow | SmartArt] = []
         excel_names: list[tuple[str, int]] = []
         node_index = 0
-        pending_connections: list[tuple[Shape, str | None, str | None]] = []
+        pending_connections: list[tuple[Arrow, str | None, str | None]] = []
         for root in sheet.shapes:
             for shp in iter_shapes_recursive(root):
                 try:
@@ -148,7 +351,11 @@ def get_shapes_with_position(  # noqa: C901
                 except Exception:
                     text = ""
 
-                if not _should_include_shape(
+                if mode == "light":
+                    continue
+
+                has_smartart = _shape_has_smartart(shp)
+                if not has_smartart and not _should_include_shape(
                     text=text,
                     shape_type_num=type_num,
                     shape_type_str=shape_type_str,
@@ -179,7 +386,8 @@ def get_shapes_with_position(  # noqa: C901
                 ):
                     is_relationship_geom = True
                 if shape_type_str and (
-                    "Connector" in shape_type_str or shape_type_str in ("Line", "ConnectLine")
+                    "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):
@@ -192,19 +400,54 @@ def get_shapes_with_position(  # noqa: C901
 
                 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),
-                    w=int(shp.width)
-                    if mode == "verbose" or shape_type_str == "Group"
-                    else None,
-                    h=int(shp.height)
-                    if mode == "verbose" or shape_type_str == "Group"
-                    else None,
-                    type=type_label,
-                )
+                shape_obj: Shape | Arrow | SmartArt
+                if has_smartart:
+                    smartart_obj: _SmartArtLike | None = None
+                    try:
+                        smartart_obj = shp.api.SmartArt
+                    except Exception:
+                        smartart_obj = None
+                    shape_obj = SmartArt(
+                        id=shape_id,
+                        text=text,
+                        l=int(shp.left),
+                        t=int(shp.top),
+                        w=int(shp.width)
+                        if mode == "verbose" or shape_type_str == "Group"
+                        else None,
+                        h=int(shp.height)
+                        if mode == "verbose" or shape_type_str == "Group"
+                        else None,
+                        layout=_get_smartart_layout_name(smartart_obj),
+                        nodes=_extract_smartart_nodes(smartart_obj),
+                    )
+                elif is_relationship_geom:
+                    shape_obj = Arrow(
+                        id=shape_id,
+                        text=text,
+                        l=int(shp.left),
+                        t=int(shp.top),
+                        w=int(shp.width)
+                        if mode == "verbose" or shape_type_str == "Group"
+                        else None,
+                        h=int(shp.height)
+                        if mode == "verbose" or shape_type_str == "Group"
+                        else None,
+                    )
+                else:
+                    shape_obj = Shape(
+                        id=shape_id,
+                        text=text,
+                        l=int(shp.left),
+                        t=int(shp.top),
+                        w=int(shp.width)
+                        if mode == "verbose" or shape_type_str == "Group"
+                        else None,
+                        h=int(shp.height)
+                        if mode == "verbose" or shape_type_str == "Group"
+                        else None,
+                        type=type_label,
+                    )
                 if excel_name:
                     if shape_id is not None:
                         excel_names.append((excel_name, shape_id))
@@ -215,7 +458,8 @@ def get_shapes_with_position(  # noqa: C901
                         angle = compute_line_angle_deg(
                             float(shp.width), float(shp.height)
                         )
-                        shape_obj.direction = angle_to_compass(angle)  # type: ignore
+                        if isinstance(shape_obj, Arrow):
+                            shape_obj.direction = angle_to_compass(angle)
                         try:
                             rot = float(shp.api.Rotation)
                             if abs(rot) > 1e-6:
@@ -225,8 +469,9 @@ def get_shapes_with_position(  # noqa: C901
                         try:
                             begin_style = int(shp.api.Line.BeginArrowheadStyle)
                             end_style = int(shp.api.Line.EndArrowheadStyle)
-                            shape_obj.begin_arrow_style = begin_style
-                            shape_obj.end_arrow_style = end_style
+                            if isinstance(shape_obj, Arrow):
+                                shape_obj.begin_arrow_style = begin_style
+                                shape_obj.end_arrow_style = end_style
                         except Exception:
                             pass
                         # Connector begin/end connected shapes (if this shape is a connector).
@@ -262,7 +507,8 @@ def get_shapes_with_position(  # noqa: C901
                             pass
                 except Exception:
                     pass
-                pending_connections.append((shape_obj, begin_name, end_name))
+                if isinstance(shape_obj, Arrow):
+                    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}

exstruct/core/workbook.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+import logging
+from pathlib import Path
+from typing import Any
+import warnings
+
+from openpyxl import load_workbook
+import xlwings as xw
+
+logger = logging.getLogger(__name__)
+
+
+@contextmanager
+def openpyxl_workbook(
+    file_path: Path, *, data_only: bool, read_only: bool
+) -> Iterator[Any]:
+    """Open an openpyxl workbook and ensure it is closed.
+
+    Args:
+        file_path: Workbook path.
+        data_only: Whether to read formula results.
+        read_only: Whether to open in read-only mode.
+
+    Yields:
+        openpyxl workbook instance.
+    """
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message="Unknown extension is not supported and will be removed",
+            category=UserWarning,
+            module="openpyxl",
+        )
+        warnings.filterwarnings(
+            "ignore",
+            message="Conditional Formatting extension is not supported and will be removed",
+            category=UserWarning,
+            module="openpyxl",
+        )
+        warnings.filterwarnings(
+            "ignore",
+            message="Cannot parse header or footer so it will be ignored",
+            category=UserWarning,
+            module="openpyxl",
+        )
+        wb = load_workbook(file_path, data_only=data_only, read_only=read_only)
+    try:
+        yield wb
+    finally:
+        try:
+            wb.close()
+        except Exception as exc:
+            logger.debug("Failed to close openpyxl workbook. (%r)", exc)
+
+
+@contextmanager
+def xlwings_workbook(file_path: Path, *, visible: bool = False) -> Iterator[xw.Book]:
+    """Open an Excel workbook via xlwings and close if created.
+
+    Args:
+        file_path: Workbook path.
+        visible: Whether to show the Excel application window.
+
+    Yields:
+        xlwings workbook instance.
+    """
+    existing = _find_open_workbook(file_path)
+    if existing:
+        yield existing
+        return
+
+    app = xw.App(add_book=False, visible=visible)
+    wb = app.books.open(str(file_path))
+    try:
+        yield wb
+    finally:
+        try:
+            wb.close()
+        except Exception as exc:
+            logger.debug("Failed to close Excel workbook. (%r)", exc)
+        try:
+            app.quit()
+        except Exception as exc:
+            logger.debug("Failed to quit Excel application. (%r)", exc)
+
+
+def _find_open_workbook(file_path: Path) -> xw.Book | None:
+    """Return an existing workbook if already open in Excel.
+
+    Args:
+        file_path: Workbook path to search for.
+
+    Returns:
+        Existing xlwings workbook if open; otherwise None.
+    """
+    try:
+        for app in xw.apps:
+            for wb in app.books:
+                resolved_path: Path | None = None
+                try:
+                    resolved_path = Path(wb.fullname).resolve()
+                except Exception as exc:
+                    logger.debug("Failed to resolve workbook path. (%r)", exc)
+                if resolved_path is None:
+                    continue
+                if resolved_path == file_path.resolve():
+                    return wb
+    except Exception as exc:
+        logger.debug("Failed to inspect open Excel workbooks. (%r)", exc)
+        return None
+    return None