exstruct 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.3.0
+Version: 0.3.1
 Summary: Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines
 Keywords: excel,structure,data,exstruct
 Author: harumiWeb
@@ -55,18 +55,18 @@ 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)
+[![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)
 
 ![ExStruct Image](/docs/assets/icon.webp)
 
-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.
+ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, smartart, 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)
 
 ## 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 and `colors_map`. Size output is flag-controlled.
+- **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, 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.
@@ -435,6 +435,27 @@ This project is suitable for teams that:
 - Use CLI `--auto-page-breaks-dir` (COM only), `DestinationOptions.auto_page_breaks_dir` (preferred), or `export_auto_page_breaks(...)` to write per-auto-page-break files; the API raises `ValueError` if no auto page breaks exist.
 - `PrintAreaView` includes rows and table candidates inside the area, plus shapes/charts that overlap the area (size-less shapes are treated as points). `normalize=True` rebases row/col indices to the area origin.
 
+## Architecture
+
+ExStruct uses a pipeline-based architecture that separates
+extraction strategy (Backend) from orchestration (Pipeline)
+and semantic modeling.
+
+→ See: [docs/architecture/pipeline.md](docs/architecture/pipeline.md)
+
+## Contributing
+
+If you plan to extend ExStruct internals,
+please read the contributor architecture guide.
+
+→ [docs/contributors/architecture.md](docs/contributors/architecture.md)
+
+## Note on coverage
+
+The cell-structure inference logic (cells.py) relies on heuristic rules
+and Excel-specific behaviors. Full coverage is intentionally not pursued,
+as exhaustive testing would not reflect real-world reliability.
+
 ## License
 
 BSD-3-Clause. See `LICENSE` for details.

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

@@ -1,17 +1,17 @@
 # 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)
+[![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)
 
 ![ExStruct Image](/docs/assets/icon.webp)
 
-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.
+ExStruct reads Excel workbooks and outputs structured data (cells, table candidates, shapes, charts, smartart, 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)
 
 ## 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 and `colors_map`. Size output is flag-controlled.
+- **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, 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.
@@ -380,6 +380,27 @@ This project is suitable for teams that:
 - Use CLI `--auto-page-breaks-dir` (COM only), `DestinationOptions.auto_page_breaks_dir` (preferred), or `export_auto_page_breaks(...)` to write per-auto-page-break files; the API raises `ValueError` if no auto page breaks exist.
 - `PrintAreaView` includes rows and table candidates inside the area, plus shapes/charts that overlap the area (size-less shapes are treated as points). `normalize=True` rebases row/col indices to the area origin.
 
+## Architecture
+
+ExStruct uses a pipeline-based architecture that separates
+extraction strategy (Backend) from orchestration (Pipeline)
+and semantic modeling.
+
+→ See: [docs/architecture/pipeline.md](docs/architecture/pipeline.md)
+
+## Contributing
+
+If you plan to extend ExStruct internals,
+please read the contributor architecture guide.
+
+→ [docs/contributors/architecture.md](docs/contributors/architecture.md)
+
+## Note on coverage
+
+The cell-structure inference logic (cells.py) relies on heuristic rules
+and Excel-specific behaviors. Full coverage is intentionally not pursued,
+as exhaustive testing would not reflect real-world reliability.
+
 ## License
 
 BSD-3-Clause. See `LICENSE` for details.

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

@@ -1,128 +1,133 @@
-[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"
+[project]
+name = "exstruct"
+version = "0.3.1"
+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 = [
+    "codecov-cli>=11.2.6",
+    "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" # 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"
+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"
+build-docs = "mkdocs build && python scripts/gen_json_schema.py && python scripts/gen_model_docs.py"

{exstruct-0.3.0 → exstruct-0.3.1}/src/exstruct/core/backends/__init__.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
-from .base import Backend
-from .com_backend import ComBackend
-from .openpyxl_backend import OpenpyxlBackend
-
-__all__ = ["Backend", "ComBackend", "OpenpyxlBackend"]
+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 → exstruct-0.3.1}/src/exstruct/core/backends/base.py

@@ -1,38 +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."""
+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."""