wixlf 0.1.1__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,49 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ jobs:
11
+ build:
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Set up Python 3.14
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.14"
20
+
21
+ - name: Build sdist and wheel
22
+ run: |
23
+ python -m pip install --upgrade pip build
24
+ python -m build
25
+
26
+ - name: Upload build artifacts
27
+ uses: actions/upload-artifact@v4
28
+ with:
29
+ name: dist
30
+ path: dist/
31
+
32
+ publish-pypi:
33
+ needs: build
34
+ runs-on: ubuntu-latest
35
+ environment:
36
+ name: pypi
37
+ url: https://pypi.org/p/wixlf
38
+ permissions:
39
+ id-token: write
40
+
41
+ steps:
42
+ - name: Download build artifacts
43
+ uses: actions/download-artifact@v4
44
+ with:
45
+ name: dist
46
+ path: dist/
47
+
48
+ - name: Publish package to PyPI
49
+ uses: pypa/gh-action-pypi-publish@release/v1
wixlf-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,204 @@
1
+ Metadata-Version: 2.5
2
+ Name: wixlf
3
+ Version: 0.1.1
4
+ Summary: Write Into XLSX Files — constant-memory, multiprocess streaming writer for existing .xlsx/.xlsm workbooks.
5
+ Project-URL: Homepage, https://github.com/chinchilak/wixlf
6
+ Project-URL: Issues, https://github.com/chinchilak/wixlf/issues
7
+ Author: chinchilak
8
+ License-Expression: MIT
9
+ Keywords: excel,lxml,openpyxl,streaming,wixlf,xlsm,xlsx
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
16
+ Requires-Python: >=3.14
17
+ Requires-Dist: lxml>=5.3.0
18
+ Description-Content-Type: text/markdown
19
+
20
+ # WIXLF — Write Into XLSX Files
21
+
22
+ A high-performance, constant-memory Python 3.14+ library for modifying existing Excel (`.xlsx` / `.xlsm`) workbooks. Instead of deserializing the entire workbook DOM into memory like `openpyxl`, **WIXLF** streams modified worksheets row-by-row via `lxml` while copying untouched archive parts byte-for-byte.
23
+
24
+ #### Why openpyxl Is Slow & Limiting for Existing Files
25
+ If you are designing a streamlined writer specifically for modifying existing files, openpyxl suffers from four architectural bottlenecks you can avoid:
26
+
27
+ * Full DOM Deserialization: Even to change a single cell (ws['A1'] = 5), openpyxl parses every XML file in the .xlsx zip archive (sharedStrings.xml, styles.xml, all sheetN.xml files) into heavy Python objects and re-serializes everything on save(). A streaming XML/zip-patching approach that only rewrites the modified sheetN.xml (and calcChain.xml if needed) is orders of magnitude faster.
28
+
29
+ * No write_only Mode for Existing Files: openpyxl restricts its fast lxml-backed streaming writer (write_only=True) to brand-new workbooks. You cannot stream-append rows to an existing template without loading the whole file into memory.
30
+
31
+ * Destructive Round-Tripping: Because openpyxl only rebuilds XML elements it explicitly models, opening and saving an existing workbook silently strips unsupported features—such as shapes, SmartArt, form controls, slicers, and certain pivot table/chart properties. Preserving untouched XML parts verbatim inside the zip archive avoids this completely.
32
+
33
+ * No Automatic Formula Shifting: Inserting/deleting rows or appending data into existing Excel Tables (ListObject in xl/tables/tableN.xml) requires manual updates to table ranges and formulas in openpyxl.
34
+
35
+ ---
36
+
37
+ ## Key Features
38
+
39
+ * **Constant $O(1)$ Memory Footprint:** Streams `<worksheet>` XML via `lxml.etree.iterparse` + `lxml.etree.xmlfile` with immediate DOM node pruning (`elem.clear()` and preceding-sibling deletion), keeping RAM flat even on multi-hundred-megabyte sheets.
40
+ * **Per-Worksheet Multiprocessing:** Automatically dispatches modified worksheets across a `ProcessPoolExecutor` (bypassing the GIL) when editing multiple sheets or sheets $\ge$ 512 KB, while running single small edits inline to avoid process spawn overhead.
41
+ * **Lossless Workbook Round-Tripping:** Untouched worksheets, `styles.xml`, themes, charts, pivot tables, drawings, media, and VBA macros (`.xlsm`) are streamed straight from source to destination in 1 MB chunks without parsing or stripping unsupported OOXML tags.
42
+ * **Automatic Style Inheritance:** Overwriting an existing cell preserves its original Excel style index (`s` attribute—fonts, fills, borders, number formats) unless explicitly overridden or cleared.
43
+ * **Zero `sharedStrings.xml` Contention:** Writes text values using OOXML `inlineStr` (`<c t="inlineStr"><is><t>...</t></is></c>`), eliminating shared-string table locks and enabling safe parallel sheet processing.
44
+ * **Automatic Formula Recalculation Safety:** Strips stale `xl/calcChain.xml` references from `[Content_Types].xml` and `xl/_rels/workbook.xml.rels` and sets `fullCalcOnLoad="1"` in `xl/workbook.xml` so Excel recalculates dependent formulas cleanly on open.
45
+ * **Atomic File Replacement:** Writes to a staged temporary `.xlsx` file in the target directory and promotes it via `os.replace()`, preventing half-written or corrupted outputs on failure.
46
+ * **Pure-Python Utilities (Zero Regex):** Cell coordinate parsing and XML 1.0 character sanitization use pure ASCII character scanning and C-level `str.translate()`.
47
+
48
+ ---
49
+
50
+ ## Installation
51
+
52
+ Requires **Python 3.14+** and `lxml`:
53
+
54
+ ```bash
55
+ pip install wixlf
56
+ ```
57
+
58
+ Or install from source:
59
+
60
+ ```bash
61
+ pip install -e .
62
+ ```
63
+
64
+ ---
65
+
66
+ ## Quick Start
67
+
68
+ ### High-Level API (`wixlf.patch_workbook`)
69
+
70
+ ```python
71
+ import wixlf
72
+
73
+ wixlf.patch_workbook(
74
+ "template.xlsx",
75
+ "output.xlsx",
76
+ {
77
+ "Sales": {
78
+ "A1": "Q4 Revenue Report",
79
+ "B2": 149500.75,
80
+ "C2": True,
81
+ "D2": "=B2*0.21",
82
+ },
83
+ "Summary": {
84
+ (2, 1): "Total",
85
+ (2, 2): "=SUM(Sales!B2:B500)",
86
+ },
87
+ },
88
+ )
89
+ ```
90
+
91
+ ### Lower-Level Pipeline API
92
+
93
+ Use `PackageReader`, `SheetEditPlan`, and `PackageAssembler` directly when you need fine-grained control over worker count, chunk sizes, or pre-compiled edit plans:
94
+
95
+ ```python
96
+ from wixlf import (
97
+ PackageAssembler,
98
+ PackageReader,
99
+ SheetEditPlan,
100
+ patch_sheet_worker,
101
+ )
102
+
103
+ # 1. Resolve human-readable sheet names to internal zip paths
104
+ reader = PackageReader("template.xlsx")
105
+ sheets = reader.get_sheets()
106
+
107
+ # 2. Pre-sort edits into immutable, picklable plans per sheet
108
+ dirty_edits = {
109
+ sheets["Sales"].zip_path: SheetEditPlan.from_dict({
110
+ "A1": "Q4 Revenue Report",
111
+ "B2": 149500.75,
112
+ }),
113
+ }
114
+
115
+ # 3. Execute parallel sheet streaming & atomic archive assembly
116
+ assembler = PackageAssembler(
117
+ src_path="template.xlsx",
118
+ dst_path="output.xlsx",
119
+ max_workers=4, # Defaults to os.process_cpu_count()
120
+ chunk_size=2 * 1024 * 1024, # 2 MB zip stream copy buffer
121
+ )
122
+ assembler.build(
123
+ dirty_edits=dirty_edits,
124
+ patch_fn=patch_sheet_worker,
125
+ force_recalc=True,
126
+ )
127
+ ```
128
+
129
+ ---
130
+
131
+ ## Supported Cell Types & Styling
132
+
133
+ ### 1. Data Types & Formulas
134
+
135
+ `SheetEditPlan.from_dict()` accepts A1-style coordinates (`"B5"`, `"$AA$10"`) or 1-based `(row, col)` tuples (`(5, 2)`):
136
+
137
+ ```python
138
+ from datetime import date, datetime, time
139
+ from wixlf import SheetEditPlan
140
+
141
+ plan = SheetEditPlan.from_dict({
142
+ "A2": "Plain text (auto-strips illegal XML 1.0 control chars)",
143
+ "B2": " Leading/trailing spaces (auto-sets xml:space='preserve') ",
144
+ "C2": 42, # Integer
145
+ "D2": 3.14159, # Float (NaN/Inf serializes as #NUM!)
146
+ "E2": True, # Boolean (OOXML t="b")
147
+ "F2": date(2026, 11, 16), # Converted to Excel 1900 serial number
148
+ "G2": datetime(2026, 11, 16, 14, 30),
149
+ "H2": time(9, 15, 0),
150
+ "I2": "=SUM(C2:D2)", # Formula (leading '=' stripped for OOXML <f>)
151
+ "J2": None, # Clears cell value while keeping cell style
152
+ })
153
+ ```
154
+
155
+ ### 2. Overriding or Clearing Cell Styles
156
+
157
+ ```python
158
+ from wixlf import CellEdit, RowEditBatch, SheetEditPlan
159
+
160
+ # Option A: Assign explicit style indices ('s' from xl/styles.xml)
161
+ plan = SheetEditPlan.from_dict(
162
+ cell_map={"A10": 9999.95, "B10": "Total"},
163
+ styles={"A10": "14", "B10": "15"},
164
+ )
165
+
166
+ # Option B: Strip styling from specific cells
167
+ custom_plan = SheetEditPlan(
168
+ rows=(
169
+ RowEditBatch(
170
+ row=10,
171
+ cells=(
172
+ CellEdit(row=10, col=1, value="Unstyled Reset", clear_style=True),
173
+ ),
174
+ ),
175
+ )
176
+ )
177
+ ```
178
+
179
+ ---
180
+
181
+ ## Package Architecture
182
+
183
+ ```text
184
+ src/wixlf/
185
+ ├── __init__.py # Public API exports + patch_workbook() facade
186
+ ├── constants.py # OOXML namespaces, QName tags, content-types, and type aliases
187
+ ├── models.py # Immutable slotted dataclasses (SheetInfo, CellEdit, RowEditBatch, SheetEditPlan)
188
+ ├── reader.py # PackageReader: resolves sheet names to internal zip XML paths
189
+ ├── patcher.py # SheetStreamPatcher & patch_sheet_worker: O(1) memory XML stream patcher
190
+ ├── assembler.py # PackageAssembler: ProcessPoolExecutor orchestrator & atomic zip writer
191
+ └── utils/
192
+ ├── __init__.py # Re-exports shared utility functions
193
+ ├── coords.py # Pure-Python coordinate/column converters (col_to_idx, parse_coord, etc.)
194
+ ├── xml_text.py # XML 1.0 text sanitization & Excel 1900 serial date conversion
195
+ └── zip_io.py # Streaming zip entry helpers, ZipInfo cloning, and OOXML path resolution
196
+ ```
197
+
198
+ ---
199
+
200
+ ## Current MVP Limitations
201
+
202
+ * **Cell Value & Formula Updates Only:** Does not insert/delete rows (shifting formulas) or auto-resize Excel Tables (`xl/tables/tableN.xml`).
203
+ * **Date Cells Require Existing Date Formatting:** `date` and `datetime` values serialize to Excel serial numbers; the target cell must already have a date number format style (`s`) in the template to render as a date rather than a number.
204
+ * **No New Style Creation:** Can inherit or assign existing `s` style indices from the workbook, but does not author new entries in `xl/styles.xml`.
wixlf-0.1.1/README.md ADDED
@@ -0,0 +1,185 @@
1
+ # WIXLF — Write Into XLSX Files
2
+
3
+ A high-performance, constant-memory Python 3.14+ library for modifying existing Excel (`.xlsx` / `.xlsm`) workbooks. Instead of deserializing the entire workbook DOM into memory like `openpyxl`, **WIXLF** streams modified worksheets row-by-row via `lxml` while copying untouched archive parts byte-for-byte.
4
+
5
+ #### Why openpyxl Is Slow & Limiting for Existing Files
6
+ If you are designing a streamlined writer specifically for modifying existing files, openpyxl suffers from four architectural bottlenecks you can avoid:
7
+
8
+ * Full DOM Deserialization: Even to change a single cell (ws['A1'] = 5), openpyxl parses every XML file in the .xlsx zip archive (sharedStrings.xml, styles.xml, all sheetN.xml files) into heavy Python objects and re-serializes everything on save(). A streaming XML/zip-patching approach that only rewrites the modified sheetN.xml (and calcChain.xml if needed) is orders of magnitude faster.
9
+
10
+ * No write_only Mode for Existing Files: openpyxl restricts its fast lxml-backed streaming writer (write_only=True) to brand-new workbooks. You cannot stream-append rows to an existing template without loading the whole file into memory.
11
+
12
+ * Destructive Round-Tripping: Because openpyxl only rebuilds XML elements it explicitly models, opening and saving an existing workbook silently strips unsupported features—such as shapes, SmartArt, form controls, slicers, and certain pivot table/chart properties. Preserving untouched XML parts verbatim inside the zip archive avoids this completely.
13
+
14
+ * No Automatic Formula Shifting: Inserting/deleting rows or appending data into existing Excel Tables (ListObject in xl/tables/tableN.xml) requires manual updates to table ranges and formulas in openpyxl.
15
+
16
+ ---
17
+
18
+ ## Key Features
19
+
20
+ * **Constant $O(1)$ Memory Footprint:** Streams `<worksheet>` XML via `lxml.etree.iterparse` + `lxml.etree.xmlfile` with immediate DOM node pruning (`elem.clear()` and preceding-sibling deletion), keeping RAM flat even on multi-hundred-megabyte sheets.
21
+ * **Per-Worksheet Multiprocessing:** Automatically dispatches modified worksheets across a `ProcessPoolExecutor` (bypassing the GIL) when editing multiple sheets or sheets $\ge$ 512 KB, while running single small edits inline to avoid process spawn overhead.
22
+ * **Lossless Workbook Round-Tripping:** Untouched worksheets, `styles.xml`, themes, charts, pivot tables, drawings, media, and VBA macros (`.xlsm`) are streamed straight from source to destination in 1 MB chunks without parsing or stripping unsupported OOXML tags.
23
+ * **Automatic Style Inheritance:** Overwriting an existing cell preserves its original Excel style index (`s` attribute—fonts, fills, borders, number formats) unless explicitly overridden or cleared.
24
+ * **Zero `sharedStrings.xml` Contention:** Writes text values using OOXML `inlineStr` (`<c t="inlineStr"><is><t>...</t></is></c>`), eliminating shared-string table locks and enabling safe parallel sheet processing.
25
+ * **Automatic Formula Recalculation Safety:** Strips stale `xl/calcChain.xml` references from `[Content_Types].xml` and `xl/_rels/workbook.xml.rels` and sets `fullCalcOnLoad="1"` in `xl/workbook.xml` so Excel recalculates dependent formulas cleanly on open.
26
+ * **Atomic File Replacement:** Writes to a staged temporary `.xlsx` file in the target directory and promotes it via `os.replace()`, preventing half-written or corrupted outputs on failure.
27
+ * **Pure-Python Utilities (Zero Regex):** Cell coordinate parsing and XML 1.0 character sanitization use pure ASCII character scanning and C-level `str.translate()`.
28
+
29
+ ---
30
+
31
+ ## Installation
32
+
33
+ Requires **Python 3.14+** and `lxml`:
34
+
35
+ ```bash
36
+ pip install wixlf
37
+ ```
38
+
39
+ Or install from source:
40
+
41
+ ```bash
42
+ pip install -e .
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Quick Start
48
+
49
+ ### High-Level API (`wixlf.patch_workbook`)
50
+
51
+ ```python
52
+ import wixlf
53
+
54
+ wixlf.patch_workbook(
55
+ "template.xlsx",
56
+ "output.xlsx",
57
+ {
58
+ "Sales": {
59
+ "A1": "Q4 Revenue Report",
60
+ "B2": 149500.75,
61
+ "C2": True,
62
+ "D2": "=B2*0.21",
63
+ },
64
+ "Summary": {
65
+ (2, 1): "Total",
66
+ (2, 2): "=SUM(Sales!B2:B500)",
67
+ },
68
+ },
69
+ )
70
+ ```
71
+
72
+ ### Lower-Level Pipeline API
73
+
74
+ Use `PackageReader`, `SheetEditPlan`, and `PackageAssembler` directly when you need fine-grained control over worker count, chunk sizes, or pre-compiled edit plans:
75
+
76
+ ```python
77
+ from wixlf import (
78
+ PackageAssembler,
79
+ PackageReader,
80
+ SheetEditPlan,
81
+ patch_sheet_worker,
82
+ )
83
+
84
+ # 1. Resolve human-readable sheet names to internal zip paths
85
+ reader = PackageReader("template.xlsx")
86
+ sheets = reader.get_sheets()
87
+
88
+ # 2. Pre-sort edits into immutable, picklable plans per sheet
89
+ dirty_edits = {
90
+ sheets["Sales"].zip_path: SheetEditPlan.from_dict({
91
+ "A1": "Q4 Revenue Report",
92
+ "B2": 149500.75,
93
+ }),
94
+ }
95
+
96
+ # 3. Execute parallel sheet streaming & atomic archive assembly
97
+ assembler = PackageAssembler(
98
+ src_path="template.xlsx",
99
+ dst_path="output.xlsx",
100
+ max_workers=4, # Defaults to os.process_cpu_count()
101
+ chunk_size=2 * 1024 * 1024, # 2 MB zip stream copy buffer
102
+ )
103
+ assembler.build(
104
+ dirty_edits=dirty_edits,
105
+ patch_fn=patch_sheet_worker,
106
+ force_recalc=True,
107
+ )
108
+ ```
109
+
110
+ ---
111
+
112
+ ## Supported Cell Types & Styling
113
+
114
+ ### 1. Data Types & Formulas
115
+
116
+ `SheetEditPlan.from_dict()` accepts A1-style coordinates (`"B5"`, `"$AA$10"`) or 1-based `(row, col)` tuples (`(5, 2)`):
117
+
118
+ ```python
119
+ from datetime import date, datetime, time
120
+ from wixlf import SheetEditPlan
121
+
122
+ plan = SheetEditPlan.from_dict({
123
+ "A2": "Plain text (auto-strips illegal XML 1.0 control chars)",
124
+ "B2": " Leading/trailing spaces (auto-sets xml:space='preserve') ",
125
+ "C2": 42, # Integer
126
+ "D2": 3.14159, # Float (NaN/Inf serializes as #NUM!)
127
+ "E2": True, # Boolean (OOXML t="b")
128
+ "F2": date(2026, 11, 16), # Converted to Excel 1900 serial number
129
+ "G2": datetime(2026, 11, 16, 14, 30),
130
+ "H2": time(9, 15, 0),
131
+ "I2": "=SUM(C2:D2)", # Formula (leading '=' stripped for OOXML <f>)
132
+ "J2": None, # Clears cell value while keeping cell style
133
+ })
134
+ ```
135
+
136
+ ### 2. Overriding or Clearing Cell Styles
137
+
138
+ ```python
139
+ from wixlf import CellEdit, RowEditBatch, SheetEditPlan
140
+
141
+ # Option A: Assign explicit style indices ('s' from xl/styles.xml)
142
+ plan = SheetEditPlan.from_dict(
143
+ cell_map={"A10": 9999.95, "B10": "Total"},
144
+ styles={"A10": "14", "B10": "15"},
145
+ )
146
+
147
+ # Option B: Strip styling from specific cells
148
+ custom_plan = SheetEditPlan(
149
+ rows=(
150
+ RowEditBatch(
151
+ row=10,
152
+ cells=(
153
+ CellEdit(row=10, col=1, value="Unstyled Reset", clear_style=True),
154
+ ),
155
+ ),
156
+ )
157
+ )
158
+ ```
159
+
160
+ ---
161
+
162
+ ## Package Architecture
163
+
164
+ ```text
165
+ src/wixlf/
166
+ ├── __init__.py # Public API exports + patch_workbook() facade
167
+ ├── constants.py # OOXML namespaces, QName tags, content-types, and type aliases
168
+ ├── models.py # Immutable slotted dataclasses (SheetInfo, CellEdit, RowEditBatch, SheetEditPlan)
169
+ ├── reader.py # PackageReader: resolves sheet names to internal zip XML paths
170
+ ├── patcher.py # SheetStreamPatcher & patch_sheet_worker: O(1) memory XML stream patcher
171
+ ├── assembler.py # PackageAssembler: ProcessPoolExecutor orchestrator & atomic zip writer
172
+ └── utils/
173
+ ├── __init__.py # Re-exports shared utility functions
174
+ ├── coords.py # Pure-Python coordinate/column converters (col_to_idx, parse_coord, etc.)
175
+ ├── xml_text.py # XML 1.0 text sanitization & Excel 1900 serial date conversion
176
+ └── zip_io.py # Streaming zip entry helpers, ZipInfo cloning, and OOXML path resolution
177
+ ```
178
+
179
+ ---
180
+
181
+ ## Current MVP Limitations
182
+
183
+ * **Cell Value & Formula Updates Only:** Does not insert/delete rows (shifting formulas) or auto-resize Excel Tables (`xl/tables/tableN.xml`).
184
+ * **Date Cells Require Existing Date Formatting:** `date` and `datetime` values serialize to Excel serial numbers; the target cell must already have a date number format style (`s`) in the template to render as a date rather than a number.
185
+ * **No New Style Creation:** Can inherit or assign existing `s` style indices from the workbook, but does not author new entries in `xl/styles.xml`.
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "wixlf"
7
+ version = "0.1.1"
8
+ description = "Write Into XLSX Files — constant-memory, multiprocess streaming writer for existing .xlsx/.xlsm workbooks."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.14"
12
+ authors = [
13
+ { name = "chinchilak" },
14
+ ]
15
+ keywords = ["excel", "xlsx", "xlsm", "lxml", "streaming", "openpyxl", "wixlf"]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Intended Audience :: Developers",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.14",
22
+ "Topic :: Office/Business :: Financial :: Spreadsheet",
23
+ ]
24
+ dependencies = [
25
+ "lxml>=5.3.0",
26
+ ]
27
+
28
+ [project.urls]
29
+ Homepage = "https://github.com/chinchilak/wixlf"
30
+ Issues = "https://github.com/chinchilak/wixlf/issues"
31
+
32
+ [tool.hatch.build.targets.wheel]
33
+ packages = ["src/wixlf"]
@@ -0,0 +1 @@
1
+ lxml>=5.3.0
@@ -0,0 +1,56 @@
1
+ from collections.abc import Mapping
2
+ from pathlib import Path
3
+
4
+ from .assembler import PackageAssembler
5
+ from .constants import CellScalar, PatchWorkerFn
6
+ from .models import CellEdit, RowEditBatch, SheetEditPlan, SheetInfo
7
+ from .patcher import SheetStreamPatcher, patch_sheet_worker
8
+ from .reader import PackageReader
9
+
10
+ __version__ = "0.1.0"
11
+
12
+ __all__ = [
13
+ "CellEdit",
14
+ "CellScalar",
15
+ "PackageAssembler",
16
+ "PackageReader",
17
+ "PatchWorkerFn",
18
+ "RowEditBatch",
19
+ "SheetEditPlan",
20
+ "SheetInfo",
21
+ "SheetStreamPatcher",
22
+ "__version__",
23
+ "patch_sheet_worker",
24
+ "patch_workbook",
25
+ ]
26
+
27
+
28
+ def patch_workbook(
29
+ src_path: str | Path,
30
+ dst_path: str | Path,
31
+ edits_by_sheet: Mapping[str, Mapping[str | tuple[int, int], CellScalar] | SheetEditPlan],
32
+ *,
33
+ max_workers: int | None = None,
34
+ force_recalc: bool = True,
35
+ ) -> None:
36
+ """High-level convenience wrapper to patch multiple sheets by name."""
37
+ reader = PackageReader(src_path)
38
+ sheets = reader.get_sheets()
39
+
40
+ dirty_edits: dict[str, SheetEditPlan] = {}
41
+ for sheet_name, edits in edits_by_sheet.items():
42
+ if sheet_name not in sheets:
43
+ raise KeyError(f"Worksheet {sheet_name!r} not found in {src_path}")
44
+ plan = (
45
+ edits
46
+ if isinstance(edits, SheetEditPlan)
47
+ else SheetEditPlan.from_dict(edits)
48
+ )
49
+ dirty_edits[sheets[sheet_name].zip_path] = plan
50
+
51
+ assembler = PackageAssembler(src_path, dst_path, max_workers=max_workers)
52
+ assembler.build(
53
+ dirty_edits=dirty_edits,
54
+ patch_fn=patch_sheet_worker,
55
+ force_recalc=force_recalc,
56
+ )