exstruct 0.5.1__tar.gz → 0.5.3__tar.gz

{exstruct-0.5.1 → exstruct-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.5.1
+Version: 0.5.3
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -158,6 +158,7 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_capture_sheet_images`
 - `exstruct_make`
 - `exstruct_patch`
 - `exstruct_read_json_chunk`
@@ -169,6 +170,12 @@ Available tools:
 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.
+- `exstruct_capture_sheet_images` is COM-only (Experimental) and supports optional `sheet` / `range` targeting (`A1:B2`, `Sheet1!A1:B2`, `'Sheet 1'!A1:B2`). When `out_dir` is omitted, it creates a unique `<workbook_stem>_images` directory under MCP `--root`.
+- MCP server startup sets `EXSTRUCT_RENDER_SUBPROCESS=1` by default (`setdefault`). If you prefer in-process rendering, set `EXSTRUCT_RENDER_SUBPROCESS=0` before launching the server.
+- Timeout tuning for `exstruct_capture_sheet_images`: `EXSTRUCT_MCP_CAPTURE_SHEET_IMAGES_TIMEOUT_SEC` (tool timeout), `EXSTRUCT_RENDER_SUBPROCESS_STARTUP_TIMEOUT_SEC` (worker startup), `EXSTRUCT_RENDER_SUBPROCESS_JOIN_TIMEOUT_SEC` (primary wait budget), `EXSTRUCT_RENDER_SUBPROCESS_RESULT_TIMEOUT_SEC` (post-exit grace).
+- Subprocess errors are stage-aware (`stage=startup|join|result|worker`) so MCP clients can distinguish bootstrap failures vs timeout vs worker-side rendering errors.
+- Trade-off of `EXSTRUCT_RENDER_SUBPROCESS=1`: subprocess startup/coordination overhead and dependency on worker-side module resolution.
+- Trade-off of `EXSTRUCT_RENDER_SUBPROCESS=0`: less crash isolation and higher memory pressure risk in long-running processes.
 - 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:
@@ -177,8 +184,13 @@ Notes:
   - `openpyxl`: force openpyxl (`.xls` is not supported)
 - `create_chart` is COM-only (`backend="openpyxl"` is not allowed for requests that include it), and it also rejects `dry_run` / `return_inverse_ops` / `preflight_formula_check`.
 - `create_chart` `chart_type` supports: `line`, `column`, `bar`, `area`, `pie`, `doughnut`, `scatter`, `radar` (aliases: `column_clustered`, `bar_clustered`, `xy_scatter`, `donut`).
-- `create_chart` and `apply_table_style` cannot be combined in one request (split into separate calls).
+- `create_chart` `data_range` accepts either one range string or `list[str]` (multi-series), and `data_range` / `category_range` both support sheet-qualified ranges (`Sheet2!A1:B10`, `'Sales Data'!A1:B10`).
+- `create_chart` supports optional explicit labels: `chart_title`, `x_axis_title`, `y_axis_title`.
+- `create_chart` and `apply_table_style` can be combined in one request when the backend resolves to COM (`backend="com"` or `backend="auto"` with COM available).
+- For stable `apply_table_style` COM runs on Windows, ensure desktop Excel is installed/runnable and the target `range` is a contiguous header-included A1 range.
+- `exstruct_patch` error detail may include `error_code` / `failed_field` / `raw_com_message`; table-related codes include `table_style_invalid`, `list_object_add_failed`, and `com_api_missing`.
 - `exstruct_patch` response includes `engine` (`com` or `openpyxl`) to show the actual backend used. `restore_design_snapshot` remains openpyxl-only.
+- Use `exstruct_make` for new workbook creation and `exstruct_patch` for editing existing workbooks.
 - `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`

{exstruct-0.5.1 → exstruct-0.5.3}/README.md

@@ -93,6 +93,7 @@ exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict re
 Available tools:
 
 - `exstruct_extract`
+- `exstruct_capture_sheet_images`
 - `exstruct_make`
 - `exstruct_patch`
 - `exstruct_read_json_chunk`
@@ -104,6 +105,12 @@ Available tools:
 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.
+- `exstruct_capture_sheet_images` is COM-only (Experimental) and supports optional `sheet` / `range` targeting (`A1:B2`, `Sheet1!A1:B2`, `'Sheet 1'!A1:B2`). When `out_dir` is omitted, it creates a unique `<workbook_stem>_images` directory under MCP `--root`.
+- MCP server startup sets `EXSTRUCT_RENDER_SUBPROCESS=1` by default (`setdefault`). If you prefer in-process rendering, set `EXSTRUCT_RENDER_SUBPROCESS=0` before launching the server.
+- Timeout tuning for `exstruct_capture_sheet_images`: `EXSTRUCT_MCP_CAPTURE_SHEET_IMAGES_TIMEOUT_SEC` (tool timeout), `EXSTRUCT_RENDER_SUBPROCESS_STARTUP_TIMEOUT_SEC` (worker startup), `EXSTRUCT_RENDER_SUBPROCESS_JOIN_TIMEOUT_SEC` (primary wait budget), `EXSTRUCT_RENDER_SUBPROCESS_RESULT_TIMEOUT_SEC` (post-exit grace).
+- Subprocess errors are stage-aware (`stage=startup|join|result|worker`) so MCP clients can distinguish bootstrap failures vs timeout vs worker-side rendering errors.
+- Trade-off of `EXSTRUCT_RENDER_SUBPROCESS=1`: subprocess startup/coordination overhead and dependency on worker-side module resolution.
+- Trade-off of `EXSTRUCT_RENDER_SUBPROCESS=0`: less crash isolation and higher memory pressure risk in long-running processes.
 - 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:
@@ -112,8 +119,13 @@ Notes:
   - `openpyxl`: force openpyxl (`.xls` is not supported)
 - `create_chart` is COM-only (`backend="openpyxl"` is not allowed for requests that include it), and it also rejects `dry_run` / `return_inverse_ops` / `preflight_formula_check`.
 - `create_chart` `chart_type` supports: `line`, `column`, `bar`, `area`, `pie`, `doughnut`, `scatter`, `radar` (aliases: `column_clustered`, `bar_clustered`, `xy_scatter`, `donut`).
-- `create_chart` and `apply_table_style` cannot be combined in one request (split into separate calls).
+- `create_chart` `data_range` accepts either one range string or `list[str]` (multi-series), and `data_range` / `category_range` both support sheet-qualified ranges (`Sheet2!A1:B10`, `'Sales Data'!A1:B10`).
+- `create_chart` supports optional explicit labels: `chart_title`, `x_axis_title`, `y_axis_title`.
+- `create_chart` and `apply_table_style` can be combined in one request when the backend resolves to COM (`backend="com"` or `backend="auto"` with COM available).
+- For stable `apply_table_style` COM runs on Windows, ensure desktop Excel is installed/runnable and the target `range` is a contiguous header-included A1 range.
+- `exstruct_patch` error detail may include `error_code` / `failed_field` / `raw_com_message`; table-related codes include `table_style_invalid`, `list_object_add_failed`, and `com_api_missing`.
 - `exstruct_patch` response includes `engine` (`com` or `openpyxl`) to show the actual backend used. `restore_design_snapshot` remains openpyxl-only.
+- Use `exstruct_make` for new workbook creation and `exstruct_patch` for editing existing workbooks.
 - `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`

{exstruct-0.5.1 → exstruct-0.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.5.1"
+version = "0.5.3"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }

{exstruct-0.5.1 → exstruct-0.5.3}/src/exstruct/mcp/__init__.py

@@ -28,6 +28,11 @@ from .patch_runner import (
     run_make,
     run_patch,
 )
+from .render_runner import (
+    CaptureSheetImagesRequest,
+    CaptureSheetImagesResult,
+    run_capture_sheet_images,
+)
 from .sheet_reader import (
     CellReadItem,
     FormulaReadItem,
@@ -42,6 +47,8 @@ from .sheet_reader import (
     read_range,
 )
 from .tools import (
+    CaptureSheetImagesToolInput,
+    CaptureSheetImagesToolOutput,
     DescribeOpToolInput,
     DescribeOpToolOutput,
     ExtractToolInput,
@@ -61,6 +68,7 @@ from .tools import (
     ReadRangeToolOutput,
     ValidateInputToolInput,
     ValidateInputToolOutput,
+    run_capture_sheet_images_tool,
     run_describe_op_tool,
     run_extract_tool,
     run_list_ops_tool,
@@ -79,6 +87,10 @@ from .validate_input import (
 )
 
 __all__ = [
+    "CaptureSheetImagesRequest",
+    "CaptureSheetImagesResult",
+    "CaptureSheetImagesToolInput",
+    "CaptureSheetImagesToolOutput",
     "DescribeOpToolInput",
     "DescribeOpToolOutput",
     "ExtractRequest",
@@ -133,6 +145,8 @@ __all__ = [
     "run_make",
     "run_make_tool",
     "run_patch",
+    "run_capture_sheet_images",
+    "run_capture_sheet_images_tool",
     "run_patch_tool",
     "read_cells",
     "read_formulas",

{exstruct-0.5.1 → exstruct-0.5.3}/src/exstruct/mcp/op_schema.py

@@ -380,7 +380,6 @@ _PATCH_OP_SCHEMA_BY_NAME: dict[str, PatchOpSchema] = {
             "range must include header row",
             "table name must be unique when provided",
             "range must not intersect existing table",
-            "backend='com' falls back to openpyxl with warning",
         ],
         example={
             "op": "apply_table_style",
@@ -401,9 +400,14 @@ _PATCH_OP_SCHEMA_BY_NAME: dict[str, PatchOpSchema] = {
             "height",
             "titles_from_data",
             "series_from_rows",
+            "chart_title",
+            "x_axis_title",
+            "y_axis_title",
         ],
         constraints=[
             "chart_type in {'line','column','bar','area','pie','doughnut','scatter','radar'}",
+            "data_range accepts A1 range string or list[str] for multi-series input",
+            "data_range/category_range allow sheet-qualified ranges like 'Sheet2!A1:B10'",
             "width/height must be > 0 when provided",
             "chart_name must be unique in sheet when provided",
             "backend='openpyxl' is not supported",
@@ -412,14 +416,17 @@ _PATCH_OP_SCHEMA_BY_NAME: dict[str, PatchOpSchema] = {
             "op": "create_chart",
             "sheet": "Sheet1",
             "chart_type": "line",
-            "data_range": "A1:C10",
-            "category_range": "A2:A10",
+            "data_range": ["A2:A10", "C2:C10", "D2:D10"],
+            "category_range": "B2:B10",
             "anchor_cell": "E2",
             "chart_name": "SalesTrend",
             "width": 360,
             "height": 220,
             "titles_from_data": True,
             "series_from_rows": False,
+            "chart_title": "Sales trend",
+            "x_axis_title": "Month",
+            "y_axis_title": "Amount",
         },
     ),
     "restore_design_snapshot": PatchOpSchema(