exstruct 0.1.0__py3-none-any.whl

exstruct/core/charts.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import logging
+from typing import Dict, List, Optional
+
+import xlwings as xw
+
+from ..models import Chart, ChartSeries
+from ..models.maps import XL_CHART_TYPE_MAP
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_series_args_text(formula: str) -> Optional[str]:
+    """Extract the outer argument text from '=SERIES(...)'; return None if unmatched."""
+    if not formula:
+        return None
+    s = formula.strip()
+    if not s.upper().startswith("=SERIES"):
+        return None
+    try:
+        open_idx = s.index("(", s.upper().index("=SERIES"))
+    except ValueError:
+        return None
+    depth_paren = 0
+    depth_brace = 0
+    in_str = False
+    i = open_idx + 1
+    start = i
+    while i < len(s):
+        ch = s[i]
+        if in_str:
+            if ch == '"':
+                if i + 1 < len(s) and s[i + 1] == '"':
+                    i += 2
+                    continue
+                else:
+                    in_str = False
+                    i += 1
+                    continue
+            else:
+                i += 1
+                continue
+        else:
+            if ch == '"':
+                in_str = True
+                i += 1
+                continue
+            elif ch == "(":
+                depth_paren += 1
+            elif ch == ")":
+                if depth_paren == 0:
+                    return s[start:i].strip()
+                depth_paren -= 1
+            elif ch == "{":
+                depth_brace += 1
+            elif ch == "}":
+                if depth_brace > 0:
+                    depth_brace -= 1
+            i += 1
+    return None
+
+
+def _split_top_level_args(args_text: str) -> List[str]:
+    """Split SERIES arguments at top-level separators (',' or ';')."""
+    if args_text is None:
+        return []
+    use_semicolon = (";" in args_text) and ("," not in args_text.split('"')[0])
+    sep_chars = (";",) if use_semicolon else (",",)
+    args: List[str] = []
+    buf: List[str] = []
+    depth_paren = 0
+    depth_brace = 0
+    in_str = False
+    i = 0
+    while i < len(args_text):
+        ch = args_text[i]
+        if in_str:
+            if ch == '"':
+                if i + 1 < len(args_text) and args_text[i + 1] == '"':
+                    buf.append('"')
+                    i += 2
+                    continue
+                else:
+                    in_str = False
+                    i += 1
+                    continue
+            else:
+                buf.append(ch)
+                i += 1
+                continue
+        else:
+            if ch == '"':
+                in_str = True
+                i += 1
+                continue
+            elif ch == "(":
+                depth_paren += 1
+                buf.append(ch)
+                i += 1
+                continue
+            elif ch == ")":
+                depth_paren = max(0, depth_paren - 1)
+                buf.append(ch)
+                i += 1
+                continue
+            elif ch == "{":
+                depth_brace += 1
+                buf.append(ch)
+                i += 1
+                continue
+            elif ch == "}":
+                depth_brace = max(0, depth_brace - 1)
+                buf.append(ch)
+                i += 1
+                continue
+            elif (ch in sep_chars) and depth_paren == 0 and depth_brace == 0:
+                args.append("".join(buf).strip())
+                buf = []
+                i += 1
+                continue
+            else:
+                buf.append(ch)
+                i += 1
+                continue
+    if buf or (args and args_text.endswith(sep_chars)):
+        args.append("".join(buf).strip())
+    return args
+
+
+def _unquote_excel_string(s: Optional[str]) -> Optional[str]:
+    """Decode Excel-style quoted string; return None if not quoted."""
+    if s is None:
+        return None
+    st = s.strip()
+    if len(st) >= 2 and st[0] == '"' and st[-1] == '"':
+        inner = st[1:-1]
+        return inner.replace('""', '"')
+    return None
+
+
+def parse_series_formula(formula: str) -> Optional[Dict[str, Optional[str]]]:
+    """Parse =SERIES into a dict of references; return None on failure."""
+    args_text = _extract_series_args_text(formula)
+    if args_text is None:
+        return None
+    parts = _split_top_level_args(args_text)
+    name_part = parts[0].strip() if len(parts) >= 1 and parts[0].strip() != "" else None
+    x_part = parts[1].strip() if len(parts) >= 2 and parts[1].strip() != "" else None
+    y_part = parts[2].strip() if len(parts) >= 3 and parts[2].strip() != "" else None
+    plot_order_part = (
+        parts[3].strip() if len(parts) >= 4 and parts[3].strip() != "" else None
+    )
+    bubble_part = (
+        parts[4].strip() if len(parts) >= 5 and parts[4].strip() != "" else None
+    )
+    name_literal = _unquote_excel_string(name_part)
+    name_range = None if name_literal is not None else name_part
+    return {
+        "name_range": name_range,
+        "x_range": x_part,
+        "y_range": y_part,
+        "plot_order": plot_order_part,
+        "bubble_size_range": bubble_part,
+        "name_literal": name_literal,
+    }
+
+
+def get_charts(sheet: xw.Sheet) -> List[Chart]:
+    """Parse charts in a sheet into Chart models; failed charts carry an error field."""
+    charts: List[Chart] = []
+    for ch in sheet.charts:
+        series_list: List[ChartSeries] = []
+        y_axis_title: str = ""
+        y_axis_range: List[int] = []
+        chart_type_label: str = "unknown"
+        error: Optional[str] = None
+
+        try:
+            chart_com = sheet.api.ChartObjects(ch.name).Chart
+            chart_type_num = chart_com.ChartType
+            chart_type_label = XL_CHART_TYPE_MAP.get(
+                chart_type_num, f"unknown_{chart_type_num}"
+            )
+
+            for s in chart_com.SeriesCollection():
+                parsed = parse_series_formula(getattr(s, "Formula", ""))
+                name_range = parsed["name_range"] if parsed else None
+                x_range = parsed["x_range"] if parsed else None
+                y_range = parsed["y_range"] if parsed else None
+
+                series_list.append(
+                    ChartSeries(
+                        name=s.Name,
+                        name_range=name_range,
+                        x_range=x_range,
+                        y_range=y_range,
+                    )
+                )
+
+            try:
+                y_axis = chart_com.Axes(2, 1)
+                if y_axis.HasTitle:
+                    y_axis_title = y_axis.AxisTitle.Text
+                y_axis_range = [y_axis.MinimumScale, y_axis.MaximumScale]
+            except Exception:
+                y_axis_title = ""
+                y_axis_range = []
+
+            title = chart_com.ChartTitle.Text if chart_com.HasTitle else None
+        except Exception:
+            logger.warning("Failed to parse chart; returning with error string.")
+            title = None
+            error = "Failed to build chart JSON structure"
+
+        charts.append(
+            Chart(
+                name=ch.name,
+                chart_type=chart_type_label,
+                title=title,
+                y_axis_title=y_axis_title,
+                y_axis_range=y_axis_range,  # type: ignore
+                series=series_list,
+                l=int(ch.left),
+                t=int(ch.top),
+                error=error,
+            )
+        )
+    return charts

