PyPI - exstruct - Versions diffs - 0.2.90__tar.gz → 0.3.1__tar.gz - Mend

exstruct 0.2.90tar.gz → 0.3.1tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

{exstruct-0.2.90 → exstruct-0.3.1}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exstruct
-Version: 0.2.90
+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.
@@ -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
@@ -436,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.2.90 → exstruct-0.3.1}/README.md RENAMED Viewed

@@ -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.
@@ -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
@@ -381,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.2.90 → exstruct-0.3.1}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "exstruct"
-version = "0.2.90"
+version = "0.3.1"
 description = "Excel to structured JSON (tables, shapes, charts) for LLM/RAG pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -24,6 +24,7 @@ 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",
@@ -32,6 +33,7 @@ dev = [
     "pytest-cov>=7.0.0",
     "pytest-mock>=3.15.1",
     "ruff>=0.14.8",
+    "taskipy>=1.14.1",
 ]
 [project.optional-dependencies]
@@ -117,3 +119,15 @@ 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.2.90 → exstruct-0.3.1}/src/exstruct/__init__.py RENAMED Viewed

@@ -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.1/src/exstruct/core/backends/__init__.py ADDED Viewed

@@ -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.1/src/exstruct/core/backends/base.py ADDED Viewed

@@ -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.1/src/exstruct/core/backends/com_backend.py ADDED Viewed

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

exstruct-0.3.1/src/exstruct/core/backends/openpyxl_backend.py ADDED Viewed

@@ -0,0 +1,179 @@
+"""Openpyxl backend for Excel workbook extraction."""
+from __future__ import annotations
+from dataclasses import dataclass
+import logging
+from pathlib import Path
+from ...models import PrintArea
+from ..cells import (
+    WorkbookColorsMap,
+    detect_tables_openpyxl,
+    extract_sheet_cells,
+    extract_sheet_cells_with_links,
+    extract_sheet_colors_map,
+)
+from ..ranges import parse_range_zero_based
+from ..workbook import openpyxl_workbook
+from .base import CellData, PrintAreaData
+logger = logging.getLogger(__name__)
+@dataclass(frozen=True)
+class OpenpyxlBackend:
+    """Openpyxl-based backend for extraction tasks.
+    Attributes:
+        file_path: Path to the workbook file.
+    """
+    file_path: Path
+    def extract_cells(self, *, include_links: bool) -> CellData:
+        """Extract cell rows from the workbook.
+        Args:
+            include_links: Whether to include hyperlinks.
+        Returns:
+            Mapping of sheet name to cell rows.
+        """
+        return (
+            extract_sheet_cells_with_links(self.file_path)
+            if include_links
+            else extract_sheet_cells(self.file_path)
+        )
+    def extract_print_areas(self) -> PrintAreaData:
+        """Extract print areas per sheet using openpyxl defined names.
+        Returns:
+            Mapping of sheet name to print area list.
+        """
+        try:
+            with openpyxl_workbook(
+                self.file_path, data_only=True, read_only=False
+            ) as wb:
+                areas = _extract_print_areas_from_defined_names(wb)
+                if not areas:
+                    areas = _extract_print_areas_from_sheet_props(wb)
+                return areas
+        except Exception:
+            return {}
+    def extract_colors_map(
+        self, *, include_default_background: bool, ignore_colors: set[str] | None
+    ) -> WorkbookColorsMap | None:
+        """Extract colors_map using openpyxl.
+        Args:
+            include_default_background: Whether to include default background colors.
+            ignore_colors: Optional set of color keys to ignore.
+        Returns:
+            WorkbookColorsMap or None when extraction fails.
+        """
+        try:
+            return extract_sheet_colors_map(
+                self.file_path,
+                include_default_background=include_default_background,
+                ignore_colors=ignore_colors,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Color map extraction failed; skipping colors_map. (%r)", exc
+            )
+            return None
+    def detect_tables(self, sheet_name: str) -> list[str]:
+        """Detect table candidates for a single sheet.
+        Args:
+            sheet_name: Target worksheet name.
+        Returns:
+            List of table candidate ranges.
+        """
+        try:
+            return detect_tables_openpyxl(self.file_path, sheet_name)
+        except Exception:
+            return []
+def _extract_print_areas_from_defined_names(workbook: object) -> PrintAreaData:
+    """Extract print areas from defined names in an openpyxl workbook.
+    Args:
+        workbook: openpyxl workbook instance.
+    Returns:
+        Mapping of sheet name to print area list.
+    """
+    defined = getattr(workbook, "defined_names", None)
+    if defined is None:
+        return {}
+    defined_area = defined.get("_xlnm.Print_Area")
+    if not defined_area:
+        return {}
+    areas: PrintAreaData = {}
+    sheetnames = set(getattr(workbook, "sheetnames", []))
+    for sheet_name, range_str in defined_area.destinations:
+        if sheet_name not in sheetnames:
+            continue
+        _append_print_areas(areas, sheet_name, str(range_str))
+    return areas
+def _extract_print_areas_from_sheet_props(workbook: object) -> PrintAreaData:
+    """Extract print areas from sheet-level print area properties.
+    Args:
+        workbook: openpyxl workbook instance.
+    Returns:
+        Mapping of sheet name to print area list.
+    """
+    areas: PrintAreaData = {}
+    worksheets = getattr(workbook, "worksheets", [])
+    for ws in worksheets:
+        pa = getattr(ws, "_print_area", None)
+        if not pa:
+            continue
+        _append_print_areas(areas, str(getattr(ws, "title", "")), str(pa))
+    return areas
+def _append_print_areas(areas: PrintAreaData, sheet_name: str, range_str: str) -> None:
+    """Append parsed print areas to the mapping.
+    Args:
+        areas: Mapping to update.
+        sheet_name: Target sheet name.
+        range_str: Raw range string, possibly comma-separated.
+    """
+    for part in str(range_str).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)
+        )
+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)

exstruct 0.2.90__tar.gz → 0.3.1__tar.gz

exstruct 0.2.90tar.gz → 0.3.1tar.gz