exstruct 0.2.90__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.90
+Version: 0.3.0
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -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
 

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

@@ -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
 

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

@@ -1,119 +1,128 @@
-[project]
-name = "exstruct"
-version = "0.2.90"
-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.90 → exstruct-0.3.0}/src/exstruct/__init__.py

@@ -11,6 +11,7 @@ from .engine import (
     DestinationOptions,
     ExStructEngine,
     FilterOptions,
+    FormatOptions,
     OutputOptions,
     StructOptions,
 )
@@ -76,6 +77,7 @@ __all__ = [
     "StructOptions",
     "OutputOptions",
     "FilterOptions",
+    "FormatOptions",
     "DestinationOptions",
     "ColorsOptions",
     "serialize_workbook",
@@ -95,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.
@@ -365,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.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."""

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

@@ -0,0 +1,226 @@
+"""COM backend for Excel workbook extraction via xlwings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from typing import Any, cast
+
+import xlwings as xw
+
+from ...models import PrintArea
+from ..cells import WorkbookColorsMap, extract_sheet_colors_map_com
+from ..ranges import parse_range_zero_based
+from .base import PrintAreaData
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ComBackend:
+    """COM-based backend for extraction tasks.
+
+    Attributes:
+        workbook: xlwings workbook instance.
+    """
+
+    workbook: xw.Book
+
+    def extract_print_areas(self) -> PrintAreaData:
+        """Extract print areas per sheet via xlwings/COM.
+
+        Returns:
+            Mapping of sheet name to print area list.
+        """
+        areas: PrintAreaData = {}
+        for sheet in self.workbook.sheets:
+            raw = ""
+            try:
+                raw = sheet.api.PageSetup.PrintArea or ""
+            except Exception as exc:
+                logger.warning(
+                    "Failed to read print area via COM for sheet '%s'. (%r)",
+                    sheet.name,
+                    exc,
+                )
+            if not raw:
+                continue
+            for part in str(raw).split(","):
+                parsed = _parse_print_area_range(part)
+                if not parsed:
+                    continue
+                r1, c1, r2, c2 = parsed
+                areas.setdefault(sheet.name, []).append(
+                    PrintArea(r1=r1 + 1, c1=c1, r2=r2 + 1, c2=c2)
+                )
+        return areas
+
+    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.
+
+        Args:
+            include_default_background: Whether to include default backgrounds.
+            ignore_colors: Optional set of color keys to ignore.
+
+        Returns:
+            WorkbookColorsMap or None when extraction fails.
+        """
+        try:
+            return extract_sheet_colors_map_com(
+                self.workbook,
+                include_default_background=include_default_background,
+                ignore_colors=ignore_colors,
+            )
+        except Exception as exc:
+            logger.warning(
+                "COM color map extraction failed; falling back to openpyxl. (%r)",
+                exc,
+            )
+            return None
+
+    def extract_auto_page_breaks(self) -> PrintAreaData:
+        """Compute auto page-break rectangles per sheet using Excel COM.
+
+        Returns:
+            Mapping of sheet name to auto page-break areas.
+        """
+        results: PrintAreaData = {}
+        for sheet in self.workbook.sheets:
+            ws_api: Any | None = None
+            original_display: bool | None = None
+            failed = False
+            try:
+                ws_api = cast(Any, sheet.api)
+                original_display = ws_api.DisplayPageBreaks
+                ws_api.DisplayPageBreaks = True
+                print_area = ws_api.PageSetup.PrintArea or ws_api.UsedRange.Address
+                parts_raw = _split_csv_respecting_quotes(str(print_area))
+                area_parts: list[str] = []
+                for part in parts_raw:
+                    rng = _normalize_area_for_sheet(part, sheet.name)
+                    if rng:
+                        area_parts.append(rng)
+                hpb = cast(Any, ws_api.HPageBreaks)
+                vpb = cast(Any, ws_api.VPageBreaks)
+                h_break_rows = [
+                    hpb.Item(i).Location.Row for i in range(1, int(hpb.Count) + 1)
+                ]
+                v_break_cols = [
+                    vpb.Item(i).Location.Column for i in range(1, int(vpb.Count) + 1)
+                ]
+                for addr in area_parts:
+                    range_obj = cast(Any, ws_api.Range(addr))
+                    min_row = int(range_obj.Row)
+                    max_row = min_row + int(range_obj.Rows.Count) - 1
+                    min_col = int(range_obj.Column)
+                    max_col = min_col + int(range_obj.Columns.Count) - 1
+                    rows = (
+                        [min_row]
+                        + [r for r in h_break_rows if min_row < r <= max_row]
+                        + [max_row + 1]
+                    )
+                    cols = (
+                        [min_col]
+                        + [c for c in v_break_cols if min_col < c <= max_col]
+                        + [max_col + 1]
+                    )
+                    for i in range(len(rows) - 1):
+                        r1, r2 = rows[i], rows[i + 1] - 1
+                        for j in range(len(cols) - 1):
+                            c1, c2 = cols[j], cols[j + 1] - 1
+                            results.setdefault(sheet.name, []).append(
+                                PrintArea(r1=r1, c1=c1 - 1, r2=r2, c2=c2 - 1)
+                            )
+            except Exception as exc:
+                logger.warning(
+                    "Failed to extract auto page breaks via COM for sheet '%s'. (%r)",
+                    sheet.name,
+                    exc,
+                )
+                failed = True
+            finally:
+                if ws_api is not None and original_display is not None:
+                    try:
+                        ws_api.DisplayPageBreaks = original_display
+                    except Exception as exc:
+                        logger.debug(
+                            "Failed to restore DisplayPageBreaks for sheet '%s'. (%r)",
+                            sheet.name,
+                            exc,
+                        )
+            if failed:
+                continue
+        return results
+
+
+def _parse_print_area_range(range_str: str) -> tuple[int, int, int, int] | None:
+    """Parse an Excel range string into zero-based coordinates.
+
+    Args:
+        range_str: Excel range string.
+
+    Returns:
+        Zero-based (r1, c1, r2, c2) tuple or None on failure.
+    """
+    bounds = parse_range_zero_based(range_str)
+    if bounds is None:
+        return None
+    return (bounds.r1, bounds.c1, bounds.r2, bounds.c2)
+
+
+def _normalize_area_for_sheet(part: str, ws_name: str) -> str | None:
+    """Strip sheet name from a range part when it matches the target sheet.
+
+    Args:
+        part: Raw range string part.
+        ws_name: Target worksheet name.
+
+    Returns:
+        Range without sheet prefix, or None if not matching.
+    """
+    s = part.strip()
+    if "!" not in s:
+        return s
+    sheet, rng = s.rsplit("!", 1)
+    sheet = sheet.strip()
+    if sheet.startswith("'") and sheet.endswith("'"):
+        sheet = sheet[1:-1].replace("''", "'")
+    return rng if sheet == ws_name else None
+
+
+def _split_csv_respecting_quotes(raw: str) -> list[str]:
+    """Split a CSV-like string while keeping commas inside single quotes intact.
+
+    Args:
+        raw: Raw CSV-like string.
+
+    Returns:
+        List of split parts.
+    """
+    parts: list[str] = []
+    buf: list[str] = []
+    in_quote = False
+    i = 0
+    while i < len(raw):
+        ch = raw[i]
+        if ch == "'":
+            if in_quote and i + 1 < len(raw) and raw[i + 1] == "'":
+                buf.append("''")
+                i += 2
+                continue
+            in_quote = not in_quote
+            buf.append(ch)
+            i += 1
+            continue
+        if ch == "," and not in_quote:
+            parts.append("".join(buf).strip())
+            buf = []
+            i += 1
+            continue
+        buf.append(ch)
+        i += 1
+    if buf:
+        parts.append("".join(buf).strip())
+    return [p for p in parts if p]