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.
- wixlf-0.1.1/.github/workflows/publish.yml +49 -0
- wixlf-0.1.1/PKG-INFO +204 -0
- wixlf-0.1.1/README.md +185 -0
- wixlf-0.1.1/pyproject.toml +33 -0
- wixlf-0.1.1/requirements.txt +1 -0
- wixlf-0.1.1/src/wixlf/__init__.py +56 -0
- wixlf-0.1.1/src/wixlf/assembler.py +220 -0
- wixlf-0.1.1/src/wixlf/constants.py +34 -0
- wixlf-0.1.1/src/wixlf/models.py +82 -0
- wixlf-0.1.1/src/wixlf/patcher.py +281 -0
- wixlf-0.1.1/src/wixlf/reader.py +54 -0
- wixlf-0.1.1/src/wixlf/utils/__init__.py +21 -0
- wixlf-0.1.1/src/wixlf/utils/coords.py +53 -0
- wixlf-0.1.1/src/wixlf/utils/xml_text.py +47 -0
- wixlf-0.1.1/src/wixlf/utils/zip_io.py +46 -0
|
@@ -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
|
+
)
|