exstruct 0.3.6__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.3.6
+Version: 0.4.0
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -39,6 +39,12 @@ Requires-Dist: pandas>=2.3.3
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: scipy>=1.16.3
 Requires-Dist: xlwings>=0.33.16
+Requires-Dist: pyyaml>=6.0.3 ; extra == 'all'
+Requires-Dist: python-toon>=0.1.3 ; extra == 'all'
+Requires-Dist: pypdfium2>=5.1.0 ; extra == 'all'
+Requires-Dist: pillow>=12.0.0 ; extra == 'all'
+Requires-Dist: mcp>=1.6.0,<2.0.0 ; extra == 'all'
+Requires-Dist: mcp>=1.6.0,<2.0.0 ; extra == 'mcp'
 Requires-Dist: pypdfium2>=5.1.0 ; extra == 'render'
 Requires-Dist: pillow>=12.0.0 ; extra == 'render'
 Requires-Dist: python-toon>=0.1.3 ; extra == 'toon'
@@ -48,6 +54,8 @@ Project-URL: Documentation, https://harumiweb.github.io/exstruct/
 Project-URL: Homepage, https://harumiweb.github.io/exstruct/
 Project-URL: Issues, https://github.com/harumiWeb/exstruct/issues
 Project-URL: Repository, https://github.com/harumiWeb/exstruct
+Provides-Extra: all
+Provides-Extra: mcp
 Provides-Extra: render
 Provides-Extra: toon
 Provides-Extra: yaml
@@ -67,6 +75,7 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 
 - **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.
+- **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.
@@ -106,6 +115,30 @@ exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
 
 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.
 
+## MCP Server (stdio)
+
+Install the MCP extras and run the stdio server:
+
+```bash
+pip install exstruct[mcp]
+exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
+```
+
+Available tools:
+
+- `exstruct.extract`
+- `exstruct.read_json_chunk`
+- `exstruct.validate_input`
+
+Notes:
+
+- Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
+- On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
+
+MCP Setup Guide for Each AI Agent:
+
+[MCP Server](https://harumiweb.github.io/exstruct/mcp/)
+
 ## Quick Start (Python)
 
 ```python
@@ -391,7 +424,6 @@ flowchart TD
 ```
 ````
 
-
 ## Example 2: General Application Form
 
 ### Excel Sheet

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

@@ -12,6 +12,7 @@ ExStruct reads Excel workbooks and outputs structured data (cells, table candida
 
 - **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.
+- **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.
@@ -51,6 +52,30 @@ exstruct input.xlsx --pdf --image          # PDF and PNGs (Excel required)
 
 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.
 
+## MCP Server (stdio)
+
+Install the MCP extras and run the stdio server:
+
+```bash
+pip install exstruct[mcp]
+exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
+```
+
+Available tools:
+
+- `exstruct.extract`
+- `exstruct.read_json_chunk`
+- `exstruct.validate_input`
+
+Notes:
+
+- Logs go to stderr (and optionally `--log-file`) to avoid contaminating stdio responses.
+- On Windows with Excel, standard/verbose can use COM for richer extraction. On non-Windows, COM is unavailable and extraction uses openpyxl-based fallbacks.
+
+MCP Setup Guide for Each AI Agent:
+
+[MCP Server](https://harumiweb.github.io/exstruct/mcp/)
+
 ## Quick Start (Python)
 
 ```python
@@ -336,7 +361,6 @@ flowchart TD
 ```
 ````
 
-
 ## Example 2: General Application Form
 
 ### Excel Sheet

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

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.3.6"
+version = "0.4.0"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -37,12 +37,21 @@ dev = [
 ]
 
 [project.optional-dependencies]
+all = [
+    "pyyaml>=6.0.3",
+    "python-toon>=0.1.3",
+    "pypdfium2>=5.1.0",
+    "Pillow>=12.0.0",
+    "mcp>=1.6.0,<2.0.0",
+]
 yaml = ["pyyaml>=6.0.3"]
 toon = ["python-toon>=0.1.3"]
 render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
+mcp = ["mcp>=1.6.0,<2.0.0"]
 
 [project.scripts]
 exstruct = "exstruct.cli.main:main"
+exstruct-mcp = "exstruct.mcp.server:main"
 
 [project.urls]
 Homepage = "https://harumiweb.github.io/exstruct/"
@@ -60,7 +69,10 @@ omit = [
 [tool.ruff]
 target-version = "py311"
 src = ["exstruct"]
+fix = true
 
+# 静的解析ルール
+[tool.ruff.lint]
 select = [
     "E",   # pycodestyle errors
     "W",   # pycodestyle warnings
@@ -75,43 +87,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]
@@ -124,6 +129,7 @@ markers = [
 ruff = "ruff check ."
 ruff-fix = "ruff check . --fix"
 mypy = "mypy src/exstruct --strict"
+precommit-run = "pre-commit run -a"
 test = "pytest -vv --cov=exstruct --cov-report=term-missing --cov-report=xml" # uv sync --extra render --extra toon
 test-unit = "pytest -vv -m \"not com and not render\" --cov=exstruct --cov-report=term-missing --cov-report=xml"
 test-com = "pytest -vv -m \"com\" --cov=exstruct --cov-report=term-missing --cov-report=xml"

{exstruct-0.3.6 → exstruct-0.4.0}/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.4.0}/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.4.0}/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.4.0}/src/exstruct/core/backends/openpyxl_backend.py

@@ -5,14 +5,17 @@ from __future__ import annotations
 from dataclasses import dataclass
 import logging
 from pathlib import Path
+from typing import Literal
 
 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,17 +102,40 @@ class OpenpyxlBackend:
         except Exception:
             return {}
 
-    def detect_tables(self, sheet_name: str) -> list[str]:
-        """Detect table candidates for a single sheet.
+    def extract_formulas_map(self) -> WorkbookFormulasMap | None:
+        """
+        Extract a mapping of workbook formulas for each sheet.
 
-        Args:
-            sheet_name: Target worksheet name.
+        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,
+        *,
+        mode: Literal["light", "standard", "verbose"] = "standard",
+    ) -> list[str]:
+        """
+        Detects table candidate ranges within the specified worksheet.
+
+        Parameters:
+            sheet_name (str): Name of the worksheet to analyze for table candidates.
+            mode (Literal["light", "standard", "verbose"]): Extraction mode, used to
+                adjust scan limits in openpyxl-based detection.
 
         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)
+            return detect_tables_openpyxl(self.file_path, sheet_name, mode=mode)
         except Exception:
             return []