exstruct/core/integrate.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Literal
+
+import logging
+
+import xlwings as xw
+
+from ..models import CellRow, Shape, SheetData, WorkbookData
+from .cells import (
+    detect_tables,
+    detect_tables_openpyxl,
+    extract_sheet_cells,
+)
+from .charts import get_charts
+from .shapes import get_shapes_with_position
+
+logger = logging.getLogger(__name__)
+_ALLOWED_MODES: set[str] = {"light", "standard", "verbose"}
+
+
+def _find_open_workbook(file_path: Path) -> xw.Book | None:
+    """Return an existing workbook if already open in Excel; otherwise None."""
+    try:
+        for app in xw.apps:
+            for wb in app.books:
+                try:
+                    if Path(wb.fullname).resolve() == file_path.resolve():
+                        return wb
+                except Exception:
+                    continue
+    except Exception:
+        return None
+    return None
+
+
+def _open_workbook(file_path: Path) -> tuple[xw.Book, bool]:
+    """
+    Open workbook:
+    - If already open, reuse and do not close Excel on exit.
+    - Otherwise create invisible Excel (visible=False) and close when done.
+    Returns (workbook, should_close_app).
+    """
+    existing = _find_open_workbook(file_path)
+    if existing:
+        return existing, False
+    app = xw.App(add_book=False, visible=False)
+    wb = app.books.open(str(file_path))
+    return wb, True
+
+
+def integrate_sheet_content(
+    cell_data: Dict[str, List[CellRow]],
+    shape_data: Dict[str, List[Shape]],
+    workbook: xw.Book,
+    mode: Literal["light", "standard", "verbose"] = "standard",
+) -> Dict[str, SheetData]:
+    """Integrate cells, shapes, charts, and tables into SheetData per sheet."""
+    result: Dict[str, SheetData] = {}
+    for sheet_name, rows in cell_data.items():
+        sheet_shapes = shape_data.get(sheet_name, [])
+        sheet = workbook.sheets[sheet_name]
+
+        sheet_model = SheetData(
+            rows=rows,
+            shapes=sheet_shapes,
+            charts=[] if mode == "light" else get_charts(sheet),
+            table_candidates=detect_tables(sheet),
+        )
+
+        result[sheet_name] = sheet_model
+    return result
+
+
+def extract_workbook(
+    file_path: Path, mode: Literal["light", "standard", "verbose"] = "standard"
+) -> WorkbookData:
+    """Extract workbook and return WorkbookData; fallback to cells+tables if Excel COM is unavailable."""
+    if mode not in _ALLOWED_MODES:
+        raise ValueError(f"Unsupported mode: {mode}")
+
+    cell_data = extract_sheet_cells(file_path)
+
+    def _cells_and_tables_only(reason: str) -> WorkbookData:
+        sheets: Dict[str, SheetData] = {}
+        for sheet_name, rows in cell_data.items():
+            try:
+                tables = detect_tables_openpyxl(file_path, sheet_name)
+            except Exception:
+                tables = []
+            sheets[sheet_name] = SheetData(
+                rows=rows,
+                shapes=[],
+                charts=[],
+                table_candidates=tables,
+            )
+        logger.warning(
+            "%s Falling back to cells+tables only; shapes and charts will be empty.",
+            reason,
+        )
+        return WorkbookData(book_name=file_path.name, sheets=sheets)
+
+    if mode == "light":
+        return _cells_and_tables_only("Light mode selected.")
+
+    try:
+        wb, close_app = _open_workbook(file_path)
+    except Exception as e:
+        return _cells_and_tables_only(
+            f"xlwings/Excel COM is unavailable. ({e!r})"
+        )
+
+    try:
+        try:
+            shape_data = get_shapes_with_position(wb, mode=mode)
+            merged = integrate_sheet_content(cell_data, shape_data, wb, mode=mode)
+            return WorkbookData(book_name=file_path.name, sheets=merged)
+        except Exception as e:
+            logger.warning("Shape extraction failed; falling back to cells+tables. (%r)", e)
+            return _cells_and_tables_only(
+                f"Shape extraction failed ({e!r})."
+            )
+    finally:
+        # Close only if we created the app to avoid shutting user sessions.
+        try:
+            if close_app:
+                app = wb.app
+                wb.close()
+                app.quit()
+        except Exception:
+            pass

