exstruct 0.2.80__tar.gz → 0.3.0__tar.gz

{exstruct-0.2.80 → exstruct-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.80
+Version: 0.3.0
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -61,12 +61,12 @@ Description-Content-Type: text/markdown
 
 ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
 
-[日本版README](README.ja.md)
+[日本版 README](README.ja.md)
 
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, 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, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks. Size output is flag-controlled.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
 - **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.
@@ -189,7 +189,7 @@ Use higher thresholds to reduce false positives; lower them if true tables are m
 
 - **light**: cells + table candidates (no COM needed).
 - **standard**: texted shapes + arrows, charts (COM if available), table candidates. Hyperlinks are off unless `include_cell_links=True`.
-- **verbose**: all shapes (with width/height), charts, table candidates, and cell hyperlinks.
+- **verbose**: all shapes (with width/height), charts, table candidates, cell hyperlinks, and `colors_map`.
 
 ## Error Handling / Fallbacks
 
@@ -218,7 +218,6 @@ To show how well exstruct can structure Excel, we parse a workbook that combines
 (Screenshot below is the actual sample Excel sheet)
 ![Sample Excel](/docs/assets/demo_sheet.png)
 Sample workbook: `sample/sample.xlsx`
-Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -274,12 +273,14 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
       ],
       "shapes": [
         {
+          "id": 1,
           "text": "開始",
           "l": 148,
           "t": 220,
           "type": "AutoShape-FlowchartProcess"
         },
         {
+          "id": 2,
           "text": "入力データ読み込み",
           "l": 132,
           "t": 282,
@@ -291,6 +292,8 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
           "type": "AutoShape-Mixed",
           "begin_arrow_style": 1,
           "end_arrow_style": 2,
+          "begin_id": 1,
+          "end_id": 2,
           "direction": "N"
         },
         ...
@@ -374,14 +377,14 @@ flowchart TD
 
     A --> B
     B --> C
-    C -- no --> D
-    C -- yes --> E
+    C -->|yes| D
+    C --> H
+    D --> E
     E --> F
-    F -- yes --> E
-    F -- no --> G
-    G --> H
-    H -- yes --> I
-    H -- no --> J
+    F --> G
+    G -->|yes| I
+    G -->|no| J
+    H --> J
     I --> J
 ```
 ````
@@ -390,6 +393,12 @@ From this we can see:
 
 **exstruct's JSON is already in a format that AI can read and reason over directly.**
 
+Other LLM inference samples using this library can be found in the following directory:
+
+- [Basic Excel](sample/basic/)
+- [Flowchart](sample/flowchart/)
+- [Gantt Chart](sample/gantt_chart/)
+
 ### 4. Summary
 
 This benchmark confirms exstruct can:
@@ -414,6 +423,7 @@ ExStruct is used primarily as a **library**, not a service.
 - Forking and internal modification are expected in enterprise use
 
 This project is suitable for teams that:
+
 - need transparency over black-box tools
 - are comfortable maintaining internal forks if necessary
 

{exstruct-0.2.80 → exstruct-0.3.0}/README.md

@@ -6,12 +6,12 @@
 
 ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, print areas/views, auto page-break areas, hyperlinks) as JSON by default, with optional YAML/TOON formats. It targets both COM/Excel environments (rich extraction) and non-COM environments (cells + table candidates + print areas), with tunable detection heuristics and multiple output modes to fit LLM/RAG pipelines.
 
-[日本版README](README.ja.md)
+[日本版 README](README.ja.md)
 
 ## Features
 
 - **Excel → Structured JSON**: cells, shapes, charts, 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, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks. Size output is flag-controlled.
+- **Output modes**: `light` (cells + table candidates + print areas; no COM, shapes/charts empty), `standard` (texted shapes + arrows, charts, print areas), `verbose` (all shapes with width/height, charts with size, print areas). Verbose also emits cell hyperlinks and `colors_map`. Size output is flag-controlled.
 - **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.
@@ -134,7 +134,7 @@ Use higher thresholds to reduce false positives; lower them if true tables are m
 
 - **light**: cells + table candidates (no COM needed).
 - **standard**: texted shapes + arrows, charts (COM if available), table candidates. Hyperlinks are off unless `include_cell_links=True`.
-- **verbose**: all shapes (with width/height), charts, table candidates, and cell hyperlinks.
+- **verbose**: all shapes (with width/height), charts, table candidates, cell hyperlinks, and `colors_map`.
 
 ## Error Handling / Fallbacks
 
@@ -163,7 +163,6 @@ To show how well exstruct can structure Excel, we parse a workbook that combines
 (Screenshot below is the actual sample Excel sheet)
 ![Sample Excel](/docs/assets/demo_sheet.png)
 Sample workbook: `sample/sample.xlsx`
-Sample workbook: `sample/sample.xlsx`
 
 ### 1. Input: Excel Sheet Overview
 
@@ -219,12 +218,14 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
       ],
       "shapes": [
         {
+          "id": 1,
           "text": "開始",
           "l": 148,
           "t": 220,
           "type": "AutoShape-FlowchartProcess"
         },
         {
+          "id": 2,
           "text": "入力データ読み込み",
           "l": 132,
           "t": 282,
@@ -236,6 +237,8 @@ Below is a **shortened JSON output example** from parsing this Excel workbook.
           "type": "AutoShape-Mixed",
           "begin_arrow_style": 1,
           "end_arrow_style": 2,
+          "begin_id": 1,
+          "end_id": 2,
           "direction": "N"
         },
         ...
@@ -319,14 +322,14 @@ flowchart TD
 
     A --> B
     B --> C
-    C -- no --> D
-    C -- yes --> E
+    C -->|yes| D
+    C --> H
+    D --> E
     E --> F
-    F -- yes --> E
-    F -- no --> G
-    G --> H
-    H -- yes --> I
-    H -- no --> J
+    F --> G
+    G -->|yes| I
+    G -->|no| J
+    H --> J
     I --> J
 ```
 ````
@@ -335,6 +338,12 @@ From this we can see:
 
 **exstruct's JSON is already in a format that AI can read and reason over directly.**
 
+Other LLM inference samples using this library can be found in the following directory:
+
+- [Basic Excel](sample/basic/)
+- [Flowchart](sample/flowchart/)
+- [Gantt Chart](sample/gantt_chart/)
+
 ### 4. Summary
 
 This benchmark confirms exstruct can:
@@ -359,6 +368,7 @@ ExStruct is used primarily as a **library**, not a service.
 - Forking and internal modification are expected in enterprise use
 
 This project is suitable for teams that:
+
 - need transparency over black-box tools
 - are comfortable maintaining internal forks if necessary
 

{exstruct-0.2.80 → exstruct-0.3.0}/pyproject.toml

@@ -1,119 +1,128 @@
-[project]
-name = "exstruct"
-version = "0.2.80"
-description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
-readme = "README.md"
-license = { file = "LICENSE" }
-keywords = ["excel", "structure", "data", "exstruct"]
-authors = [
-    { name = "harumiWeb"}
-]
-requires-python = ">=3.11"
-dependencies = [
-    "numpy>=2.3.5",
-    "openpyxl>=3.1.5",
-    "pandas>=2.3.3",
-    "pydantic>=2.12.5",
-    "scipy>=1.16.3",
-    "xlwings>=0.33.16",
-]
-
-[build-system]
-requires = ["uv_build>=0.8.4,<0.9.0"]
-build-backend = "uv_build"
-
-[dependency-groups]
-dev = [
-    "mkdocs-material>=9.7.0",
-    "mkdocstrings-python>=2.0.1",
-    "mypy>=1.19.0",
-    "pre-commit>=4.5.0",
-    "pytest>=9.0.1",
-    "pytest-cov>=7.0.0",
-    "pytest-mock>=3.15.1",
-    "ruff>=0.14.8",
-]
-
-[project.optional-dependencies]
-yaml = ["pyyaml>=6.0.3"]
-toon = ["python-toon>=0.1.3"]
-render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
-
-[project.scripts]
-exstruct = "exstruct.cli.main:main"
-
-[project.urls]
-Homepage = "https://harumiweb.github.io/exstruct/"
-Repository = "https://github.com/harumiWeb/exstruct"
-Issues = "https://github.com/harumiWeb/exstruct/issues"
-Documentation = "https://harumiweb.github.io/exstruct/"
-
-[tool.coverage.run]
-omit = [
-    "tests/*",
-    "*/test_*.py",
-    "*/gen_py/*",
-]
-
-[tool.ruff]
-target-version = "py311"
-src = ["exstruct"]
-
-select = [
-    "E",   # pycodestyle errors
-    "W",   # pycodestyle warnings
-    "F",   # pyflakes
-    "I",   # import sorting
-    "UP",  # pyupgrade
-    "B",   # flake8-bugbear
-    "N",   # naming
-    "C90", # complexity
-    "A",   # flake8-builtins
-    "ANN", # type annotations
-]
-
-ignore = [
-    "E501",   # 行長は許容（Excel JSON は長くなりがち）
-    "B008",   # Pydantic の default_factory を誤検知するため
-    "ANN101", # self に型を要求されてしまうため
-    "ANN102", # cls も同様
-]
-
-fix = true
-
-# 型ヒントのスタイル
-[tool.ruff.lint]
-extend-select = ["ANN"]
-
-# import の並び替え設定
-[tool.ruff.isort]
-combine-as-imports = true
-known-first-party = ["exstruct"]
-force-sort-within-sections = true
-
-# 複雑度チェック（関数の最大複雑度）
-[tool.ruff.mccabe]
-max-complexity = 12
-
-[tool.ruff.per-file-ignores]
-"tests/**/*.py" = ["N802", "N803", "N806"]
-
-
-[tool.mypy]
-packages = ["exstruct"]
-python_version = "3.11"
-
-# 外部ライブラリは一切チェックしない
-ignore_missing_imports = true
-
-# 自作コードは厳密にチェックする
-strict = true
-
-# Pydantic v2 向け
-plugins = ["pydantic.mypy"]
-
-[tool.pytest.ini_options]
-markers = [
-    "com: requires Excel COM (Windows + Excel)",
-    "render: requires Excel COM and pypdfium2; set RUN_RENDER_SMOKE=1 to enable",
-]
+[project]
+name = "exstruct"
+version = "0.3.0"
+description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
+readme = "README.md"
+license = { file = "LICENSE" }
+keywords = ["excel", "structure", "data", "exstruct"]
+authors = [
+    { name = "harumiWeb"}
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=2.3.5",
+    "openpyxl>=3.1.5",
+    "pandas>=2.3.3",
+    "pydantic>=2.12.5",
+    "scipy>=1.16.3",
+    "xlwings>=0.33.16",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.7.0",
+    "mkdocstrings-python>=2.0.1",
+    "mypy>=1.19.0",
+    "pre-commit>=4.5.0",
+    "pytest>=9.0.1",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.14.8",
+    "taskipy>=1.14.1",
+]
+
+[project.optional-dependencies]
+yaml = ["pyyaml>=6.0.3"]
+toon = ["python-toon>=0.1.3"]
+render = ["pypdfium2>=5.1.0", "Pillow>=12.0.0"]
+
+[project.scripts]
+exstruct = "exstruct.cli.main:main"
+
+[project.urls]
+Homepage = "https://harumiweb.github.io/exstruct/"
+Repository = "https://github.com/harumiWeb/exstruct"
+Issues = "https://github.com/harumiWeb/exstruct/issues"
+Documentation = "https://harumiweb.github.io/exstruct/"
+
+[tool.coverage.run]
+omit = [
+    "tests/*",
+    "*/test_*.py",
+    "*/gen_py/*",
+]
+
+[tool.ruff]
+target-version = "py311"
+src = ["exstruct"]
+
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # import sorting
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "N",   # naming
+    "C90", # complexity
+    "A",   # flake8-builtins
+    "ANN", # type annotations
+]
+
+ignore = [
+    "E501",   # 行長は許容（Excel JSON は長くなりがち）
+    "B008",   # Pydantic の default_factory を誤検知するため
+    "ANN101", # self に型を要求されてしまうため
+    "ANN102", # cls も同様
+]
+
+fix = true
+
+# 型ヒントのスタイル
+[tool.ruff.lint]
+extend-select = ["ANN"]
+
+# import の並び替え設定
+[tool.ruff.isort]
+combine-as-imports = true
+known-first-party = ["exstruct"]
+force-sort-within-sections = true
+
+# 複雑度チェック（関数の最大複雑度）
+[tool.ruff.mccabe]
+max-complexity = 12
+
+[tool.ruff.per-file-ignores]
+"tests/**/*.py" = ["N802", "N803", "N806"]
+
+
+[tool.mypy]
+packages = ["exstruct"]
+python_version = "3.11"
+
+# 外部ライブラリは一切チェックしない
+ignore_missing_imports = true
+
+# 自作コードは厳密にチェックする
+strict = true
+
+# Pydantic v2 向け
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+markers = [
+    "com: requires Excel COM (Windows + Excel)",
+    "render: requires Excel COM and pypdfium2; set RUN_RENDER_SMOKE=1 to enable",
+]
+
+[tool.taskipy.tasks]
+ruff = "ruff check ."
+ruff-fix = "ruff check . --fix"
+mypy = "mypy src/exstruct --strict"
+test = "pytest -vv --cov=exstruct --cov-report=term-missing --cov-report=xml"
+docs = "mkdocs serve"
+build-docs = "mkdocs build && python scripts/gen_json_schema.py && python scripts/gen_model_docs.py"

