rn-forge-data 0.1.2__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.
@@ -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
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"
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"
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