rn-forge-data 0.1.2.dev0__tar.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.
Potentially problematic release.
This version of rn-forge-data might be problematic. Click here for more details.
- rn_forge_data-0.1.2.dev0/LICENSE +21 -0
- rn_forge_data-0.1.2.dev0/PKG-INFO +44 -0
- rn_forge_data-0.1.2.dev0/README.md +17 -0
- rn_forge_data-0.1.2.dev0/pyproject.toml +78 -0
- rn_forge_data-0.1.2.dev0/pyproject.toml.orig +74 -0
- rn_forge_data-0.1.2.dev0/src/rn_forge/data/__init__.py +9 -0
- rn_forge_data-0.1.2.dev0/src/rn_forge/data/excel.py +409 -0
- rn_forge_data-0.1.2.dev0/src/rn_forge/data/pandas.py +279 -0
- rn_forge_data-0.1.2.dev0/src/rn_forge/data/py.typed +0 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rohit Narayanan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: rn-forge-data
|
|
3
|
+
Version: 0.1.2.dev0
|
|
4
|
+
Summary: Excel and tabular data helpers for Python programming
|
|
5
|
+
Author: Rohit Narayanan
|
|
6
|
+
Author-email: Rohit Narayanan <rohit.nn@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Dist: rn-forge-commons>=0.8.0,<0.9
|
|
17
|
+
Requires-Dist: openpyxl>=3.1.5
|
|
18
|
+
Requires-Dist: tablib[xlsx]>=3.8
|
|
19
|
+
Requires-Dist: pandas>=3.0.3 ; extra == 'pandas'
|
|
20
|
+
Requires-Python: >=3.14
|
|
21
|
+
Project-URL: Documentation, https://rn-forge.github.io/pykit/packages/rn-forge-data/latest/
|
|
22
|
+
Project-URL: Source, https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-data
|
|
23
|
+
Project-URL: Changelog, https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-data/CHANGELOG.md
|
|
24
|
+
Project-URL: Issues, https://github.com/rn-forge/pykit/issues
|
|
25
|
+
Provides-Extra: pandas
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# rn-forge-data
|
|
29
|
+
|
|
30
|
+
[Documentation](https://rn-forge.github.io/pykit/packages/rn-forge-data/latest/)
|
|
31
|
+
·
|
|
32
|
+
[Changelog](https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-data/CHANGELOG.md)
|
|
33
|
+
· [Source](https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-data) ·
|
|
34
|
+
[All pykit packages](https://rn-forge.github.io/pykit/)
|
|
35
|
+
|
|
36
|
+
Excel and tabular data helpers for Python programming, built on
|
|
37
|
+
`rn-forge-commons`. The base install carries `openpyxl` and `tablib[xlsx]`; the
|
|
38
|
+
`pandas` extra adds the pandas adapter.
|
|
39
|
+
|
|
40
|
+
- `rn_forge.data` — the core: `ExcelUtils`, `CellFormat`, `WorkbookTemplate` and
|
|
41
|
+
`write_xlsx`. The facade re-exports the core only.
|
|
42
|
+
- `rn_forge.data.pandas` — the pandas adapter, behind the `pandas` extra:
|
|
43
|
+
`PandasUtils` and `ExcelAdapter`. The core never imports it; `.importlinter`
|
|
44
|
+
proves that.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# rn-forge-data
|
|
2
|
+
|
|
3
|
+
[Documentation](https://rn-forge.github.io/pykit/packages/rn-forge-data/latest/)
|
|
4
|
+
·
|
|
5
|
+
[Changelog](https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-data/CHANGELOG.md)
|
|
6
|
+
· [Source](https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-data) ·
|
|
7
|
+
[All pykit packages](https://rn-forge.github.io/pykit/)
|
|
8
|
+
|
|
9
|
+
Excel and tabular data helpers for Python programming, built on
|
|
10
|
+
`rn-forge-commons`. The base install carries `openpyxl` and `tablib[xlsx]`; the
|
|
11
|
+
`pandas` extra adds the pandas adapter.
|
|
12
|
+
|
|
13
|
+
- `rn_forge.data` — the core: `ExcelUtils`, `CellFormat`, `WorkbookTemplate` and
|
|
14
|
+
`write_xlsx`. The facade re-exports the core only.
|
|
15
|
+
- `rn_forge.data.pandas` — the pandas adapter, behind the `pandas` extra:
|
|
16
|
+
`PandasUtils` and `ExcelAdapter`. The core never imports it; `.importlinter`
|
|
17
|
+
proves that.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "rn-forge-data"
|
|
3
|
+
version = "0.1.2.dev0"
|
|
4
|
+
description = "Excel and tabular data helpers for Python programming"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
classifiers = [
|
|
9
|
+
"Development Status :: 3 - Alpha",
|
|
10
|
+
"Intended Audience :: Developers",
|
|
11
|
+
"Operating System :: OS Independent",
|
|
12
|
+
"Programming Language :: Python :: 3",
|
|
13
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
14
|
+
"Programming Language :: Python :: 3.14",
|
|
15
|
+
"Typing :: Typed",
|
|
16
|
+
]
|
|
17
|
+
requires-python = ">=3.14"
|
|
18
|
+
dependencies = [
|
|
19
|
+
"rn-forge-commons>=0.8.0,<0.9",
|
|
20
|
+
"openpyxl>=3.1.5",
|
|
21
|
+
"tablib[xlsx]>=3.8",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[[project.authors]]
|
|
25
|
+
name = "Rohit Narayanan"
|
|
26
|
+
email = "rohit.nn@gmail.com"
|
|
27
|
+
|
|
28
|
+
[project.optional-dependencies]
|
|
29
|
+
pandas = ["pandas>=3.0.3"]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
Documentation = "https://rn-forge.github.io/pykit/packages/rn-forge-data/latest/"
|
|
33
|
+
Source = "https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-data"
|
|
34
|
+
Changelog = "https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-data/CHANGELOG.md"
|
|
35
|
+
Issues = "https://github.com/rn-forge/pykit/issues"
|
|
36
|
+
|
|
37
|
+
[build-system]
|
|
38
|
+
requires = ["uv_build>=0.11.28,<0.12.0"]
|
|
39
|
+
build-backend = "uv_build"
|
|
40
|
+
|
|
41
|
+
[tool.uv.build-backend]
|
|
42
|
+
module-name = "rn_forge.data"
|
|
43
|
+
|
|
44
|
+
[tool.uv.sources.rn-forge-commons]
|
|
45
|
+
workspace = true
|
|
46
|
+
|
|
47
|
+
[tool.uv.sources.rn-forge-data]
|
|
48
|
+
workspace = true
|
|
49
|
+
|
|
50
|
+
[tool.workspace-ci]
|
|
51
|
+
adapters = ["pandas"]
|
|
52
|
+
|
|
53
|
+
[tool.workspace-ci.smoke]
|
|
54
|
+
modules = ["rn_forge.data"]
|
|
55
|
+
|
|
56
|
+
[tool.workspace-ci.smoke.extras]
|
|
57
|
+
pandas = ["rn_forge.data.pandas"]
|
|
58
|
+
|
|
59
|
+
[tool.pytest.ini_options]
|
|
60
|
+
addopts = "-ra --import-mode=importlib"
|
|
61
|
+
|
|
62
|
+
[dependency-groups]
|
|
63
|
+
dev = [
|
|
64
|
+
"assertpy>=1.1",
|
|
65
|
+
"pandas-stubs>=3.0.5",
|
|
66
|
+
"pyright>=1.1.411",
|
|
67
|
+
"pytest>=9.1.1",
|
|
68
|
+
"pytest-cov>=7.1.0",
|
|
69
|
+
"pytest-randomly>=4.1.0",
|
|
70
|
+
"rn-forge-data[pandas]",
|
|
71
|
+
"ruff>=0.15.21",
|
|
72
|
+
]
|
|
73
|
+
docs = [
|
|
74
|
+
"mkdocs>=1.6.1",
|
|
75
|
+
"mkdocs-material>=9.7.6",
|
|
76
|
+
"mkdocstrings[python]>=1.0.6",
|
|
77
|
+
"rn-forge-data[pandas]",
|
|
78
|
+
]
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "rn-forge-data"
|
|
3
|
+
version = "0.1.2.dev0"
|
|
4
|
+
description = "Excel and tabular data helpers for Python programming"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [{ name = "Rohit Narayanan", email = "rohit.nn@gmail.com" }]
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
classifiers = [
|
|
10
|
+
"Development Status :: 3 - Alpha",
|
|
11
|
+
"Intended Audience :: Developers",
|
|
12
|
+
"Operating System :: OS Independent",
|
|
13
|
+
"Programming Language :: Python :: 3",
|
|
14
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
15
|
+
"Programming Language :: Python :: 3.14",
|
|
16
|
+
"Typing :: Typed",
|
|
17
|
+
]
|
|
18
|
+
requires-python = ">=3.14"
|
|
19
|
+
# Internal requirements are version ranges (ADR-0004).
|
|
20
|
+
dependencies = [
|
|
21
|
+
"rn-forge-commons>=0.8.0,<0.9",
|
|
22
|
+
"openpyxl>=3.1.5",
|
|
23
|
+
"tablib[xlsx]>=3.8",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
pandas = ["pandas>=3.0.3"]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Documentation = "https://rn-forge.github.io/pykit/packages/rn-forge-data/latest/"
|
|
31
|
+
Source = "https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-data"
|
|
32
|
+
Changelog = "https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-data/CHANGELOG.md"
|
|
33
|
+
Issues = "https://github.com/rn-forge/pykit/issues"
|
|
34
|
+
|
|
35
|
+
[build-system]
|
|
36
|
+
requires = ["uv_build>=0.11.28,<0.12.0"]
|
|
37
|
+
build-backend = "uv_build"
|
|
38
|
+
|
|
39
|
+
[tool.uv.build-backend]
|
|
40
|
+
module-name = "rn_forge.data"
|
|
41
|
+
|
|
42
|
+
[tool.uv.sources]
|
|
43
|
+
rn-forge-commons = { workspace = true }
|
|
44
|
+
rn-forge-data = { workspace = true }
|
|
45
|
+
|
|
46
|
+
[tool.workspace-ci]
|
|
47
|
+
adapters = ["pandas"]
|
|
48
|
+
|
|
49
|
+
[tool.workspace-ci.smoke]
|
|
50
|
+
modules = ["rn_forge.data"]
|
|
51
|
+
|
|
52
|
+
[tool.workspace-ci.smoke.extras]
|
|
53
|
+
pandas = ["rn_forge.data.pandas"]
|
|
54
|
+
|
|
55
|
+
[tool.pytest.ini_options]
|
|
56
|
+
addopts = "-ra --import-mode=importlib"
|
|
57
|
+
|
|
58
|
+
[dependency-groups]
|
|
59
|
+
dev = [
|
|
60
|
+
"assertpy>=1.1",
|
|
61
|
+
"pandas-stubs>=3.0.5",
|
|
62
|
+
"pyright>=1.1.411",
|
|
63
|
+
"pytest>=9.1.1",
|
|
64
|
+
"pytest-cov>=7.1.0",
|
|
65
|
+
"pytest-randomly>=4.1.0",
|
|
66
|
+
"rn-forge-data[pandas]",
|
|
67
|
+
"ruff>=0.15.21",
|
|
68
|
+
]
|
|
69
|
+
docs = [
|
|
70
|
+
"mkdocs>=1.6.1",
|
|
71
|
+
"mkdocs-material>=9.7.6",
|
|
72
|
+
"mkdocstrings[python]>=1.0.6",
|
|
73
|
+
"rn-forge-data[pandas]",
|
|
74
|
+
]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Excel and tabular data helpers.
|
|
2
|
+
|
|
3
|
+
The pandas adapter, :mod:`rn_forge.data.pandas`, needs the ``pandas`` extra and
|
|
4
|
+
is imported directly.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from rn_forge.data.excel import CellFormat, ExcelUtils, WorkbookTemplate, write_xlsx
|
|
8
|
+
|
|
9
|
+
__all__ = ["CellFormat", "ExcelUtils", "WorkbookTemplate", "write_xlsx"]
|
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
"""Excel workbook, formatting, and tabular export helpers built on ``openpyxl``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Mapping
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from io import BytesIO
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import TYPE_CHECKING, Any, cast
|
|
10
|
+
|
|
11
|
+
import openpyxl
|
|
12
|
+
from openpyxl.cell import WriteOnlyCell
|
|
13
|
+
from openpyxl.styles import Alignment, Border, Font, PatternFill, Protection
|
|
14
|
+
from openpyxl.workbook.workbook import Workbook
|
|
15
|
+
from openpyxl.worksheet.worksheet import Worksheet
|
|
16
|
+
from rn_forge.commons.lang.dataclasses import DataclassMixin
|
|
17
|
+
from rn_forge.commons.logging import AppLogger
|
|
18
|
+
|
|
19
|
+
if TYPE_CHECKING:
|
|
20
|
+
import tablib
|
|
21
|
+
|
|
22
|
+
__all__ = [
|
|
23
|
+
"CellFormat",
|
|
24
|
+
"ExcelUtils",
|
|
25
|
+
"WorkbookTemplate",
|
|
26
|
+
"write_xlsx",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
_LOGGER = AppLogger.get_logger(__name__)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
# ---------------------------------------------------------------------------
|
|
33
|
+
# CellFormat — cell formatting dataclass
|
|
34
|
+
# ---------------------------------------------------------------------------
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass
|
|
38
|
+
class CellFormat(DataclassMixin):
|
|
39
|
+
"""Cell formatting attributes applied via :meth:`ExcelUtils.format_row`.
|
|
40
|
+
|
|
41
|
+
All fields are optional; only non-``None`` values are applied to cells.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
font: Font | None = None
|
|
45
|
+
fill: PatternFill | None = None
|
|
46
|
+
border: Border | None = None
|
|
47
|
+
number_format: str | None = None
|
|
48
|
+
alignment: Alignment | None = None
|
|
49
|
+
protection: Protection | None = None
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
# ---------------------------------------------------------------------------
|
|
53
|
+
# WorkbookTemplate — sheet structure config
|
|
54
|
+
# ---------------------------------------------------------------------------
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass
|
|
58
|
+
class WorkbookTemplate(DataclassMixin):
|
|
59
|
+
"""Configuration struct for a worksheet's column layout and default formats.
|
|
60
|
+
|
|
61
|
+
Args:
|
|
62
|
+
name: Sheet name.
|
|
63
|
+
columns: Ordered list of column header strings.
|
|
64
|
+
row_format: Default :class:`CellFormat` applied to every data row.
|
|
65
|
+
column_formats: Per-column format overrides keyed by 1-based column index.
|
|
66
|
+
"""
|
|
67
|
+
|
|
68
|
+
name: str
|
|
69
|
+
columns: list[str]
|
|
70
|
+
row_format: CellFormat | None = None
|
|
71
|
+
column_formats: dict[int, CellFormat] = field(default_factory=dict[int, CellFormat])
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
# ---------------------------------------------------------------------------
|
|
75
|
+
# ExcelUtils — workbook helpers
|
|
76
|
+
# ---------------------------------------------------------------------------
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class ExcelUtils:
|
|
80
|
+
"""Excel workbook operations via ``openpyxl``.
|
|
81
|
+
|
|
82
|
+
Requires ``openpyxl`` — install with ``rn-forge-data``.
|
|
83
|
+
|
|
84
|
+
Typical workflow::
|
|
85
|
+
|
|
86
|
+
wb = ExcelUtils.new_workbook()
|
|
87
|
+
sheet = wb.active
|
|
88
|
+
sheet.title = "Orders"
|
|
89
|
+
sheet.append(["id", "total"])
|
|
90
|
+
sheet.append([1001, 42.50])
|
|
91
|
+
ExcelUtils.write_workbook(wb, "build/orders.xlsx")
|
|
92
|
+
"""
|
|
93
|
+
|
|
94
|
+
# -- pre-built format constants ----------------------------------------
|
|
95
|
+
|
|
96
|
+
FORMAT_CURRENCY: CellFormat = CellFormat(
|
|
97
|
+
number_format='_([$$-en-US]* #,##0.00_);_([$$-en-US]* (#,##0.00);_([$$-en-US]* "-"??_);_(@_)'
|
|
98
|
+
)
|
|
99
|
+
FORMAT_DATE: CellFormat = CellFormat(number_format="mm/dd/yy;@")
|
|
100
|
+
FORMAT_PERCENTAGE: CellFormat = CellFormat(number_format="0.00%")
|
|
101
|
+
|
|
102
|
+
# -- workbook I/O ------------------------------------------------------
|
|
103
|
+
|
|
104
|
+
@staticmethod
|
|
105
|
+
def new_workbook(write_only: bool = False, iso_dates: bool = False) -> Workbook:
|
|
106
|
+
"""Create and return a new blank :class:`~openpyxl.workbook.Workbook`."""
|
|
107
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
108
|
+
"ExcelUtils.new_workbook | write_only={} | iso_dates={}",
|
|
109
|
+
write_only,
|
|
110
|
+
iso_dates,
|
|
111
|
+
)
|
|
112
|
+
return openpyxl.Workbook(write_only=write_only, iso_dates=iso_dates)
|
|
113
|
+
|
|
114
|
+
@staticmethod
|
|
115
|
+
def load_workbook(
|
|
116
|
+
source: str | Path | BytesIO,
|
|
117
|
+
read_only: bool = False,
|
|
118
|
+
keep_vba: bool = False,
|
|
119
|
+
data_only: bool = False,
|
|
120
|
+
keep_links: bool = True,
|
|
121
|
+
rich_text: bool = False,
|
|
122
|
+
) -> Workbook:
|
|
123
|
+
"""Load an existing Excel file from a path or byte stream.
|
|
124
|
+
|
|
125
|
+
Args:
|
|
126
|
+
source: File path or :class:`~io.BytesIO` containing the workbook.
|
|
127
|
+
read_only: Open in read-only mode (faster for large files).
|
|
128
|
+
keep_vba: Preserve VBA macros.
|
|
129
|
+
data_only: Return cell values instead of formulae.
|
|
130
|
+
keep_links: Preserve external links.
|
|
131
|
+
rich_text: Preserve rich-text cell content.
|
|
132
|
+
"""
|
|
133
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
134
|
+
"ExcelUtils.load_workbook | source={} | read_only={} | keep_vba={} | data_only={} | keep_links={} | rich_text={}",
|
|
135
|
+
source,
|
|
136
|
+
read_only,
|
|
137
|
+
keep_vba,
|
|
138
|
+
data_only,
|
|
139
|
+
keep_links,
|
|
140
|
+
rich_text,
|
|
141
|
+
)
|
|
142
|
+
try:
|
|
143
|
+
workbook = openpyxl.load_workbook(
|
|
144
|
+
source,
|
|
145
|
+
read_only=read_only,
|
|
146
|
+
keep_vba=keep_vba,
|
|
147
|
+
data_only=data_only,
|
|
148
|
+
keep_links=keep_links,
|
|
149
|
+
rich_text=rich_text,
|
|
150
|
+
)
|
|
151
|
+
except Exception:
|
|
152
|
+
_LOGGER.exception("ExcelUtils.load_workbook failed | source={}", source) # noqa: PLE1205 # brace-style log format
|
|
153
|
+
raise
|
|
154
|
+
_LOGGER.verbose(
|
|
155
|
+
"ExcelUtils.load_workbook complete | source={} | sheets={}",
|
|
156
|
+
source,
|
|
157
|
+
workbook.sheetnames,
|
|
158
|
+
)
|
|
159
|
+
return workbook
|
|
160
|
+
|
|
161
|
+
@staticmethod
|
|
162
|
+
def write_workbook(workbook: Workbook, path: str | Path) -> Path:
|
|
163
|
+
"""Save *workbook* to *path*, creating parent directories as needed.
|
|
164
|
+
|
|
165
|
+
Returns the resolved :class:`~pathlib.Path` written.
|
|
166
|
+
"""
|
|
167
|
+
target = Path(path)
|
|
168
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
169
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
170
|
+
"ExcelUtils.write_workbook | path={} | sheets={}",
|
|
171
|
+
target,
|
|
172
|
+
workbook.sheetnames,
|
|
173
|
+
)
|
|
174
|
+
try:
|
|
175
|
+
workbook.save(target)
|
|
176
|
+
except Exception:
|
|
177
|
+
_LOGGER.exception("ExcelUtils.write_workbook failed | path={}", target) # noqa: PLE1205 # brace-style log format
|
|
178
|
+
raise
|
|
179
|
+
_LOGGER.verbose("ExcelUtils.write_workbook complete | path={}", target)
|
|
180
|
+
return target
|
|
181
|
+
|
|
182
|
+
@staticmethod
|
|
183
|
+
def write_workbook_bytes(workbook: Workbook) -> BytesIO:
|
|
184
|
+
"""Serialise *workbook* to an in-memory :class:`~io.BytesIO` buffer."""
|
|
185
|
+
target = BytesIO()
|
|
186
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
187
|
+
"ExcelUtils.write_workbook_bytes | sheets={}",
|
|
188
|
+
workbook.sheetnames,
|
|
189
|
+
)
|
|
190
|
+
try:
|
|
191
|
+
workbook.save(target)
|
|
192
|
+
except Exception:
|
|
193
|
+
_LOGGER.exception("ExcelUtils.write_workbook_bytes failed")
|
|
194
|
+
raise
|
|
195
|
+
_LOGGER.trace(
|
|
196
|
+
"ExcelUtils.write_workbook_bytes complete | bytes={}",
|
|
197
|
+
target.tell(),
|
|
198
|
+
)
|
|
199
|
+
return target
|
|
200
|
+
|
|
201
|
+
# -- formatting --------------------------------------------------------
|
|
202
|
+
|
|
203
|
+
@staticmethod
|
|
204
|
+
def format_row(
|
|
205
|
+
row: tuple[Any, ...],
|
|
206
|
+
row_format: CellFormat | None = None,
|
|
207
|
+
column_formats: dict[int, CellFormat] | None = None,
|
|
208
|
+
) -> None:
|
|
209
|
+
"""Apply *row_format* and per-column *column_formats* to every cell in *row*.
|
|
210
|
+
|
|
211
|
+
Args:
|
|
212
|
+
row: Tuple of ``Cell`` objects as returned by iterating worksheet rows.
|
|
213
|
+
row_format: Format applied to every cell in the row before column overrides.
|
|
214
|
+
column_formats: Mapping of 1-based column index → :class:`CellFormat`.
|
|
215
|
+
Applied after *row_format*, so column-specific values take precedence.
|
|
216
|
+
"""
|
|
217
|
+
_column_formats = column_formats or {}
|
|
218
|
+
_LOGGER.trace(
|
|
219
|
+
"ExcelUtils.format_row | cells={} | row_format={} | column_formats={}",
|
|
220
|
+
len(row),
|
|
221
|
+
row_format is not None,
|
|
222
|
+
sorted(_column_formats),
|
|
223
|
+
)
|
|
224
|
+
for cell in row:
|
|
225
|
+
if row_format:
|
|
226
|
+
ExcelUtils._apply_cell_format(cell, row_format)
|
|
227
|
+
col_fmt = _column_formats.get(cell.column) if cell.column else None
|
|
228
|
+
if col_fmt:
|
|
229
|
+
ExcelUtils._apply_cell_format(cell, col_fmt)
|
|
230
|
+
|
|
231
|
+
@staticmethod
|
|
232
|
+
def _apply_cell_format(cell: Any, cell_format: CellFormat) -> None:
|
|
233
|
+
"""Apply each non-``None`` attribute of *cell_format* onto *cell*."""
|
|
234
|
+
for key, value in vars(cell_format).items():
|
|
235
|
+
if value is not None:
|
|
236
|
+
setattr(cell, key, value)
|
|
237
|
+
|
|
238
|
+
# -- table management --------------------------------------------------
|
|
239
|
+
|
|
240
|
+
@staticmethod
|
|
241
|
+
def add_table(
|
|
242
|
+
sheet: Worksheet,
|
|
243
|
+
table_name: str,
|
|
244
|
+
cell_range: str,
|
|
245
|
+
style: str,
|
|
246
|
+
show_first_column: bool | None = None,
|
|
247
|
+
show_last_column: bool | None = None,
|
|
248
|
+
show_row_stripes: bool | None = None,
|
|
249
|
+
show_column_stripes: bool | None = None,
|
|
250
|
+
) -> None:
|
|
251
|
+
"""Add a named table to *sheet*.
|
|
252
|
+
|
|
253
|
+
Parameters
|
|
254
|
+
----------
|
|
255
|
+
sheet:
|
|
256
|
+
Target worksheet.
|
|
257
|
+
table_name:
|
|
258
|
+
Unique display name for the table (e.g. ``"SalesData"``).
|
|
259
|
+
cell_range:
|
|
260
|
+
Excel range reference (e.g. ``"A1:D20"``).
|
|
261
|
+
style:
|
|
262
|
+
Table style name (e.g. ``"TableStyleMedium9"``).
|
|
263
|
+
show_first_column / show_last_column / show_row_stripes / show_column_stripes:
|
|
264
|
+
Optional table style flags.
|
|
265
|
+
"""
|
|
266
|
+
from openpyxl.worksheet.table import Table, TableStyleInfo
|
|
267
|
+
|
|
268
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
269
|
+
"ExcelUtils.add_table | sheet={} | table_name={} | range={} | style={}",
|
|
270
|
+
sheet.title,
|
|
271
|
+
table_name,
|
|
272
|
+
cell_range,
|
|
273
|
+
style,
|
|
274
|
+
)
|
|
275
|
+
table: Table = Table(displayName=table_name, ref=cell_range)
|
|
276
|
+
table.tableStyleInfo = TableStyleInfo(
|
|
277
|
+
name=style,
|
|
278
|
+
showFirstColumn=show_first_column,
|
|
279
|
+
showLastColumn=show_last_column,
|
|
280
|
+
showRowStripes=show_row_stripes,
|
|
281
|
+
showColumnStripes=show_column_stripes,
|
|
282
|
+
)
|
|
283
|
+
sheet.add_table(table)
|
|
284
|
+
|
|
285
|
+
@staticmethod
|
|
286
|
+
def resize_table(sheet: Worksheet, table_name: str) -> None:
|
|
287
|
+
"""Resize the named table to span all rows currently in *sheet*.
|
|
288
|
+
|
|
289
|
+
Updates the table's ``ref`` to ``A1:<last-column><last-row>``.
|
|
290
|
+
|
|
291
|
+
Raises:
|
|
292
|
+
TypeError: If the last cell in the final row is a merged cell (no column letter).
|
|
293
|
+
"""
|
|
294
|
+
from openpyxl.cell import Cell
|
|
295
|
+
|
|
296
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
297
|
+
"ExcelUtils.resize_table | sheet={} | table_name={} | max_row={}",
|
|
298
|
+
sheet.title,
|
|
299
|
+
table_name,
|
|
300
|
+
sheet.max_row,
|
|
301
|
+
)
|
|
302
|
+
last_row = sheet[sheet.max_row]
|
|
303
|
+
last_cell = last_row[-1]
|
|
304
|
+
if not isinstance(last_cell, Cell):
|
|
305
|
+
_LOGGER.warning( # noqa: PLE1205 # brace-style log format
|
|
306
|
+
"ExcelUtils.resize_table: merged cell prevents resize | sheet={} | table_name={} | row={}",
|
|
307
|
+
sheet.title,
|
|
308
|
+
table_name,
|
|
309
|
+
sheet.max_row,
|
|
310
|
+
)
|
|
311
|
+
raise TypeError(
|
|
312
|
+
f"resize_table: last cell in row {sheet.max_row} is a MergedCell "
|
|
313
|
+
"and has no column letter — cannot determine table bounds"
|
|
314
|
+
)
|
|
315
|
+
sheet.tables[table_name].ref = f"A1:{last_cell.column_letter}{sheet.max_row}"
|
|
316
|
+
_LOGGER.trace(
|
|
317
|
+
"ExcelUtils.resize_table complete | table_name={} | ref={}",
|
|
318
|
+
table_name,
|
|
319
|
+
sheet.tables[table_name].ref,
|
|
320
|
+
)
|
|
321
|
+
|
|
322
|
+
# -- column utilities --------------------------------------------------
|
|
323
|
+
|
|
324
|
+
@staticmethod
|
|
325
|
+
def auto_adjust_column_width(sheet: Worksheet) -> None:
|
|
326
|
+
"""Set each column's width to fit the longest cell value in that column."""
|
|
327
|
+
from openpyxl.cell import Cell
|
|
328
|
+
|
|
329
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
330
|
+
"ExcelUtils.auto_adjust_column_width | sheet={} | columns={}",
|
|
331
|
+
sheet.title,
|
|
332
|
+
sheet.max_column,
|
|
333
|
+
)
|
|
334
|
+
for col_cells in sheet.columns:
|
|
335
|
+
col_list = list(col_cells)
|
|
336
|
+
max_length = 0
|
|
337
|
+
for cell in col_list:
|
|
338
|
+
if cell.value is None:
|
|
339
|
+
continue
|
|
340
|
+
max_length = max(max_length, len(str(cell.value)))
|
|
341
|
+
first = col_list[0]
|
|
342
|
+
if not isinstance(first, Cell):
|
|
343
|
+
continue
|
|
344
|
+
sheet.column_dimensions[first.column_letter].width = max_length + 1
|
|
345
|
+
_LOGGER.trace(
|
|
346
|
+
"ExcelUtils.auto_adjust_column_width complete | sheet={}",
|
|
347
|
+
sheet.title,
|
|
348
|
+
)
|
|
349
|
+
|
|
350
|
+
@staticmethod
|
|
351
|
+
def column_letter(column_number: int) -> str:
|
|
352
|
+
"""Convert a 1-based column number to its Excel letter(s).
|
|
353
|
+
|
|
354
|
+
Examples: ``1`` → ``"A"``, ``26`` → ``"Z"``, ``27`` → ``"AA"``.
|
|
355
|
+
"""
|
|
356
|
+
from openpyxl.utils import get_column_letter
|
|
357
|
+
|
|
358
|
+
return get_column_letter(column_number)
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def write_xlsx(
|
|
362
|
+
dataset: tablib.Dataset,
|
|
363
|
+
column_formats: Mapping[str, str] | None = None,
|
|
364
|
+
sheet_title: str = "Sheet1",
|
|
365
|
+
) -> bytes:
|
|
366
|
+
"""Serialise *dataset* to ``.xlsx`` bytes, with per-column number formats.
|
|
367
|
+
|
|
368
|
+
Args:
|
|
369
|
+
dataset: Data to write. Its headers form the first row; without headers
|
|
370
|
+
only data rows are written.
|
|
371
|
+
column_formats: Excel number format per header name, for example
|
|
372
|
+
``{"due": "yyyy-mm-dd", "total": "#,##0.00"}``. Columns not named
|
|
373
|
+
keep the default format.
|
|
374
|
+
sheet_title: Worksheet title.
|
|
375
|
+
|
|
376
|
+
Returns:
|
|
377
|
+
The workbook as bytes.
|
|
378
|
+
|
|
379
|
+
Raises:
|
|
380
|
+
KeyError: A *column_formats* key is not a dataset header.
|
|
381
|
+
"""
|
|
382
|
+
formats = column_formats or {}
|
|
383
|
+
headers = cast("list[str]", dataset.headers or []) # pyright: ignore[reportUnknownMemberType] # tablib is untyped
|
|
384
|
+
unknown = sorted(set(formats) - set(headers))
|
|
385
|
+
if unknown:
|
|
386
|
+
raise KeyError(f"column_formats names unknown columns: {unknown}")
|
|
387
|
+
by_index = {headers.index(name): fmt for name, fmt in formats.items()}
|
|
388
|
+
|
|
389
|
+
workbook = openpyxl.Workbook(write_only=True)
|
|
390
|
+
sheet = workbook.create_sheet(sheet_title)
|
|
391
|
+
if headers:
|
|
392
|
+
sheet.append(headers)
|
|
393
|
+
rows = cast(
|
|
394
|
+
"list[tuple[Any, ...]]", list(cast("Any", dataset))
|
|
395
|
+
) # tablib is untyped
|
|
396
|
+
for row in rows:
|
|
397
|
+
cells: list[Any] = []
|
|
398
|
+
for index, value in enumerate(row):
|
|
399
|
+
cell = WriteOnlyCell(sheet, value=value)
|
|
400
|
+
if index in by_index:
|
|
401
|
+
cell.number_format = by_index[index]
|
|
402
|
+
cells.append(cell)
|
|
403
|
+
sheet.append(cells)
|
|
404
|
+
return ExcelUtils.write_workbook_bytes(workbook).getvalue()
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
# ---------------------------------------------------------------------------
|
|
408
|
+
# Internal helpers
|
|
409
|
+
# ---------------------------------------------------------------------------
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
"""The pandas adapter: row field extraction and Excel DataFrame conversion.
|
|
2
|
+
|
|
3
|
+
Requires the ``pandas`` extra.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from decimal import Decimal
|
|
9
|
+
from io import BytesIO
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
import pandas
|
|
14
|
+
from openpyxl.workbook.workbook import Workbook
|
|
15
|
+
from rn_forge.commons.exceptions import AppException
|
|
16
|
+
from rn_forge.commons.logging import AppLogger
|
|
17
|
+
from rn_forge.data.excel import ExcelUtils
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"ExcelAdapter",
|
|
21
|
+
"PandasUtils",
|
|
22
|
+
"SeriesRow",
|
|
23
|
+
"series_columns",
|
|
24
|
+
"series_value",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
_LOGGER = AppLogger.get_logger(__name__)
|
|
28
|
+
|
|
29
|
+
type SeriesRow = pandas.Series
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def series_value(row: SeriesRow, field_name: str) -> Any:
|
|
33
|
+
"""Return ``row[field_name]``, normalized to ``Any``.
|
|
34
|
+
|
|
35
|
+
``Series.__getitem__`` has a wide overload set; pinning the result to
|
|
36
|
+
``Any`` here keeps the variation out of every call site.
|
|
37
|
+
"""
|
|
38
|
+
return row[field_name]
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def series_columns(row: SeriesRow) -> list[Any]:
|
|
42
|
+
"""Return the index labels of *row* as a plain list."""
|
|
43
|
+
return row.index.tolist()
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class PandasUtils:
|
|
47
|
+
"""Field extraction from pandas DataFrame and Series rows.
|
|
48
|
+
|
|
49
|
+
Requires ``pandas`` — install with ``rn-forge-data[pandas]``.
|
|
50
|
+
|
|
51
|
+
Example::
|
|
52
|
+
|
|
53
|
+
row = df.iloc[0]
|
|
54
|
+
customer_id = PandasUtils.get_string_field(row, "customer_id")
|
|
55
|
+
total = PandasUtils.get_decimal_field(row, "total", precision=2)
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
# -- row field extraction ----------------------------------------------
|
|
59
|
+
|
|
60
|
+
@staticmethod
|
|
61
|
+
def get_field(
|
|
62
|
+
row: pandas.Series,
|
|
63
|
+
field_name: str,
|
|
64
|
+
required: bool = True,
|
|
65
|
+
) -> Any:
|
|
66
|
+
"""Return the value of *field_name* from *row*, or ``None`` if NaN.
|
|
67
|
+
|
|
68
|
+
Args:
|
|
69
|
+
row: A ``pandas.Series`` (e.g. from ``df.itertuples()`` or
|
|
70
|
+
``df.iterrows()``).
|
|
71
|
+
field_name: Column name to extract.
|
|
72
|
+
required: When ``True`` (default), raise
|
|
73
|
+
:exc:`~rn_forge.commons.AppException` if the field is NaN / missing.
|
|
74
|
+
"""
|
|
75
|
+
try:
|
|
76
|
+
field_value: Any = series_value(row, field_name)
|
|
77
|
+
except Exception:
|
|
78
|
+
columns = series_columns(row) if hasattr(row, "index") else "<unavailable>"
|
|
79
|
+
_LOGGER.exception( # noqa: PLE1205 # brace-style log format
|
|
80
|
+
"PandasUtils.get_field failed | field={} | required={} | columns={}",
|
|
81
|
+
field_name,
|
|
82
|
+
required,
|
|
83
|
+
columns,
|
|
84
|
+
)
|
|
85
|
+
raise
|
|
86
|
+
is_valid = not PandasUtils.is_na(field_value)
|
|
87
|
+
_LOGGER.trace(
|
|
88
|
+
"PandasUtils.get_field | field={} | required={} | is_valid={} | value={}",
|
|
89
|
+
field_name,
|
|
90
|
+
required,
|
|
91
|
+
is_valid,
|
|
92
|
+
field_value,
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
if required and not is_valid:
|
|
96
|
+
_LOGGER.warning( # noqa: PLE1205 # brace-style log format
|
|
97
|
+
"PandasUtils.get_field missing required value | field={} | columns={}",
|
|
98
|
+
field_name,
|
|
99
|
+
series_columns(row),
|
|
100
|
+
)
|
|
101
|
+
AppException.check(
|
|
102
|
+
not required or is_valid,
|
|
103
|
+
"Field is required: {}",
|
|
104
|
+
field_name,
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
return field_value if is_valid else None
|
|
108
|
+
|
|
109
|
+
@staticmethod
|
|
110
|
+
def get_string_field(
|
|
111
|
+
row: pandas.Series,
|
|
112
|
+
field_name: str,
|
|
113
|
+
required: bool = True,
|
|
114
|
+
) -> str:
|
|
115
|
+
"""Return *field_name* from *row* as a string.
|
|
116
|
+
|
|
117
|
+
NaN values are returned as an empty string ``""``.
|
|
118
|
+
"""
|
|
119
|
+
field_value = PandasUtils.get_field(row, field_name, required)
|
|
120
|
+
result = str(field_value or "").strip()
|
|
121
|
+
_LOGGER.trace(
|
|
122
|
+
"PandasUtils.get_string_field | field={} | required={} | result={}",
|
|
123
|
+
field_name,
|
|
124
|
+
required,
|
|
125
|
+
result,
|
|
126
|
+
)
|
|
127
|
+
return result
|
|
128
|
+
|
|
129
|
+
@staticmethod
|
|
130
|
+
def get_decimal_field(
|
|
131
|
+
row: pandas.Series,
|
|
132
|
+
field_name: str,
|
|
133
|
+
precision: int = 2,
|
|
134
|
+
required: bool = True,
|
|
135
|
+
) -> Decimal:
|
|
136
|
+
"""Return *field_name* from *row* as a :class:`~decimal.Decimal`.
|
|
137
|
+
|
|
138
|
+
Args:
|
|
139
|
+
row: A ``pandas.Series`` row.
|
|
140
|
+
field_name: Column name to extract.
|
|
141
|
+
precision: Number of decimal places to round to (default ``2``).
|
|
142
|
+
required: When ``True`` (default), raise
|
|
143
|
+
:exc:`~rn_forge.commons.AppException` if the field is NaN / missing.
|
|
144
|
+
"""
|
|
145
|
+
field_value = PandasUtils.get_string_field(row, field_name, required)
|
|
146
|
+
try:
|
|
147
|
+
result = round(Decimal(str(field_value or 0)), precision)
|
|
148
|
+
except Exception:
|
|
149
|
+
_LOGGER.exception( # noqa: PLE1205 # brace-style log format
|
|
150
|
+
"PandasUtils.get_decimal_field failed | field={} | precision={} | value={}",
|
|
151
|
+
field_name,
|
|
152
|
+
precision,
|
|
153
|
+
field_value,
|
|
154
|
+
)
|
|
155
|
+
raise
|
|
156
|
+
_LOGGER.trace(
|
|
157
|
+
"PandasUtils.get_decimal_field | field={} | precision={} | result={}",
|
|
158
|
+
field_name,
|
|
159
|
+
precision,
|
|
160
|
+
result,
|
|
161
|
+
)
|
|
162
|
+
return result
|
|
163
|
+
|
|
164
|
+
@staticmethod
|
|
165
|
+
def is_na(value: Any) -> bool:
|
|
166
|
+
"""Return whether *value* is considered missing by pandas.
|
|
167
|
+
|
|
168
|
+
Mirrors :func:`pandas.isna` but always returns a plain ``bool``.
|
|
169
|
+
"""
|
|
170
|
+
# pandas-stubs gap: the ``isna`` overload set leaks Unknown type vars.
|
|
171
|
+
result = bool(pandas.isna(value)) # pyright: ignore[reportUnknownArgumentType]
|
|
172
|
+
_LOGGER.trace("PandasUtils.is_na | result={}", result)
|
|
173
|
+
return result
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
class ExcelAdapter:
|
|
177
|
+
"""Adapters between workbook primitives and pandas DataFrames.
|
|
178
|
+
|
|
179
|
+
Use this layer when the calling code wants ``pandas`` for transformation
|
|
180
|
+
but ``openpyxl`` for workbook-level formatting or templating.
|
|
181
|
+
|
|
182
|
+
Example::
|
|
183
|
+
|
|
184
|
+
data = ExcelAdapter.read_dataframe("orders.xlsx")
|
|
185
|
+
workbook = ExcelAdapter.from_dataframe(data)
|
|
186
|
+
ExcelUtils.write_workbook(workbook, "build/orders-copy.xlsx")
|
|
187
|
+
"""
|
|
188
|
+
|
|
189
|
+
@staticmethod
|
|
190
|
+
def read_dataframe(path: str | Path) -> dict[str, pandas.DataFrame]:
|
|
191
|
+
"""Read a workbook file into a sheet-name keyed DataFrame mapping."""
|
|
192
|
+
_LOGGER.debug("ExcelAdapter.read_dataframe | path={}", path) # noqa: PLE1205 # brace-style log format
|
|
193
|
+
try:
|
|
194
|
+
workbook: dict[str, pandas.DataFrame] = pandas.read_excel( # pyright: ignore[reportUnknownMemberType] # pandas-stubs gap
|
|
195
|
+
path, sheet_name=None
|
|
196
|
+
)
|
|
197
|
+
except Exception:
|
|
198
|
+
_LOGGER.exception("ExcelAdapter.read_dataframe failed | path={}", path) # noqa: PLE1205 # brace-style log format
|
|
199
|
+
raise
|
|
200
|
+
_LOGGER.verbose(
|
|
201
|
+
"ExcelAdapter.read_dataframe complete | path={} | sheets={}",
|
|
202
|
+
path,
|
|
203
|
+
list(workbook),
|
|
204
|
+
)
|
|
205
|
+
return workbook
|
|
206
|
+
|
|
207
|
+
@staticmethod
|
|
208
|
+
def load_dataframe(source: BytesIO) -> dict[str, pandas.DataFrame]:
|
|
209
|
+
"""Load an in-memory workbook into a sheet-name keyed DataFrame mapping."""
|
|
210
|
+
_LOGGER.debug("ExcelAdapter.load_dataframe")
|
|
211
|
+
try:
|
|
212
|
+
workbook: dict[str, pandas.DataFrame] = pandas.read_excel( # pyright: ignore[reportUnknownMemberType] # pandas-stubs gap
|
|
213
|
+
source, sheet_name=None
|
|
214
|
+
)
|
|
215
|
+
except Exception:
|
|
216
|
+
_LOGGER.exception("ExcelAdapter.load_dataframe failed")
|
|
217
|
+
raise
|
|
218
|
+
_LOGGER.verbose(
|
|
219
|
+
"ExcelAdapter.load_dataframe complete | sheets={}",
|
|
220
|
+
list(workbook),
|
|
221
|
+
)
|
|
222
|
+
return workbook
|
|
223
|
+
|
|
224
|
+
@staticmethod
|
|
225
|
+
def from_dataframe(
|
|
226
|
+
data: pandas.DataFrame | dict[str, pandas.DataFrame],
|
|
227
|
+
) -> Workbook:
|
|
228
|
+
"""Convert DataFrame data to an in-memory workbook."""
|
|
229
|
+
buf = BytesIO()
|
|
230
|
+
sheets = data if isinstance(data, dict) else {"Sheet1": data}
|
|
231
|
+
_LOGGER.debug( # noqa: PLE1205 # brace-style log format
|
|
232
|
+
"ExcelAdapter.from_dataframe | sheets={}",
|
|
233
|
+
list(sheets),
|
|
234
|
+
)
|
|
235
|
+
try:
|
|
236
|
+
with pandas.ExcelWriter(
|
|
237
|
+
buf, engine="openpyxl"
|
|
238
|
+
) as writer: # pandas-stubs gap
|
|
239
|
+
for sheet_name, frame in sheets.items():
|
|
240
|
+
_LOGGER.trace(
|
|
241
|
+
"ExcelAdapter.from_dataframe sheet | name={} | rows={} | columns={}",
|
|
242
|
+
sheet_name,
|
|
243
|
+
len(frame.index),
|
|
244
|
+
list(frame.columns),
|
|
245
|
+
)
|
|
246
|
+
frame.to_excel(writer, sheet_name=sheet_name, index=False) # pyright: ignore[reportUnknownMemberType] # pandas-stubs gap
|
|
247
|
+
except Exception:
|
|
248
|
+
_LOGGER.exception( # noqa: PLE1205 # brace-style log format
|
|
249
|
+
"ExcelAdapter.from_dataframe failed | sheets={}",
|
|
250
|
+
list(sheets),
|
|
251
|
+
)
|
|
252
|
+
raise
|
|
253
|
+
buf.seek(0)
|
|
254
|
+
workbook = ExcelUtils.load_workbook(buf)
|
|
255
|
+
_LOGGER.verbose(
|
|
256
|
+
"ExcelAdapter.from_dataframe complete | sheets={}",
|
|
257
|
+
workbook.sheetnames,
|
|
258
|
+
)
|
|
259
|
+
return workbook
|
|
260
|
+
|
|
261
|
+
@staticmethod
|
|
262
|
+
def read_workbook(path: str | Path) -> Workbook:
|
|
263
|
+
"""Read a workbook from a filesystem path."""
|
|
264
|
+
return ExcelUtils.load_workbook(path)
|
|
265
|
+
|
|
266
|
+
@staticmethod
|
|
267
|
+
def load_workbook(source: BytesIO) -> Workbook:
|
|
268
|
+
"""Load a workbook from an in-memory byte buffer."""
|
|
269
|
+
return ExcelUtils.load_workbook(source)
|
|
270
|
+
|
|
271
|
+
@staticmethod
|
|
272
|
+
def write_workbook(workbook: Workbook, path: str | Path) -> Path:
|
|
273
|
+
"""Write a workbook to disk."""
|
|
274
|
+
return ExcelUtils.write_workbook(workbook, path)
|
|
275
|
+
|
|
276
|
+
@staticmethod
|
|
277
|
+
def workbook_to_bytes(workbook: Workbook) -> BytesIO:
|
|
278
|
+
"""Serialise a workbook to an in-memory byte buffer."""
|
|
279
|
+
return ExcelUtils.write_workbook_bytes(workbook)
|
|
File without changes
|