exstruct/core/shapes.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional
+
+import xlwings as xw
+from xlwings import Book
+
+from ..models import Shape
+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."""
+    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)."""
+    dirs = ["E", "NE", "N", "NW", "W", "SW", "S", "SE"]
+    idx = int(((angle + 22.5) % 360) // 45)
+    return dirs[idx]
+
+
+def coord_to_cell_by_edges(
+    row_edges: List[float], col_edges: List[float], x: float, y: float
+) -> Optional[str]:
+    """Estimate cell address from coordinates and cumulative edges; return None if out of range."""
+
+    def find_index(edges, pos):
+        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) -> bool:
+    """Return True if Excel arrow style value indicates an arrowhead."""
+    try:
+        v = int(style_val)
+        return v != 0
+    except Exception:
+        return False
+
+
+def iter_shapes_recursive(shp):
+    """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:
+                    for s in iter_shapes_recursive(xl_shape):
+                        yield s
+    except Exception:
+        pass
+
+
+def _should_include_shape(
+    *,
+    text: str,
+    shape_type_num: Optional[int],
+    shape_type_str: Optional[str],
+    autoshape_type_str: Optional[str],
+    shape_name: Optional[str],
+    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).
+    """
+    if output_mode == "light":
+        return False
+
+    is_relationship = False
+    if shape_type_num in (3, 9):  # line/connector
+        is_relationship = True
+    if autoshape_type_str and ("Arrow" in autoshape_type_str or "Connector" in autoshape_type_str):
+        is_relationship = True
+    if shape_type_str and (
+        "Connector" in shape_type_str
+        or shape_type_str in ("Line", "ConnectLine")
+    ):
+        is_relationship = True
+    if shape_name and ("Connector" in shape_name or "Line" in shape_name):
+        is_relationship = True
+
+    if output_mode == "standard":
+        return bool(text) or is_relationship
+    # verbose
+    return True
+
+
+def get_shapes_with_position(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] = []
+        for root in sheet.shapes:
+            for shp in iter_shapes_recursive(root):
+                try:
+                    shape_name = getattr(shp, "name", None)
+                except Exception:
+                    shape_name = None
+                try:
+                    type_num = shp.api.Type
+                    shape_type_str = MSO_SHAPE_TYPE_MAP.get(
+                        type_num, f"Unknown({type_num})"
+                    )
+                    if shape_type_str in ["Chart", "Comment", "Picture", "FormControl"]:
+                        continue
+                    autoshape_type_str = None
+                    try:
+                        astype_num = shp.api.AutoShapeType
+                        autoshape_type_str = MSO_AUTO_SHAPE_TYPE_MAP.get(
+                            astype_num, f"Unknown({astype_num})"
+                        )
+                    except Exception:
+                        autoshape_type_str = None
+                except Exception:
+                    type_num = None
+                    shape_type_str = None
+                    autoshape_type_str = None
+                try:
+                    text = shp.text.strip() if shp.text else ""
+                except Exception:
+                    text = ""
+
+                if not _should_include_shape(
+                    text=text,
+                    shape_type_num=type_num,
+                    shape_type_str=shape_type_str,
+                    autoshape_type_str=autoshape_type_str,
+                    shape_name=shape_name,
+                    output_mode=mode,
+                ):
+                    continue
+
+                if autoshape_type_str and autoshape_type_str == "NotPrimitive" and shape_name:
+                    type_label = shape_name
+                else:
+                    type_label = (
+                        f"{shape_type_str}-{autoshape_type_str}"
+                        if autoshape_type_str
+                        else (shape_type_str or shape_name or "Unknown")
+                    )
+
+                shape_obj = Shape(
+                    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,
+                )
+                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
+
+                    if is_relationship_geom:
+                        angle = compute_line_angle_deg(float(shp.width), float(shp.height))
+                        shape_obj.direction = angle_to_compass(angle)  # type: ignore
+                        try:
+                            rot = float(shp.api.Rotation)
+                            if abs(rot) > 1e-6:
+                                shape_obj.rotation = rot
+                        except Exception:
+                            pass
+                        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
+                        except Exception:
+                            pass
+                    elif type_num == 1 and (autoshape_type_str and "Arrow" in autoshape_type_str):
+                        try:
+                            rot = float(shp.api.Rotation)
+                            if abs(rot) > 1e-6:
+                                shape_obj.rotation = rot
+                        except Exception:
+                            pass
+                except Exception:
+                    pass
+                shapes.append(shape_obj)
+        shape_data[sheet.name] = shapes
+    return shape_data