exstruct 0.3.6__tar.gz → 0.3.7__tar.gz

{exstruct-0.3.6 → exstruct-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.3.6
+Version: 0.3.7
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -66,7 +66,8 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, smartart, 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, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Formula map extraction**: emits `formulas_map` (formula string -> cell coordinates) via openpyxl/COM; enabled by default in `verbose` or via `include_formulas_map`.
 - **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.

{exstruct-0.3.6 → exstruct-0.3.7}/README.md

@@ -11,7 +11,8 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, smartart, 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, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, smartart, merged cell ranges, print areas), `verbose` (all shapes with width/height, charts with size, merged cell ranges, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
+- **Formula map extraction**: emits `formulas_map` (formula string -> cell coordinates) via openpyxl/COM; enabled by default in `verbose` or via `include_formulas_map`.
 - **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.

{exstruct-0.3.6 → exstruct-0.3.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.3.6"
+version = "0.3.7"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -60,7 +60,10 @@ omit = [
 [tool.ruff]
 target-version = "py311"
 src = ["exstruct"]
+fix = true
 
+# 静的解析ルール
+[tool.ruff.lint]
 select = [
     "E",   # pycodestyle errors
     "W",   # pycodestyle warnings
@@ -75,43 +78,36 @@ select = [
 ]
 
 ignore = [
-    "E501",   # 行長は許容（Excel JSON は長くなりがち）
-    "B008",   # Pydantic の default_factory を誤検知するため
-    "ANN101", # self に型を要求されてしまうため
-    "ANN102", # cls も同様
+    "E501",   # 長い行は許容（Excel JSON は長くなりがち）
+    "B008",   # Pydantic の default_factory を使用するため
+    "ANN101", # self の型注釈は省略可能
+    "ANN102", # cls の型注釈は省略可能
 ]
 
-fix = true
-
-# 型ヒントのスタイル
-[tool.ruff.lint]
-extend-select = ["ANN"]
-
-# import の並び替え設定
-[tool.ruff.isort]
+# import の並び順
+[tool.ruff.lint.isort]
 combine-as-imports = true
 known-first-party = ["exstruct"]
 force-sort-within-sections = true
 
-# 複雑度チェック（関数の最大複雑度）
-[tool.ruff.mccabe]
+# 複雑度の最大値
+[tool.ruff.lint.mccabe]
 max-complexity = 12
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = ["N802", "N803", "N806"]
 
-
 [tool.mypy]
 packages = ["exstruct"]
 python_version = "3.11"
 
-# 外部ライブラリは一切チェックしない
+# 外部ライブラリの型情報がない場合は無視
 ignore_missing_imports = true
 
-# 自作コードは厳密にチェックする
+# 厳格モードを有効化
 strict = true
 
-# Pydantic v2 向け
+# Pydantic v2 対応
 plugins = ["pydantic.mypy"]
 
 [tool.pytest.ini_options]

{exstruct-0.3.6 → exstruct-0.3.7}/src/exstruct/__init__.py

@@ -90,36 +90,24 @@ ExtractionMode = Literal["light", "standard", "verbose"]
 
 def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> WorkbookData:
     """
-    Extract an Excel workbook into WorkbookData.
+    Extracts an Excel workbook into a WorkbookData structure.
 
-    Args:
-        file_path: Path to .xlsx/.xlsm/.xls.
-        mode: "light" / "standard" / "verbose"
-            - light: cells + table detection only (no COM, shapes/charts empty). Print areas via openpyxl.
-            - standard: texted shapes + arrows + charts (COM if available), print areas included. Shape/chart size is kept but hidden by default in output.
-            - verbose: all shapes (including textless) with size, charts with size, and colors_map.
+    Parameters:
+        file_path (str | Path): Path to the workbook file (.xlsx, .xlsm, .xls).
+        mode (ExtractionMode): Extraction detail level. "light" includes cells and table detection only (no COM, shapes/charts empty; print areas via openpyxl). "standard" includes texted shapes, arrows, charts (COM if available) and print areas. "verbose" also includes shape/chart sizes, cell link map, colors map, and formulas map.
 
     Returns:
-        WorkbookData containing sheets, rows, shapes, charts, and print areas.
-
-    Raises:
-        ValueError: If an invalid mode is provided.
-
-    Examples:
-        Extract with hyperlinks (verbose) and inspect table candidates:
-
-        >>> from exstruct import extract
-        >>> wb = extract("input.xlsx", mode="verbose")
-        >>> wb.sheets["Sheet1"].table_candidates
-        ['A1:B5']
+        WorkbookData: Parsed workbook representation containing sheets, rows, shapes, charts, and print areas.
     """
     include_links = True if mode == "verbose" else False
     include_colors_map = True if mode == "verbose" else None
+    include_formulas_map = True if mode == "verbose" else None
     engine = ExStructEngine(
         options=StructOptions(
             mode=mode,
             include_cell_links=include_links,
             include_colors_map=include_colors_map,
+            include_formulas_map=include_formulas_map,
         )
     )
     return engine.extract(file_path, mode=mode)

{exstruct-0.3.6 → exstruct-0.3.7}/src/exstruct/core/backends/base.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 from typing import Protocol
 
 from ...models import CellRow, PrintArea
-from ..cells import MergedCellRange, WorkbookColorsMap
+from ..cells import MergedCellRange, WorkbookColorsMap, WorkbookFormulasMap
 
 CellData = dict[str, list[CellRow]]
 PrintAreaData = dict[str, list[PrintArea]]
@@ -40,3 +40,11 @@ class Backend(Protocol):
 
     def extract_merged_cells(self) -> MergedCellData:
         """Extract merged cell ranges from the workbook."""
+
+    def extract_formulas_map(self) -> WorkbookFormulasMap | None:
+        """
+        Retrieve the workbook's formulas organized by worksheet.
+
+        Returns:
+            WorkbookFormulasMap | None: A mapping of worksheet identifiers to their formulas, or `None` if the backend cannot provide a formulas map.
+        """

{exstruct-0.3.6 → exstruct-0.3.7}/src/exstruct/core/backends/com_backend.py

@@ -9,7 +9,12 @@ from typing import Any, cast
 import xlwings as xw
 
 from ...models import PrintArea
-from ..cells import WorkbookColorsMap, extract_sheet_colors_map_com
+from ..cells import (
+    WorkbookColorsMap,
+    WorkbookFormulasMap,
+    extract_sheet_colors_map_com,
+    extract_sheet_formulas_map_com,
+)
 from ..ranges import parse_range_zero_based
 from .base import MergedCellData, PrintAreaData
 
@@ -58,14 +63,15 @@ class ComBackend:
     def extract_colors_map(
         self, *, include_default_background: bool, ignore_colors: set[str] | None
     ) -> WorkbookColorsMap | None:
-        """Extract colors_map via COM; logs and skips on failure.
+        """
+        Extract a workbook colors map using the Excel COM API.
 
-        Args:
-            include_default_background: Whether to include default backgrounds.
-            ignore_colors: Optional set of color keys to ignore.
+        Parameters:
+            include_default_background (bool): Include the workbook's default background color in the resulting map.
+            ignore_colors (set[str] | None): Optional set of color keys to exclude from the map.
 
         Returns:
-            WorkbookColorsMap or None when extraction fails.
+            WorkbookColorsMap | None: A mapping of workbook color definitions when extraction succeeds, or `None` if COM extraction fails.
         """
         try:
             return extract_sheet_colors_map_com(
@@ -80,11 +86,30 @@ class ComBackend:
             )
             return None
 
+    def extract_formulas_map(self) -> WorkbookFormulasMap | None:
+        """
+        Extracts the workbook's formulas map using COM.
+
+        Returns:
+            WorkbookFormulasMap or None: The extracted formulas map, or `None` if extraction failed.
+        """
+        try:
+            return extract_sheet_formulas_map_com(self.workbook)
+        except Exception as exc:
+            logger.warning(
+                "COM formula map extraction failed; skipping formulas_map. (%r)",
+                exc,
+            )
+            return None
+
     def extract_auto_page_breaks(self) -> PrintAreaData:
-        """Compute auto page-break rectangles per sheet using Excel COM.
+        """
+        Compute auto page-break rectangles for each worksheet using Excel COM.
+
+        For each sheet, determine the sheet's print area (PageSetup.PrintArea or the used range) and split it into sub-rectangles along Excel's horizontal and vertical page breaks; parts that reference a different sheet are ignored. If extraction for a sheet fails, the sheet is skipped and a warning is logged.
 
         Returns:
-            Mapping of sheet name to auto page-break areas.
+            Mapping from sheet name to a list of PrintArea entries. Each PrintArea describes a rectangular region with `r1` and `r2` as 1-based row indices and `c1` and `c2` as 0-based column indices.
         """
         results: PrintAreaData = {}
         for sheet in self.workbook.sheets:

{exstruct-0.3.6 → exstruct-0.3.7}/src/exstruct/core/backends/openpyxl_backend.py

@@ -9,10 +9,12 @@ from pathlib import Path
 from ...models import PrintArea
 from ..cells import (
     WorkbookColorsMap,
+    WorkbookFormulasMap,
     detect_tables_openpyxl,
     extract_sheet_cells,
     extract_sheet_cells_with_links,
     extract_sheet_colors_map,
+    extract_sheet_formulas_map,
     extract_sheet_merged_cells,
 )
 from ..ranges import parse_range_zero_based
@@ -99,14 +101,30 @@ class OpenpyxlBackend:
         except Exception:
             return {}
 
+    def extract_formulas_map(self) -> WorkbookFormulasMap | None:
+        """
+        Extract a mapping of workbook formulas for each sheet.
+
+        Returns:
+            WorkbookFormulasMap | None: A mapping from sheet name to its formulas, or `None` if extraction fails.
+        """
+        try:
+            return extract_sheet_formulas_map(self.file_path)
+        except Exception as exc:
+            logger.warning(
+                "Formula map extraction failed; skipping formulas_map. (%r)", exc
+            )
+            return None
+
     def detect_tables(self, sheet_name: str) -> list[str]:
-        """Detect table candidates for a single sheet.
+        """
+        Detects table candidate ranges within the specified worksheet.
 
-        Args:
-            sheet_name: Target worksheet name.
+        Parameters:
+            sheet_name (str): Name of the worksheet to analyze for table candidates.
 
         Returns:
-            List of table candidate ranges.
+            list[str]: Detected table candidate ranges as A1-style range strings; empty list if none are found or detection fails.
         """
         try:
             return detect_tables_openpyxl(self.file_path, sheet_name)

{exstruct-0.3.6 → exstruct-0.3.7}/src/exstruct/core/cells.py

@@ -56,13 +56,41 @@ class WorkbookColorsMap:
     sheets: dict[str, SheetColorsMap]
 
     def get_sheet(self, sheet_name: str) -> SheetColorsMap | None:
-        """Return the colors map for a sheet if available.
+        """
+        Retrieve the SheetColorsMap for a worksheet by name.
 
-        Args:
-            sheet_name: Target worksheet name.
+        Parameters:
+            sheet_name (str): Name of the worksheet to retrieve.
 
         Returns:
-            SheetColorsMap for the sheet, or None if missing.
+            SheetColorsMap | None: The sheet's color map if present, `None` otherwise.
+        """
+        return self.sheets.get(sheet_name)
+
+
+@dataclass(frozen=True)
+class SheetFormulasMap:
+    """Formula map for a single worksheet."""
+
+    sheet_name: str
+    formulas_map: dict[str, list[tuple[int, int]]]
+
+
+@dataclass(frozen=True)
+class WorkbookFormulasMap:
+    """Formula maps for all worksheets in a workbook."""
+
+    sheets: dict[str, SheetFormulasMap]
+
+    def get_sheet(self, sheet_name: str) -> SheetFormulasMap | None:
+        """
+        Retrieve the formulas map for a worksheet.
+
+        Parameters:
+            sheet_name (str): Name of the worksheet to look up.
+
+        Returns:
+            SheetFormulasMap | None: The sheet's formulas map if present, `None` if the worksheet is not found.
         """
         return self.sheets.get(sheet_name)
 
@@ -102,22 +130,79 @@ def extract_sheet_colors_map(
     return WorkbookColorsMap(sheets=sheets)
 
 
+def extract_sheet_formulas_map(file_path: Path) -> WorkbookFormulasMap:
+    """
+    Extract normalized formula strings from every worksheet in the workbook.
+
+    Parameters:
+        file_path (Path): Path to the Excel workbook to read.
+
+    Returns:
+        WorkbookFormulasMap: Mapping of sheet names to SheetFormulasMap objects. Each SheetFormulasMap contains a mapping from normalized formula strings (each beginning with "=") to a list of cell coordinates (row, column) where that formula occurs.
+    """
+    sheets: dict[str, SheetFormulasMap] = {}
+    with openpyxl_workbook(file_path, data_only=False, read_only=False) as wb:
+        for ws in wb.worksheets:
+            sheet_map = _extract_sheet_formulas(ws)
+            sheets[ws.title] = sheet_map
+    return WorkbookFormulasMap(sheets=sheets)
+
+
+def extract_sheet_formulas_map_com(workbook: xw.Book) -> WorkbookFormulasMap:
+    """
+    Collects and normalizes formulas from every worksheet in an xlwings workbook into per-sheet mappings.
+
+    Parameters:
+        workbook: xlwings Book instance whose sheets will be scanned for formulas.
+
+    Returns:
+        WorkbookFormulasMap: maps sheet names to SheetFormulasMap objects. Each SheetFormulasMap.formulas_map maps a normalized formula string (consistent representation, e.g., beginning with "=") to a list of (row, column) tuples where row is 1-based and column is 0-based.
+    """
+    sheets: dict[str, SheetFormulasMap] = {}
+    for sheet in workbook.sheets:
+        formulas_map: dict[str, list[tuple[int, int]]] = {}
+        used = sheet.used_range
+        start_row = int(getattr(used, "row", 1))
+        start_col = int(getattr(used, "column", 1))
+        max_row = used.last_cell.row
+        max_col = used.last_cell.column
+        if max_row <= 0 or max_col <= 0:
+            sheets[sheet.name] = SheetFormulasMap(
+                sheet_name=sheet.name, formulas_map=formulas_map
+            )
+            continue
+        rng = sheet.range((start_row, start_col), (max_row, max_col))
+        matrix = _normalize_matrix(rng.formula)
+        for r_offset, row in enumerate(matrix):
+            for c_offset, value in enumerate(row):
+                normalized = _normalize_formula_from_com(value)
+                if normalized is None:
+                    continue
+                row_index = start_row + r_offset
+                col_index = start_col + c_offset - 1
+                formulas_map.setdefault(normalized, []).append((row_index, col_index))
+        sheets[sheet.name] = SheetFormulasMap(
+            sheet_name=sheet.name, formulas_map=formulas_map
+        )
+    return WorkbookFormulasMap(sheets=sheets)
+
+
 def extract_sheet_colors_map_com(
     workbook: xw.Book,
     *,
     include_default_background: bool,
     ignore_colors: set[str] | None,
 ) -> WorkbookColorsMap:
-    """Extract background colors for each worksheet via COM display formats.
+    """
+    Extract per-sheet background color maps using the workbook's COM/display-format interfaces.
 
-    Args:
-        workbook: xlwings workbook instance.
-        include_default_background: Whether to include default (white) backgrounds
-            within the used range.
-        ignore_colors: Optional set of color keys to ignore.
+    Parameters:
+        workbook (xw.Book): xlwings workbook whose sheets will be inspected.
+        include_default_background (bool): If true, include default background colors (e.g., white) for cells inside each sheet's used range.
+        ignore_colors (set[str] | None): Optional set of normalized color keys to exclude from results.
 
     Returns:
-        WorkbookColorsMap containing per-sheet color maps.
+        WorkbookColorsMap: Mapping of sheet names to SheetColorsMap containing detected background color positions for each worksheet.
     """
     _prepare_workbook_for_display_format(workbook)
     sheets: dict[str, SheetColorsMap] = {}
@@ -133,15 +218,16 @@ def extract_sheet_colors_map_com(
 def _extract_sheet_colors(
     ws: Worksheet, include_default_background: bool, ignore_colors: set[str] | None
 ) -> SheetColorsMap:
-    """Extract background colors for a single worksheet.
+    """
+    Extract the background color locations present on a single worksheet.
 
-    Args:
-        ws: Target worksheet.
-        include_default_background: Whether to include default (white) backgrounds.
-        ignore_colors: Optional set of color keys to ignore.
+    Parameters:
+        ws (Worksheet): Worksheet to scan.
+        include_default_background (bool): If true, treat cells with the workbook default/background color as having a color key.
+        ignore_colors (set[str] | None): Optional set of color keys to ignore (keys are normalized before comparison).
 
     Returns:
-        SheetColorsMap for the worksheet.
+        SheetColorsMap: Mapping from normalized color key to a list of cell coordinates where that color appears. Coordinates are tuples (row, col) where `row` is 1-based and `col` is 0-based.
     """
     min_row, min_col, max_row, max_col = _get_used_range_bounds(ws)
     colors_map: dict[str, list[tuple[int, int]]] = {}
@@ -165,18 +251,90 @@ def _extract_sheet_colors(
     return SheetColorsMap(sheet_name=ws.title, colors_map=colors_map)
 
 
+def _extract_sheet_formulas(ws: Worksheet) -> SheetFormulasMap:
+    """
+    Collect normalized formula strings from a worksheet and group their cell coordinates.
+
+    Parameters:
+        ws (Worksheet): Worksheet to scan for formulas.
+
+    Returns:
+        SheetFormulasMap: container with the sheet's name and a mapping from each normalized formula string (prefixed with "=") to a list of cell coordinates as (row, zero-based-column).
+    """
+    min_row, min_col, max_row, max_col = _get_used_range_bounds(ws)
+    formulas_map: dict[str, list[tuple[int, int]]] = {}
+    if min_row > max_row or min_col > max_col:
+        return SheetFormulasMap(sheet_name=ws.title, formulas_map=formulas_map)
+
+    for row in ws.iter_rows(
+        min_row=min_row, max_row=max_row, min_col=min_col, max_col=max_col
+    ):
+        for cell in row:
+            if getattr(cell, "data_type", None) != "f":
+                continue
+            normalized = _normalize_formula_value(getattr(cell, "value", None))
+            if normalized is None:
+                continue
+            formulas_map.setdefault(normalized, []).append((cell.row, cell.col_idx - 1))
+    return SheetFormulasMap(sheet_name=ws.title, formulas_map=formulas_map)
+
+
+def _normalize_formula_value(value: object) -> str | None:
+    """Normalize a formula string for openpyxl cells.
+
+    Args:
+        value: Raw cell value.
+
+    Returns:
+        Formula string with leading "=", or None when empty.
+    """
+    if value is None:
+        return None
+    array_text = getattr(value, "text", None)
+    if array_text is not None:
+        text = str(array_text)
+    else:
+        text = str(value)
+    if text == "":
+        return None
+    if not text.startswith("="):
+        return f"={text}"
+    return text
+
+
+def _normalize_formula_from_com(value: object) -> str | None:
+    """
+    Normalize a COM-returned cell formula into a string that begins with '='.
+
+    Parameters:
+        value (object): Raw value returned from COM for a cell's formula.
+
+    Returns:
+        str | None: The input string if it is non-empty and starts with '=', `None` otherwise.
+    """
+    if value is None or not isinstance(value, str):
+        return None
+    text = value
+    if text == "":
+        return None
+    if not text.startswith("="):
+        return None
+    return text
+
+
 def _extract_sheet_colors_com(
     sheet: xw.Sheet, include_default_background: bool, ignore_colors: set[str] | None
 ) -> SheetColorsMap:
-    """Extract background colors for a single worksheet via COM.
+    """
+    Extract per-sheet background color mapping using COM/DisplayFormat.
 
-    Args:
-        sheet: Target worksheet.
-        include_default_background: Whether to include default (white) backgrounds.
-        ignore_colors: Optional set of color keys to ignore.
+    Parameters:
+        sheet (xw.Sheet): xlwings sheet object to inspect.
+        include_default_background (bool): If True, include cells whose background is the workbook default color.
+        ignore_colors (set[str] | None): Optional set of normalized color keys to exclude from the result.
 
     Returns:
-        SheetColorsMap for the worksheet.
+        SheetColorsMap: Mapping from normalized color key (hex/theme/index canonical form) to a list of cell coordinates where that color appears. Each coordinate is a tuple (row, col) where `row` is the worksheet row number (1-based) and `col` is the zero-based column index.
     """
     colors_map: dict[str, list[tuple[int, int]]] = {}
     used = sheet.used_range

exstruct-0.3.7/src/exstruct/core/integrate.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from ..models import WorkbookData
+from .pipeline import resolve_extraction_inputs, run_extraction_pipeline
+
+
+def extract_workbook(  # noqa: C901
+    file_path: str | Path,
+    mode: Literal["light", "standard", "verbose"] = "standard",
+    *,
+    include_cell_links: bool | None = None,
+    include_print_areas: bool | None = None,
+    include_auto_page_breaks: bool = False,
+    include_colors_map: bool | None = None,
+    include_default_background: bool = False,
+    ignore_colors: set[str] | None = None,
+    include_formulas_map: bool | None = None,
+    include_merged_cells: bool | None = None,
+    include_merged_values_in_rows: bool = True,
+) -> WorkbookData:
+    """
+    Extract a workbook into a structured WorkbookData representation.
+
+    May fall back to cells+tables extraction if Excel COM automation is unavailable.
+
+    Parameters:
+        file_path (str | Path): Path to the workbook file.
+        mode (Literal['light', 'standard', 'verbose']): Extraction mode that controls detail level.
+        include_cell_links (bool | None): Include cell hyperlinks; `None` uses mode defaults.
+        include_print_areas (bool | None): Include print areas; `None` defaults to True.
+        include_auto_page_breaks (bool): Include automatic page break information.
+        include_colors_map (bool | None): Include a colors map; `None` uses mode defaults.
+        include_default_background (bool): Include default background color when present.
+        ignore_colors (set[str] | None): Set of color keys to ignore during color mapping.
+        include_formulas_map (bool | None): Include a map of cell formulas; `None` uses mode defaults.
+        include_merged_cells (bool | None): Include merged cell ranges; `None` uses mode defaults.
+        include_merged_values_in_rows (bool): Preserve merged cell values in row-wise output.
+
+    Returns:
+        WorkbookData: The extracted workbook representation.
+
+    Raises:
+        ValueError: If `mode` is not one of "light", "standard", or "verbose".
+    """
+    inputs = resolve_extraction_inputs(
+        file_path,
+        mode=mode,
+        include_cell_links=include_cell_links,
+        include_print_areas=include_print_areas,
+        include_auto_page_breaks=include_auto_page_breaks,
+        include_colors_map=include_colors_map,
+        include_default_background=include_default_background,
+        ignore_colors=ignore_colors,
+        include_formulas_map=include_formulas_map,
+        include_merged_cells=include_merged_cells,
+        include_merged_values_in_rows=include_merged_values_in_rows,
+    )
+    result = run_extraction_pipeline(inputs)
+    return result.workbook

{exstruct-0.3.6 → exstruct-0.3.7}/src/exstruct/core/modeling.py

@@ -27,6 +27,7 @@ class SheetRawData:
         table_candidates: Detected table ranges.
         print_areas: Extracted print areas.
         auto_print_areas: Extracted auto page-break areas.
+        formulas_map: Mapping of formula strings to (row, column) positions.
         colors_map: Mapping of color keys to (row, column) positions.
         merged_cells: Extracted merged cell ranges.
     """
@@ -37,6 +38,7 @@ class SheetRawData:
     table_candidates: list[str]
     print_areas: list[PrintArea]
     auto_print_areas: list[PrintArea]
+    formulas_map: dict[str, list[tuple[int, int]]]
     colors_map: dict[str, list[tuple[int, int]]]
     merged_cells: list[MergedCellRange]
 
@@ -70,6 +72,7 @@ def build_sheet_data(raw: SheetRawData) -> SheetData:
         table_candidates=raw.table_candidates,
         print_areas=raw.print_areas,
         auto_print_areas=raw.auto_print_areas,
+        formulas_map=raw.formulas_map,
         colors_map=raw.colors_map,
         merged_cells=_build_merged_cells(raw.merged_cells),
     )