{exstruct-0.2.80 → exstruct-0.3.0}/src/exstruct/__init__.py

@@ -7,9 +7,11 @@ from typing import Literal, TextIO
 from .core.cells import set_table_detection_params
 from .core.integrate import extract_workbook
 from .engine import (
+    ColorsOptions,
     DestinationOptions,
     ExStructEngine,
     FilterOptions,
+    FormatOptions,
     OutputOptions,
     StructOptions,
 )
@@ -75,7 +77,9 @@ __all__ = [
     "StructOptions",
     "OutputOptions",
     "FilterOptions",
+    "FormatOptions",
     "DestinationOptions",
+    "ColorsOptions",
     "serialize_workbook",
     "export_auto_page_breaks",
 ]
@@ -93,7 +97,7 @@ def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> Workboo
         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.
+            - verbose: all shapes (including textless) with size, charts with size, and colors_map.
 
     Returns:
         WorkbookData containing sheets, rows, shapes, charts, and print areas.
@@ -110,8 +114,13 @@ def extract(file_path: str | Path, mode: ExtractionMode = "standard") -> Workboo
         ['A1:B5']
     """
     include_links = True if mode == "verbose" else False
+    include_colors_map = True if mode == "verbose" else None
     engine = ExStructEngine(
-        options=StructOptions(mode=mode, include_cell_links=include_links)
+        options=StructOptions(
+            mode=mode,
+            include_cell_links=include_links,
+            include_colors_map=include_colors_map,
+        )
     )
     return engine.extract(file_path, mode=mode)
 
@@ -358,16 +367,18 @@ def process_excel(
     engine = ExStructEngine(
         options=StructOptions(mode=mode),
         output=OutputOptions(
-            fmt=out_fmt,
-            pretty=pretty,
-            indent=indent,
-            sheets_dir=sheets_dir,
-            print_areas_dir=print_areas_dir,
-            auto_page_breaks_dir=auto_page_breaks_dir,
-            include_print_areas=None if mode == "light" else True,
-            include_shape_size=True if mode == "verbose" else False,
-            include_chart_size=True if mode == "verbose" else False,
-            stream=stream,
+            format=FormatOptions(fmt=out_fmt, pretty=pretty, indent=indent),
+            filters=FilterOptions(
+                include_print_areas=None if mode == "light" else True,
+                include_shape_size=True if mode == "verbose" else False,
+                include_chart_size=True if mode == "verbose" else False,
+            ),
+            destinations=DestinationOptions(
+                sheets_dir=sheets_dir,
+                print_areas_dir=print_areas_dir,
+                auto_page_breaks_dir=auto_page_breaks_dir,
+                stream=stream,
+            ),
         ),
     )
     engine.process(

{exstruct-0.2.80 → exstruct-0.3.0}/src/exstruct/cli/main.py

@@ -2,11 +2,30 @@ from __future__ import annotations
 
 import argparse
 from pathlib import Path
+import sys
 
 from exstruct import process_excel
 from exstruct.cli.availability import ComAvailability, get_com_availability
 
 
+def _ensure_utf8_stdout() -> None:
+    """Reconfigure stdout to UTF-8 when supported.
+
+    Windows consoles default to cp932 and can raise encoding errors when piping
+    non-ASCII characters. Reconfiguring prevents failures without affecting
+    environments that already default to UTF-8.
+    """
+
+    stdout = sys.stdout
+    if not hasattr(stdout, "reconfigure"):
+        return
+    reconfigure = stdout.reconfigure
+    try:
+        reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        return
+
+
 def _add_auto_page_breaks_argument(
     parser: argparse.ArgumentParser, availability: ComAvailability
 ) -> None:
@@ -102,6 +121,7 @@ def main(argv: list[str] | None = None) -> int:
     Returns:
         Exit code (0 for success, 1 for failure).
     """
