exstruct 0.4.4__tar.gz → 0.5.0__tar.gz

{exstruct-0.4.4 → exstruct-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.4.4
+Version: 0.5.0
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -65,7 +65,8 @@ Description-Content-Type: text/markdown
 
 # ExStruct — Excel Structured Extraction Engine
 
-[![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![codecov](https://codecov.io/gh/harumiWeb/exstruct/graph/badge.svg?token=2XI1O8TTA9)](https://codecov.io/gh/harumiWeb/exstruct) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/harumiWeb/exstruct)
+[![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![codecov](https://codecov.io/gh/harumiWeb/exstruct/graph/badge.svg?token=2XI1O8TTA9)](https://codecov.io/gh/harumiWeb/exstruct) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/harumiWeb/exstruct) ![GitHub Repo stars](https://img.shields.io/github/stars/harumiWeb/exstruct)
+
 
 ![ExStruct Image](docs/assets/icon.webp)
 
@@ -120,15 +121,34 @@ exstruct input.xlsx --format toon          # TOON (needs python-toon)
 exstruct input.xlsx --sheets-dir sheets/   # split per sheet in chosen format
 exstruct input.xlsx --auto-page-breaks-dir auto_areas/  # COM only; option appears when available
 exstruct input.xlsx --print-areas-dir areas/  # split per print area (if any)
+exstruct input.xlsx --alpha-col           # output column keys as A, B, ..., AA
 exstruct input.xlsx --mode light           # cells + table candidates only
 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.
+By default, CLI keeps legacy 0-based numeric string column keys (`"0"`, `"1"`, ...). Use `--alpha-col` to emit Excel-style column keys (`"A"`, `"B"`, ...).
+Note: MCP `exstruct_extract` defaults to `options.alpha_col=true`, while CLI defaults to `false` unless `--alpha-col` is specified.
 
 ## MCP Server (stdio)
 
-Install the MCP extras and run the stdio server:
+### Quick Start with uvx (recommended)
+
+Run directly without installation:
+
+```bash
+uvx --from 'exstruct[mcp]' exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
+```
+
+Benefits:
+- No `pip install` required
+- Automatic dependency management
+- Environment isolation
+- Easy version pinning: `uvx --from 'exstruct[mcp]==0.4.4' exstruct-mcp`
+
+### Traditional Installation
+
+Alternatively, install with pip:
 
 ```bash
 pip install exstruct[mcp]
@@ -138,8 +158,12 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_make`
 - `exstruct_patch`
 - `exstruct_read_json_chunk`
+- `exstruct_read_range`
+- `exstruct_read_cells`
+- `exstruct_read_formulas`
 - `exstruct_validate_input`
 
 Notes:
@@ -147,6 +171,15 @@ Notes:
 - In MCP, `exstruct_extract` defaults to `options.alpha_col=true` (column keys: `A`, `B`, ...). Set `options.alpha_col=false` for legacy 0-based numeric string keys.
 - 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.
+- `exstruct_patch` supports `backend` selection:
+  - `auto` (default): prefer COM when available, otherwise openpyxl
+  - `com`: force COM (rejects `dry_run` / `return_inverse_ops` / `preflight_formula_check`)
+  - `openpyxl`: force openpyxl (`.xls` is not supported)
+- `exstruct_patch` response includes `engine` (`com` or `openpyxl`) to show the actual backend used. `restore_design_snapshot` remains openpyxl-only.
+- `exstruct_make` creates a new workbook and applies `ops` in one call (`out_path` required, `ops` optional).
+  - Supports `.xlsx` / `.xlsm` / `.xls`
+  - Initial sheet is normalized to `Sheet1`
+  - `.xls` requires COM and rejects `backend=openpyxl`
 
 MCP Setup Guide for Each AI Agent:
 

{exstruct-0.4.4 → exstruct-0.5.0}/README.md

@@ -1,6 +1,7 @@
 # ExStruct — Excel Structured Extraction Engine
 
-[![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![codecov](https://codecov.io/gh/harumiWeb/exstruct/graph/badge.svg?token=2XI1O8TTA9)](https://codecov.io/gh/harumiWeb/exstruct) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/harumiWeb/exstruct)
+[![PyPI version](https://badge.fury.io/py/exstruct.svg)](https://pypi.org/project/exstruct/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/exstruct?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/exstruct) ![Licence: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square) [![pytest](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml/badge.svg)](https://github.com/harumiWeb/exstruct/actions/workflows/pytest.yml) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e081cb4f634e4175b259eb7c34f54f60)](https://app.codacy.com/gh/harumiWeb/exstruct/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![codecov](https://codecov.io/gh/harumiWeb/exstruct/graph/badge.svg?token=2XI1O8TTA9)](https://codecov.io/gh/harumiWeb/exstruct) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/harumiWeb/exstruct) ![GitHub Repo stars](https://img.shields.io/github/stars/harumiWeb/exstruct)
+
 
 ![ExStruct Image](docs/assets/icon.webp)
 
@@ -55,15 +56,34 @@ exstruct input.xlsx --format toon          # TOON (needs python-toon)
 exstruct input.xlsx --sheets-dir sheets/   # split per sheet in chosen format
 exstruct input.xlsx --auto-page-breaks-dir auto_areas/  # COM only; option appears when available
 exstruct input.xlsx --print-areas-dir areas/  # split per print area (if any)
+exstruct input.xlsx --alpha-col           # output column keys as A, B, ..., AA
 exstruct input.xlsx --mode light           # cells + table candidates only
 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.
+By default, CLI keeps legacy 0-based numeric string column keys (`"0"`, `"1"`, ...). Use `--alpha-col` to emit Excel-style column keys (`"A"`, `"B"`, ...).
+Note: MCP `exstruct_extract` defaults to `options.alpha_col=true`, while CLI defaults to `false` unless `--alpha-col` is specified.
 
 ## MCP Server (stdio)
 
-Install the MCP extras and run the stdio server:
+### Quick Start with uvx (recommended)
+
+Run directly without installation:
+
+```bash
+uvx --from 'exstruct[mcp]' exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename
+```
+
+Benefits:
+- No `pip install` required
+- Automatic dependency management
+- Environment isolation
+- Easy version pinning: `uvx --from 'exstruct[mcp]==0.4.4' exstruct-mcp`
+
+### Traditional Installation
+
+Alternatively, install with pip:
 
 ```bash
 pip install exstruct[mcp]
@@ -73,8 +93,12 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_make`
 - `exstruct_patch`
 - `exstruct_read_json_chunk`
+- `exstruct_read_range`
+- `exstruct_read_cells`
+- `exstruct_read_formulas`
 - `exstruct_validate_input`
 
 Notes:
@@ -82,6 +106,15 @@ Notes:
 - In MCP, `exstruct_extract` defaults to `options.alpha_col=true` (column keys: `A`, `B`, ...). Set `options.alpha_col=false` for legacy 0-based numeric string keys.
 - 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.
+- `exstruct_patch` supports `backend` selection:
+  - `auto` (default): prefer COM when available, otherwise openpyxl
+  - `com`: force COM (rejects `dry_run` / `return_inverse_ops` / `preflight_formula_check`)
+  - `openpyxl`: force openpyxl (`.xls` is not supported)
+- `exstruct_patch` response includes `engine` (`com` or `openpyxl`) to show the actual backend used. `restore_design_snapshot` remains openpyxl-only.
+- `exstruct_make` creates a new workbook and applies `ops` in one call (`out_path` required, `ops` optional).
+  - Supports `.xlsx` / `.xlsm` / `.xls`
+  - Initial sheet is normalized to `Sheet1`
+  - `.xls` requires COM and rejects `backend=openpyxl`
 
 MCP Setup Guide for Each AI Agent:
 

{exstruct-0.4.4 → exstruct-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.4.4"
+version = "0.5.0"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -68,6 +68,7 @@ omit = [
     "tests/*",
     "*/test_*.py",
     "*/gen_py/*",
+    "src/exstruct/mcp/patch/engine/base.py",
 ]
 
 [tool.ruff]
@@ -136,9 +137,9 @@ 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"
+test = "pytest -vv --cov=exstruct --cov-report=term-missing --cov-report=xml --cov-fail-under=80" # 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 --cov-fail-under=80"
+test-com = "pytest -vv -m \"com\" --cov=exstruct --cov-report=term-missing --cov-report=xml --cov-fail-under=80"
 codecov-unit = "codecov-cli upload-process -f coverage.xml -F unit -C %CODECOV_SHA% -t %CODECOV_TOKEN%"
 codecov-com = "codecov-cli upload-process -f coverage.xml -F com -C %CODECOV_SHA% -t %CODECOV_TOKEN%"
 docs = "mkdocs serve"

{exstruct-0.4.4 → exstruct-0.5.0}/src/exstruct/mcp/__init__.py

@@ -18,12 +18,14 @@ from .extract_runner import (
 from .io import PathPolicy
 from .patch_runner import (
     FormulaIssue,
+    MakeRequest,
     PatchDiffItem,
     PatchErrorDetail,
     PatchOp,
     PatchRequest,
     PatchResult,
     PatchValue,
+    run_make,
     run_patch,
 )
 from .sheet_reader import (
@@ -40,8 +42,13 @@ from .sheet_reader import (
     read_range,
 )
 from .tools import (
+    DescribeOpToolInput,
+    DescribeOpToolOutput,
     ExtractToolInput,
     ExtractToolOutput,
+    ListOpsToolOutput,
+    MakeToolInput,
+    MakeToolOutput,
     PatchToolInput,
     PatchToolOutput,
     ReadCellsToolInput,
@@ -54,7 +61,10 @@ from .tools import (
     ReadRangeToolOutput,
     ValidateInputToolInput,
     ValidateInputToolOutput,
+    run_describe_op_tool,
     run_extract_tool,
+    run_list_ops_tool,
+    run_make_tool,
     run_patch_tool,
     run_read_cells_tool,
     run_read_formulas_tool,
@@ -69,6 +79,8 @@ from .validate_input import (
 )
 
 __all__ = [
+    "DescribeOpToolInput",
+    "DescribeOpToolOutput",
     "ExtractRequest",
     "ExtractResult",
     "ExtractOptions",
@@ -76,6 +88,10 @@ __all__ = [
     "ExtractToolOutput",
     "FormulaIssue",
     "FormulaReadItem",
+    "ListOpsToolOutput",
+    "MakeRequest",
+    "MakeToolInput",
+    "MakeToolOutput",
     "PatchDiffItem",
     "PatchErrorDetail",
     "PatchOp",
@@ -111,7 +127,11 @@ __all__ = [
     "read_json_chunk",
     "validate_input",
     "run_extract",
+    "run_describe_op_tool",
     "run_extract_tool",
+    "run_list_ops_tool",
+    "run_make",
+    "run_make_tool",
     "run_patch",
     "run_patch_tool",
     "read_cells",

{exstruct-0.4.4 → exstruct-0.5.0}/src/exstruct/mcp/extract_runner.py

@@ -9,6 +9,11 @@ from pydantic import BaseModel, Field
 from exstruct import ExtractionMode, process_excel
 
 from .io import PathPolicy
+from .shared.output_path import (
+    apply_conflict_policy as _shared_apply_conflict_policy,
+    next_available_path as _shared_next_available_path,
+    resolve_output_path as _shared_resolve_output_path,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -179,14 +184,14 @@ def _resolve_output_path(
     Raises:
         ValueError: If the path violates the policy.
     """
-    target_dir = out_dir or input_path.parent
-    target_dir = policy.ensure_allowed(target_dir) if policy else target_dir.resolve()
-    suffix = _format_suffix(fmt)
-    name = _normalize_output_name(input_path, out_name, suffix)
-    output_path = (target_dir / name).resolve()
-    if policy is not None:
-        output_path = policy.ensure_allowed(output_path)
-    return output_path
+    return _shared_resolve_output_path(
+        input_path,
+        out_dir=out_dir,
+        out_name=out_name,
+        policy=policy,
+        default_suffix=_format_suffix(fmt),
+        default_name_builder="same_stem",
+    )
 
 
 def _normalize_output_name(input_path: Path, out_name: str | None, suffix: str) -> str:
@@ -259,35 +264,12 @@ def _apply_conflict_policy(
     Returns:
         Tuple of (resolved output path, warning message or None, skipped flag).
     """
-    if not output_path.exists():
-        return output_path, None, False
-    if on_conflict == "skip":
-        return (
-            output_path,
-            f"Output exists; skipping write: {output_path.name}",
-            True,
-        )
-    if on_conflict == "rename":
-        renamed = _next_available_path(output_path)
-        return (
-            renamed,
-            f"Output exists; renamed to: {renamed.name}",
-            False,
-        )
-    return output_path, None, False
+    return _shared_apply_conflict_policy(output_path, on_conflict)
 
 
 def _next_available_path(path: Path) -> Path:
     """Return the next available path by appending a numeric suffix."""
-    if not path.exists():
-        return path
-    stem = path.stem
-    suffix = path.suffix
-    for idx in range(1, 10_000):
-        candidate = path.with_name(f"{stem}_{idx}{suffix}")
-        if not candidate.exists():
-            return candidate
-    raise RuntimeError(f"Failed to resolve unique path for {path}")
+    return _shared_next_available_path(path)
 
 
 def _try_read_workbook_meta(path: Path) -> tuple[WorkbookMeta | None, list[str]]:

{exstruct-0.4.4 → exstruct-0.5.0}/src/exstruct/mcp/io.py

@@ -33,14 +33,24 @@ class PathPolicy(BaseModel):
         Raises:
             ValueError: If the path is outside the root or denied by glob.
         """
-        resolved = path.resolve()
         root = self.normalize_root()
+        resolved = self._resolve_from_root(path, root)
         if resolved != root and root not in resolved.parents:
-            raise ValueError(f"Path is outside root: {resolved}")
+            raise ValueError(
+                "Path is outside root. "
+                f"resolved={resolved}, root={root}, "
+                "example_relative='outputs/book.xlsx'. "
+                "Use exstruct_get_runtime_info to inspect valid root-based paths."
+            )
         if self._is_denied(resolved, root):
             raise ValueError(f"Path is denied by policy: {resolved}")
         return resolved
 
+    def _resolve_from_root(self, path: Path, root: Path) -> Path:
+        """Resolve path using root as the base for relative inputs."""
+        candidate = path if path.is_absolute() else root / path
+        return candidate.resolve()
+
     def _is_denied(self, path: Path, root: Path) -> bool:
         """Check if a path is denied by glob rules.