+    _ensure_utf8_stdout()
     parser = build_parser()
     args = parser.parse_args(argv)
 

exstruct-0.3.0/src/exstruct/core/backends/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .base import Backend
+from .com_backend import ComBackend
+from .openpyxl_backend import OpenpyxlBackend
+
+__all__ = ["Backend", "ComBackend", "OpenpyxlBackend"]

exstruct-0.3.0/src/exstruct/core/backends/base.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from ...models import CellRow, PrintArea
+from ..cells import WorkbookColorsMap
+
+CellData = dict[str, list[CellRow]]
+PrintAreaData = dict[str, list[PrintArea]]
+
+
+@dataclass(frozen=True)
+class BackendConfig:
+    """Configuration options shared across backends.
+
+    Attributes:
+        include_default_background: Whether to include default background colors.
+        ignore_colors: Optional set of color keys to ignore.
+    """
+
+    include_default_background: bool
+    ignore_colors: set[str] | None
+
+
+class Backend(Protocol):
+    """Protocol for backend implementations."""
+
+    def extract_cells(self, *, include_links: bool) -> CellData:
+        """Extract cell rows from the workbook."""
+
+    def extract_print_areas(self) -> PrintAreaData:
+        """Extract print areas from the workbook."""
+
+    def extract_colors_map(
+        self, *, include_default_background: bool, ignore_colors: set[str] | None
+    ) -> WorkbookColorsMap | None:
+        """Extract colors map from the workbook."""