wixlf 0.1.1__py3-none-any.whl
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/__init__.py +56 -0
- wixlf/assembler.py +220 -0
- wixlf/constants.py +34 -0
- wixlf/models.py +82 -0
- wixlf/patcher.py +281 -0
- wixlf/reader.py +54 -0
- wixlf/utils/__init__.py +21 -0
- wixlf/utils/coords.py +53 -0
- wixlf/utils/xml_text.py +47 -0
- wixlf/utils/zip_io.py +46 -0
- wixlf-0.1.1.dist-info/METADATA +204 -0
- wixlf-0.1.1.dist-info/RECORD +13 -0
- wixlf-0.1.1.dist-info/WHEEL +4 -0
wixlf/__init__.py
ADDED
|
@@ -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
|
+
)
|
wixlf/assembler.py
ADDED
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import shutil
|
|
3
|
+
import tempfile
|
|
4
|
+
import zipfile
|
|
5
|
+
from collections.abc import Mapping
|
|
6
|
+
from concurrent.futures import ProcessPoolExecutor, as_completed
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
from lxml import etree
|
|
11
|
+
|
|
12
|
+
from .constants import (
|
|
13
|
+
CALC_CHAIN_CT,
|
|
14
|
+
CALC_CHAIN_PATH,
|
|
15
|
+
CALC_CHAIN_REL_TYPE,
|
|
16
|
+
NS_CT,
|
|
17
|
+
NS_MAIN,
|
|
18
|
+
NS_REL_PKG,
|
|
19
|
+
PatchWorkerFn,
|
|
20
|
+
)
|
|
21
|
+
from .utils.zip_io import clone_zip_info, copy_disk_file_to_zip, stream_zip_entry
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _worker_entrypoint(
|
|
25
|
+
patch_fn: PatchWorkerFn,
|
|
26
|
+
src_path: str,
|
|
27
|
+
sheet_zip_path: str,
|
|
28
|
+
edits: Any,
|
|
29
|
+
temp_dir: str,
|
|
30
|
+
) -> tuple[str, str]:
|
|
31
|
+
"""
|
|
32
|
+
Top-level picklable wrapper executed in worker processes.
|
|
33
|
+
Writes patched XML to a temp file and returns (sheet_zip_path, temp_file_path).
|
|
34
|
+
"""
|
|
35
|
+
fd, tmp_xml_path = tempfile.mkstemp(
|
|
36
|
+
prefix="sheet_patch_", suffix=".xml", dir=temp_dir
|
|
37
|
+
)
|
|
38
|
+
os.close(fd)
|
|
39
|
+
try:
|
|
40
|
+
patch_fn(src_path, sheet_zip_path, edits, tmp_xml_path)
|
|
41
|
+
return sheet_zip_path, tmp_xml_path
|
|
42
|
+
except Exception:
|
|
43
|
+
if os.path.exists(tmp_xml_path):
|
|
44
|
+
os.remove(tmp_xml_path)
|
|
45
|
+
raise
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class PackageAssembler:
|
|
49
|
+
"""
|
|
50
|
+
Coordinates multiprocessing across dirty sheets and streams untouched + patched
|
|
51
|
+
entries into the output .xlsx archive while cleanly stripping calcChain.xml.
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
# Avoid process spawn overhead when modifying a single tiny worksheet (< 512 KB)
|
|
55
|
+
PARALLEL_SIZE_THRESHOLD_BYTES = 512 * 1024
|
|
56
|
+
|
|
57
|
+
def __init__(
|
|
58
|
+
self,
|
|
59
|
+
src_path: str | Path,
|
|
60
|
+
dst_path: str | Path,
|
|
61
|
+
max_workers: int | None = None,
|
|
62
|
+
chunk_size: int = 1024 * 1024, # 1 MB streaming buffer
|
|
63
|
+
) -> None:
|
|
64
|
+
self.src_path = Path(src_path)
|
|
65
|
+
self.dst_path = Path(dst_path)
|
|
66
|
+
self.max_workers = max_workers or os.process_cpu_count() or 1
|
|
67
|
+
self.chunk_size = chunk_size
|
|
68
|
+
|
|
69
|
+
def build(
|
|
70
|
+
self,
|
|
71
|
+
dirty_edits: Mapping[str, Any],
|
|
72
|
+
patch_fn: PatchWorkerFn,
|
|
73
|
+
force_recalc: bool = True,
|
|
74
|
+
) -> None:
|
|
75
|
+
"""
|
|
76
|
+
dirty_edits: {sheet_zip_path: sorted_edit_plan}
|
|
77
|
+
patch_fn: Top-level picklable function implementing SheetStreamPatcher
|
|
78
|
+
force_recalc: Removes calcChain.xml and sets fullCalcOnLoad="1"
|
|
79
|
+
"""
|
|
80
|
+
if not dirty_edits:
|
|
81
|
+
shutil.copy2(self.src_path, self.dst_path)
|
|
82
|
+
return
|
|
83
|
+
|
|
84
|
+
with tempfile.TemporaryDirectory(prefix="xlsx_build_") as temp_dir:
|
|
85
|
+
patched_files = self._run_sheet_workers(dirty_edits, patch_fn, temp_dir)
|
|
86
|
+
self._assemble_zip(patched_files, strip_calc_chain=force_recalc)
|
|
87
|
+
|
|
88
|
+
def _run_sheet_workers(
|
|
89
|
+
self,
|
|
90
|
+
dirty_edits: Mapping[str, Any],
|
|
91
|
+
patch_fn: PatchWorkerFn,
|
|
92
|
+
temp_dir: str,
|
|
93
|
+
) -> dict[str, str]:
|
|
94
|
+
"""Dispatches dirty sheets to ProcessPoolExecutor or runs inline if small."""
|
|
95
|
+
with zipfile.ZipFile(self.src_path, "r") as zin:
|
|
96
|
+
sheet_sizes = {
|
|
97
|
+
path: zin.getinfo(path).file_size for path in dirty_edits
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
use_multiprocessing = len(dirty_edits) > 1 or any(
|
|
101
|
+
sz >= self.PARALLEL_SIZE_THRESHOLD_BYTES for sz in sheet_sizes.values()
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
patched_map: dict[str, str] = {}
|
|
105
|
+
src_str = str(self.src_path)
|
|
106
|
+
|
|
107
|
+
if not use_multiprocessing:
|
|
108
|
+
for sheet_path, edits in dirty_edits.items():
|
|
109
|
+
path, tmp_file = _worker_entrypoint(
|
|
110
|
+
patch_fn, src_str, sheet_path, edits, temp_dir
|
|
111
|
+
)
|
|
112
|
+
patched_map[path] = tmp_file
|
|
113
|
+
return patched_map
|
|
114
|
+
|
|
115
|
+
workers = min(self.max_workers, len(dirty_edits))
|
|
116
|
+
with ProcessPoolExecutor(max_workers=workers) as pool:
|
|
117
|
+
futures = {
|
|
118
|
+
pool.submit(
|
|
119
|
+
_worker_entrypoint,
|
|
120
|
+
patch_fn,
|
|
121
|
+
src_str,
|
|
122
|
+
sheet_path,
|
|
123
|
+
edits,
|
|
124
|
+
temp_dir,
|
|
125
|
+
): sheet_path
|
|
126
|
+
for sheet_path, edits in dirty_edits.items()
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
for future in as_completed(futures):
|
|
130
|
+
sheet_path, tmp_file = future.result()
|
|
131
|
+
patched_map[sheet_path] = tmp_file
|
|
132
|
+
|
|
133
|
+
return patched_map
|
|
134
|
+
|
|
135
|
+
def _assemble_zip(
|
|
136
|
+
self, patched_files: Mapping[str, str], strip_calc_chain: bool
|
|
137
|
+
) -> None:
|
|
138
|
+
"""Streams entries into the destination archive without buffering whole files."""
|
|
139
|
+
dst_dir = self.dst_path.parent
|
|
140
|
+
dst_dir.mkdir(parents=True, exist_ok=True)
|
|
141
|
+
fd, staging_zip = tempfile.mkstemp(
|
|
142
|
+
prefix=".tmp_xlsx_", suffix=".xlsx", dir=dst_dir
|
|
143
|
+
)
|
|
144
|
+
os.close(fd)
|
|
145
|
+
|
|
146
|
+
try:
|
|
147
|
+
with (
|
|
148
|
+
zipfile.ZipFile(self.src_path, "r") as zin,
|
|
149
|
+
zipfile.ZipFile(
|
|
150
|
+
staging_zip, "w", compression=zipfile.ZIP_DEFLATED
|
|
151
|
+
) as zout,
|
|
152
|
+
):
|
|
153
|
+
for info in zin.infolist():
|
|
154
|
+
name = info.filename
|
|
155
|
+
|
|
156
|
+
if strip_calc_chain and name == CALC_CHAIN_PATH:
|
|
157
|
+
continue
|
|
158
|
+
|
|
159
|
+
if name in patched_files:
|
|
160
|
+
copy_disk_file_to_zip(
|
|
161
|
+
zout, info, patched_files[name], self.chunk_size
|
|
162
|
+
)
|
|
163
|
+
continue
|
|
164
|
+
|
|
165
|
+
if strip_calc_chain and name == "[Content_Types].xml":
|
|
166
|
+
cleaned = self._strip_calc_chain_content_type(zin.read(name))
|
|
167
|
+
zout.writestr(clone_zip_info(info), cleaned)
|
|
168
|
+
continue
|
|
169
|
+
|
|
170
|
+
if strip_calc_chain and name == "xl/_rels/workbook.xml.rels":
|
|
171
|
+
cleaned = self._strip_calc_chain_rel(zin.read(name))
|
|
172
|
+
zout.writestr(clone_zip_info(info), cleaned)
|
|
173
|
+
continue
|
|
174
|
+
|
|
175
|
+
if strip_calc_chain and name == "xl/workbook.xml":
|
|
176
|
+
updated = self._enable_full_calc_on_load(zin.read(name))
|
|
177
|
+
zout.writestr(clone_zip_info(info), updated)
|
|
178
|
+
continue
|
|
179
|
+
|
|
180
|
+
stream_zip_entry(zin, zout, info, self.chunk_size)
|
|
181
|
+
|
|
182
|
+
os.replace(staging_zip, self.dst_path)
|
|
183
|
+
except Exception:
|
|
184
|
+
if os.path.exists(staging_zip):
|
|
185
|
+
os.remove(staging_zip)
|
|
186
|
+
raise
|
|
187
|
+
|
|
188
|
+
@staticmethod
|
|
189
|
+
def _strip_calc_chain_content_type(xml_bytes: bytes) -> bytes:
|
|
190
|
+
root = etree.fromstring(xml_bytes)
|
|
191
|
+
for override in root.findall(f"{{{NS_CT}}}Override"):
|
|
192
|
+
if (
|
|
193
|
+
override.get("PartName") == "/xl/calcChain.xml"
|
|
194
|
+
or override.get("ContentType") == CALC_CHAIN_CT
|
|
195
|
+
):
|
|
196
|
+
root.remove(override)
|
|
197
|
+
return etree.tostring(
|
|
198
|
+
root, xml_declaration=True, encoding="UTF-8", standalone=True
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
@staticmethod
|
|
202
|
+
def _strip_calc_chain_rel(xml_bytes: bytes) -> bytes:
|
|
203
|
+
root = etree.fromstring(xml_bytes)
|
|
204
|
+
for rel in root.findall(f"{{{NS_REL_PKG}}}Relationship"):
|
|
205
|
+
if rel.get("Type") == CALC_CHAIN_REL_TYPE:
|
|
206
|
+
root.remove(rel)
|
|
207
|
+
return etree.tostring(
|
|
208
|
+
root, xml_declaration=True, encoding="UTF-8", standalone=True
|
|
209
|
+
)
|
|
210
|
+
|
|
211
|
+
@staticmethod
|
|
212
|
+
def _enable_full_calc_on_load(xml_bytes: bytes) -> bytes:
|
|
213
|
+
root = etree.fromstring(xml_bytes)
|
|
214
|
+
calc_pr = root.find(f"{{{NS_MAIN}}}calcPr")
|
|
215
|
+
if calc_pr is None:
|
|
216
|
+
calc_pr = etree.SubElement(root, f"{{{NS_MAIN}}}calcPr")
|
|
217
|
+
calc_pr.set("fullCalcOnLoad", "1")
|
|
218
|
+
return etree.tostring(
|
|
219
|
+
root, xml_declaration=True, encoding="UTF-8", standalone=True
|
|
220
|
+
)
|
wixlf/constants.py
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
from collections.abc import Callable
|
|
2
|
+
from datetime import date, datetime, time
|
|
3
|
+
from typing import Any, Final
|
|
4
|
+
|
|
5
|
+
# OOXML Namespaces
|
|
6
|
+
NS_MAIN: Final[str] = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
|
|
7
|
+
NS_REL_DOC: Final[str] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
|
|
8
|
+
NS_REL_PKG: Final[str] = "http://schemas.openxmlformats.org/package/2006/relationships"
|
|
9
|
+
NS_CT: Final[str] = "http://schemas.openxmlformats.org/package/2006/content-types"
|
|
10
|
+
NS_XML: Final[str] = "http://www.w3.org/XML/1998/namespace"
|
|
11
|
+
|
|
12
|
+
# Pre-qualified SpreadsheetML element tags
|
|
13
|
+
TAG_WORKSHEET: Final[str] = f"{{{NS_MAIN}}}worksheet"
|
|
14
|
+
TAG_SHEET_DATA: Final[str] = f"{{{NS_MAIN}}}sheetData"
|
|
15
|
+
TAG_DIMENSION: Final[str] = f"{{{NS_MAIN}}}dimension"
|
|
16
|
+
TAG_ROW: Final[str] = f"{{{NS_MAIN}}}row"
|
|
17
|
+
TAG_CELL: Final[str] = f"{{{NS_MAIN}}}c"
|
|
18
|
+
TAG_VALUE: Final[str] = f"{{{NS_MAIN}}}v"
|
|
19
|
+
TAG_FORMULA: Final[str] = f"{{{NS_MAIN}}}f"
|
|
20
|
+
TAG_INLINE_STR: Final[str] = f"{{{NS_MAIN}}}is"
|
|
21
|
+
TAG_TEXT: Final[str] = f"{{{NS_MAIN}}}t"
|
|
22
|
+
|
|
23
|
+
# Calculation chain identifiers
|
|
24
|
+
CALC_CHAIN_PATH: Final[str] = "xl/calcChain.xml"
|
|
25
|
+
CALC_CHAIN_CT: Final[str] = (
|
|
26
|
+
"application/vnd.openxmlformats-officedocument.spreadsheetml.calcChain+xml"
|
|
27
|
+
)
|
|
28
|
+
CALC_CHAIN_REL_TYPE: Final[str] = (
|
|
29
|
+
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain"
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
# PEP 695 native type aliases
|
|
33
|
+
type CellScalar = str | int | float | bool | date | datetime | time | None
|
|
34
|
+
type PatchWorkerFn = Callable[[str, str, Any, str], None]
|
wixlf/models.py
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
from collections.abc import Mapping
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
|
|
4
|
+
from .constants import CellScalar
|
|
5
|
+
from .utils.coords import parse_coord
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@dataclass(frozen=True, slots=True)
|
|
9
|
+
class SheetInfo:
|
|
10
|
+
"""Metadata mapping a human-readable worksheet name to its internal zip entry."""
|
|
11
|
+
|
|
12
|
+
name: str
|
|
13
|
+
sheet_id: str
|
|
14
|
+
rel_id: str
|
|
15
|
+
zip_path: str # e.g., "xl/worksheets/sheet1.xml"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass(frozen=True, slots=True)
|
|
19
|
+
class CellEdit:
|
|
20
|
+
"""Represents a single cell mutation."""
|
|
21
|
+
|
|
22
|
+
row: int
|
|
23
|
+
col: int
|
|
24
|
+
value: CellScalar
|
|
25
|
+
style_id: str | None = None # Optional explicit 's' attribute override
|
|
26
|
+
clear_style: bool = False
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True, slots=True)
|
|
30
|
+
class RowEditBatch:
|
|
31
|
+
"""Sorted cell mutations belonging to a single row."""
|
|
32
|
+
|
|
33
|
+
row: int
|
|
34
|
+
cells: tuple[CellEdit, ...] # Strictly sorted by col ascending
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True, slots=True)
|
|
38
|
+
class SheetEditPlan:
|
|
39
|
+
"""
|
|
40
|
+
Pre-sorted, immutable, picklable edit plan for a single worksheet.
|
|
41
|
+
Passed safely across ProcessPoolExecutor boundaries.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
rows: tuple[RowEditBatch, ...] # Strictly sorted by row ascending
|
|
45
|
+
|
|
46
|
+
@classmethod
|
|
47
|
+
def from_dict(
|
|
48
|
+
cls,
|
|
49
|
+
cell_map: Mapping[str | tuple[int, int], CellScalar],
|
|
50
|
+
styles: Mapping[str | tuple[int, int], str] | None = None,
|
|
51
|
+
) -> SheetEditPlan:
|
|
52
|
+
"""
|
|
53
|
+
Compiles an unsorted mapping like {'B5': 42, (1, 1): 'Title'} into a
|
|
54
|
+
strictly sorted SheetEditPlan ready for single-pass streaming.
|
|
55
|
+
"""
|
|
56
|
+
by_row: dict[int, dict[int, CellEdit]] = {}
|
|
57
|
+
style_lookup: dict[tuple[int, int], str] = {}
|
|
58
|
+
|
|
59
|
+
if styles:
|
|
60
|
+
for key, s_id in styles.items():
|
|
61
|
+
r, c = parse_coord(key) if isinstance(key, str) else key
|
|
62
|
+
style_lookup[(r, c)] = str(s_id)
|
|
63
|
+
|
|
64
|
+
for key, val in cell_map.items():
|
|
65
|
+
r, c = parse_coord(key) if isinstance(key, str) else key
|
|
66
|
+
if r < 1 or c < 1:
|
|
67
|
+
raise ValueError(f"Row and column must be >= 1, got ({r}, {c})")
|
|
68
|
+
by_row.setdefault(r, {})[c] = CellEdit(
|
|
69
|
+
row=r,
|
|
70
|
+
col=c,
|
|
71
|
+
value=val,
|
|
72
|
+
style_id=style_lookup.get((r, c)),
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
sorted_batches = tuple(
|
|
76
|
+
RowEditBatch(
|
|
77
|
+
row=r,
|
|
78
|
+
cells=tuple(by_row[r][c] for c in sorted(by_row[r])),
|
|
79
|
+
)
|
|
80
|
+
for r in sorted(by_row)
|
|
81
|
+
)
|
|
82
|
+
return cls(rows=sorted_batches)
|
wixlf/patcher.py
ADDED
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
import math
|
|
2
|
+
import zipfile
|
|
3
|
+
from collections.abc import Sequence
|
|
4
|
+
from datetime import date, datetime, time
|
|
5
|
+
|
|
6
|
+
from lxml import etree
|
|
7
|
+
|
|
8
|
+
from .constants import (
|
|
9
|
+
NS_XML,
|
|
10
|
+
TAG_CELL,
|
|
11
|
+
TAG_DIMENSION,
|
|
12
|
+
TAG_FORMULA,
|
|
13
|
+
TAG_INLINE_STR,
|
|
14
|
+
TAG_ROW,
|
|
15
|
+
TAG_SHEET_DATA,
|
|
16
|
+
TAG_TEXT,
|
|
17
|
+
TAG_VALUE,
|
|
18
|
+
TAG_WORKSHEET,
|
|
19
|
+
)
|
|
20
|
+
from .models import CellEdit, RowEditBatch, SheetEditPlan
|
|
21
|
+
from .utils.coords import format_coord, parse_coord
|
|
22
|
+
from .utils.xml_text import sanitize_xml_text, to_excel_serial
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class SheetStreamPatcher:
|
|
26
|
+
"""
|
|
27
|
+
Streams an existing worksheet XML from a zip archive and writes a patched
|
|
28
|
+
version to disk using constant O(1) memory.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
def __init__(self, drop_dimension_tag: bool = True) -> None:
|
|
32
|
+
# Dropping <dimension ref="A1:D10"/> prevents stale bounds if new rows/cols
|
|
33
|
+
# extend beyond the original range; Excel recalculates it cleanly on open.
|
|
34
|
+
self.drop_dimension_tag = drop_dimension_tag
|
|
35
|
+
|
|
36
|
+
def patch_from_zip(
|
|
37
|
+
self,
|
|
38
|
+
src_zip_path: str,
|
|
39
|
+
sheet_zip_path: str,
|
|
40
|
+
plan: SheetEditPlan,
|
|
41
|
+
out_xml_path: str,
|
|
42
|
+
) -> None:
|
|
43
|
+
"""Entrypoint compatible with PackageAssembler's PatchWorkerFn signature."""
|
|
44
|
+
with (
|
|
45
|
+
zipfile.ZipFile(src_zip_path, "r") as zin,
|
|
46
|
+
zin.open(sheet_zip_path, "r") as xml_in,
|
|
47
|
+
etree.xmlfile(out_xml_path, encoding="utf-8") as xf,
|
|
48
|
+
):
|
|
49
|
+
xf.write_declaration(standalone=True)
|
|
50
|
+
self._stream_transform(xml_in, xf, plan.rows)
|
|
51
|
+
|
|
52
|
+
def _stream_transform(
|
|
53
|
+
self,
|
|
54
|
+
xml_in: zipfile.ZipExtFile,
|
|
55
|
+
xf: etree.xmlfile,
|
|
56
|
+
row_batches: Sequence[RowEditBatch],
|
|
57
|
+
) -> None:
|
|
58
|
+
context = etree.iterparse(
|
|
59
|
+
xml_in,
|
|
60
|
+
events=("start", "end"),
|
|
61
|
+
recover=False,
|
|
62
|
+
huge_tree=True,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
# Peek at root <worksheet> start event to preserve exact namespaces/attrs
|
|
66
|
+
event, root_elem = next(context)
|
|
67
|
+
if event != "start" or root_elem.tag != TAG_WORKSHEET:
|
|
68
|
+
raise ValueError(f"Expected <worksheet> root, got {root_elem.tag}")
|
|
69
|
+
|
|
70
|
+
ws_attrib = dict(root_elem.attrib)
|
|
71
|
+
ws_nsmap = dict(root_elem.nsmap)
|
|
72
|
+
|
|
73
|
+
with xf.element(TAG_WORKSHEET, attrib=ws_attrib, nsmap=ws_nsmap):
|
|
74
|
+
in_sheet_data = False
|
|
75
|
+
sheet_data_written = False
|
|
76
|
+
batch_idx = 0
|
|
77
|
+
total_batches = len(row_batches)
|
|
78
|
+
|
|
79
|
+
for event, elem in context:
|
|
80
|
+
tag = elem.tag
|
|
81
|
+
|
|
82
|
+
# Track entry/exit of <sheetData>
|
|
83
|
+
if event == "start" and tag == TAG_SHEET_DATA:
|
|
84
|
+
in_sheet_data = True
|
|
85
|
+
sheet_data_written = True
|
|
86
|
+
sd_attrib = dict(elem.attrib)
|
|
87
|
+
sd_ctx = xf.element(TAG_SHEET_DATA, attrib=sd_attrib)
|
|
88
|
+
sd_ctx.__enter__()
|
|
89
|
+
continue
|
|
90
|
+
|
|
91
|
+
if event == "end" and tag == TAG_SHEET_DATA:
|
|
92
|
+
# Flush any remaining new rows that belong after the last existing row
|
|
93
|
+
while batch_idx < total_batches:
|
|
94
|
+
self._write_new_row(xf, row_batches[batch_idx])
|
|
95
|
+
batch_idx += 1
|
|
96
|
+
|
|
97
|
+
sd_ctx.__exit__(None, None, None)
|
|
98
|
+
in_sheet_data = False
|
|
99
|
+
self._prune_element(elem)
|
|
100
|
+
continue
|
|
101
|
+
|
|
102
|
+
# Inside <sheetData>: merge-join sorted edits against <row> stream
|
|
103
|
+
if in_sheet_data:
|
|
104
|
+
if event == "end" and tag == TAG_ROW:
|
|
105
|
+
row_num = int(elem.get("r", "0"))
|
|
106
|
+
|
|
107
|
+
# Insert any brand-new rows strictly preceding this existing row
|
|
108
|
+
while (
|
|
109
|
+
batch_idx < total_batches
|
|
110
|
+
and row_batches[batch_idx].row < row_num
|
|
111
|
+
):
|
|
112
|
+
self._write_new_row(xf, row_batches[batch_idx])
|
|
113
|
+
batch_idx += 1
|
|
114
|
+
|
|
115
|
+
# Patch existing row if it matches the current edit batch
|
|
116
|
+
if (
|
|
117
|
+
batch_idx < total_batches
|
|
118
|
+
and row_batches[batch_idx].row == row_num
|
|
119
|
+
):
|
|
120
|
+
self._patch_existing_row(elem, row_batches[batch_idx])
|
|
121
|
+
batch_idx += 1
|
|
122
|
+
|
|
123
|
+
xf.write(elem)
|
|
124
|
+
self._prune_element(elem)
|
|
125
|
+
continue
|
|
126
|
+
|
|
127
|
+
# Outside <sheetData>: pass top-level worksheet children through verbatim
|
|
128
|
+
if event == "end" and elem.getparent() is root_elem:
|
|
129
|
+
if self.drop_dimension_tag and tag == TAG_DIMENSION:
|
|
130
|
+
self._prune_element(elem)
|
|
131
|
+
continue
|
|
132
|
+
|
|
133
|
+
xf.write(elem)
|
|
134
|
+
self._prune_element(elem)
|
|
135
|
+
|
|
136
|
+
# Edge case: source worksheet had no <sheetData> tag at all
|
|
137
|
+
if not sheet_data_written and total_batches > 0:
|
|
138
|
+
with xf.element(TAG_SHEET_DATA):
|
|
139
|
+
for batch in row_batches:
|
|
140
|
+
self._write_new_row(xf, batch)
|
|
141
|
+
|
|
142
|
+
root_elem.clear()
|
|
143
|
+
|
|
144
|
+
def _patch_existing_row(
|
|
145
|
+
self, row_elem: etree._Element, batch: RowEditBatch
|
|
146
|
+
) -> None:
|
|
147
|
+
"""
|
|
148
|
+
Merges sorted CellEdits into an existing <row> element in linear time,
|
|
149
|
+
preserving existing cell styles ('s') unless overridden.
|
|
150
|
+
"""
|
|
151
|
+
existing_cells = list(row_elem)
|
|
152
|
+
new_children: list[etree._Element] = []
|
|
153
|
+
|
|
154
|
+
c_idx = 0
|
|
155
|
+
e_idx = 0
|
|
156
|
+
num_existing = len(existing_cells)
|
|
157
|
+
num_edits = len(batch.cells)
|
|
158
|
+
|
|
159
|
+
while c_idx < num_existing and e_idx < num_edits:
|
|
160
|
+
cell_elem = existing_cells[c_idx]
|
|
161
|
+
edit = batch.cells[e_idx]
|
|
162
|
+
_, existing_col = parse_coord(cell_elem.get("r", "A1"))
|
|
163
|
+
|
|
164
|
+
if existing_col < edit.col:
|
|
165
|
+
new_children.append(cell_elem)
|
|
166
|
+
c_idx += 1
|
|
167
|
+
elif existing_col > edit.col:
|
|
168
|
+
new_children.append(self._build_cell_element(edit, inherited_style=None))
|
|
169
|
+
e_idx += 1
|
|
170
|
+
else:
|
|
171
|
+
# Overwrite existing cell; inherit style unless explicitly changed
|
|
172
|
+
inherited_style = cell_elem.get("s")
|
|
173
|
+
new_children.append(
|
|
174
|
+
self._build_cell_element(edit, inherited_style=inherited_style)
|
|
175
|
+
)
|
|
176
|
+
c_idx += 1
|
|
177
|
+
e_idx += 1
|
|
178
|
+
|
|
179
|
+
while c_idx < num_existing:
|
|
180
|
+
new_children.append(existing_cells[c_idx])
|
|
181
|
+
c_idx += 1
|
|
182
|
+
|
|
183
|
+
while e_idx < num_edits:
|
|
184
|
+
new_children.append(
|
|
185
|
+
self._build_cell_element(batch.cells[e_idx], inherited_style=None)
|
|
186
|
+
)
|
|
187
|
+
e_idx += 1
|
|
188
|
+
|
|
189
|
+
# Replace row children in-place while keeping <row> attributes (ht, customHeight, s)
|
|
190
|
+
row_elem[:] = new_children
|
|
191
|
+
# Clear cached spans attribute if new columns may have widened the row
|
|
192
|
+
row_elem.attrib.pop("spans", None)
|
|
193
|
+
|
|
194
|
+
def _write_new_row(self, xf: etree.xmlfile, batch: RowEditBatch) -> None:
|
|
195
|
+
"""Streams a brand-new <row> element directly to xmlfile."""
|
|
196
|
+
row_elem = etree.Element(TAG_ROW, r=str(batch.row))
|
|
197
|
+
for edit in batch.cells:
|
|
198
|
+
row_elem.append(self._build_cell_element(edit, inherited_style=None))
|
|
199
|
+
xf.write(row_elem)
|
|
200
|
+
|
|
201
|
+
def _build_cell_element(
|
|
202
|
+
self, edit: CellEdit, inherited_style: str | None
|
|
203
|
+
) -> etree._Element:
|
|
204
|
+
"""Constructs a compliant OOXML <c> element for any scalar or formula."""
|
|
205
|
+
coord = format_coord(edit.row, edit.col)
|
|
206
|
+
c_elem = etree.Element(TAG_CELL, r=coord)
|
|
207
|
+
|
|
208
|
+
# Resolve style index ('s')
|
|
209
|
+
if not edit.clear_style:
|
|
210
|
+
final_style = edit.style_id if edit.style_id is not None else inherited_style
|
|
211
|
+
if final_style is not None:
|
|
212
|
+
c_elem.set("s", final_style)
|
|
213
|
+
|
|
214
|
+
val = edit.value
|
|
215
|
+
|
|
216
|
+
# 1. Empty / cleared cell (keeps style if present, omits type and value)
|
|
217
|
+
if val is None:
|
|
218
|
+
return c_elem
|
|
219
|
+
|
|
220
|
+
# 2. Boolean (must be checked before int because bool is a subclass of int)
|
|
221
|
+
if isinstance(val, bool):
|
|
222
|
+
c_elem.set("t", "b")
|
|
223
|
+
v_elem = etree.SubElement(c_elem, TAG_VALUE)
|
|
224
|
+
v_elem.text = "1" if val else "0"
|
|
225
|
+
return c_elem
|
|
226
|
+
|
|
227
|
+
# 3. Numeric (int / float)
|
|
228
|
+
if isinstance(val, (int, float)):
|
|
229
|
+
if isinstance(val, float) and (math.isnan(val) or math.isinf(val)):
|
|
230
|
+
c_elem.set("t", "e")
|
|
231
|
+
v_elem = etree.SubElement(c_elem, TAG_VALUE)
|
|
232
|
+
v_elem.text = "#NUM!"
|
|
233
|
+
else:
|
|
234
|
+
v_elem = etree.SubElement(c_elem, TAG_VALUE)
|
|
235
|
+
v_elem.text = repr(val) if isinstance(val, float) else str(val)
|
|
236
|
+
return c_elem
|
|
237
|
+
|
|
238
|
+
# 4. Date / Datetime / Time -> Excel serial number
|
|
239
|
+
if isinstance(val, (datetime, date, time)):
|
|
240
|
+
c_elem.set("t", "n")
|
|
241
|
+
v_elem = etree.SubElement(c_elem, TAG_VALUE)
|
|
242
|
+
v_elem.text = repr(to_excel_serial(val))
|
|
243
|
+
return c_elem
|
|
244
|
+
|
|
245
|
+
# 5. Formula vs. Inline String
|
|
246
|
+
if isinstance(val, str):
|
|
247
|
+
if val.startswith("="):
|
|
248
|
+
f_elem = etree.SubElement(c_elem, TAG_FORMULA)
|
|
249
|
+
f_elem.text = val[1:] # OOXML stores formulas without leading '='
|
|
250
|
+
# Omit <v> so Excel computes the fresh result on open
|
|
251
|
+
else:
|
|
252
|
+
clean_text = sanitize_xml_text(val)
|
|
253
|
+
c_elem.set("t", "inlineStr")
|
|
254
|
+
is_elem = etree.SubElement(c_elem, TAG_INLINE_STR)
|
|
255
|
+
t_elem = etree.SubElement(is_elem, TAG_TEXT)
|
|
256
|
+
if clean_text != clean_text.strip() or "\n" in clean_text:
|
|
257
|
+
t_elem.set(f"{{{NS_XML}}}space", "preserve")
|
|
258
|
+
t_elem.text = clean_text
|
|
259
|
+
return c_elem
|
|
260
|
+
|
|
261
|
+
raise TypeError(f"Unsupported cell value type: {type(val).__name__}")
|
|
262
|
+
|
|
263
|
+
@staticmethod
|
|
264
|
+
def _prune_element(elem: etree._Element) -> None:
|
|
265
|
+
"""Frees element memory and removes all already-processed preceding siblings."""
|
|
266
|
+
elem.clear()
|
|
267
|
+
parent = elem.getparent()
|
|
268
|
+
if parent is not None:
|
|
269
|
+
while elem.getprevious() is not None:
|
|
270
|
+
del parent[0]
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
# Top-level picklable worker function for PackageAssembler
|
|
274
|
+
def patch_sheet_worker(
|
|
275
|
+
src_zip_path: str,
|
|
276
|
+
sheet_zip_path: str,
|
|
277
|
+
plan: SheetEditPlan,
|
|
278
|
+
out_xml_path: str,
|
|
279
|
+
) -> None:
|
|
280
|
+
patcher = SheetStreamPatcher()
|
|
281
|
+
patcher.patch_from_zip(src_zip_path, sheet_zip_path, plan, out_xml_path)
|
wixlf/reader.py
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import zipfile
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
|
|
4
|
+
from lxml import etree
|
|
5
|
+
|
|
6
|
+
from .constants import NS_MAIN, NS_REL_DOC, NS_REL_PKG
|
|
7
|
+
from .models import SheetInfo
|
|
8
|
+
from .utils.zip_io import resolve_zip_path
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class PackageReader:
|
|
12
|
+
"""
|
|
13
|
+
Reads small OOXML metadata files from an existing .xlsx/.xlsm archive
|
|
14
|
+
to resolve human-readable sheet names to internal zip paths.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
def __init__(self, src_path: str | Path) -> None:
|
|
18
|
+
self.src_path = Path(src_path)
|
|
19
|
+
|
|
20
|
+
def get_sheets(self) -> dict[str, SheetInfo]:
|
|
21
|
+
"""Returns a mapping of {sheet_name: SheetInfo}."""
|
|
22
|
+
with zipfile.ZipFile(self.src_path, "r") as zin:
|
|
23
|
+
wb_rels = self._parse_relationships(zin, "xl/_rels/workbook.xml.rels")
|
|
24
|
+
wb_root = etree.fromstring(zin.read("xl/workbook.xml"))
|
|
25
|
+
|
|
26
|
+
sheets: dict[str, SheetInfo] = {}
|
|
27
|
+
for sheet_elem in wb_root.findall(f".//{{{NS_MAIN}}}sheet"):
|
|
28
|
+
name = sheet_elem.get("name")
|
|
29
|
+
sheet_id = sheet_elem.get("sheetId", "")
|
|
30
|
+
rel_id = sheet_elem.get(f"{{{NS_REL_DOC}}}id")
|
|
31
|
+
|
|
32
|
+
if not name or not rel_id or rel_id not in wb_rels:
|
|
33
|
+
continue
|
|
34
|
+
|
|
35
|
+
target = wb_rels[rel_id]
|
|
36
|
+
zip_path = resolve_zip_path("xl/workbook.xml", target)
|
|
37
|
+
sheets[name] = SheetInfo(
|
|
38
|
+
name=name,
|
|
39
|
+
sheet_id=sheet_id,
|
|
40
|
+
rel_id=rel_id,
|
|
41
|
+
zip_path=zip_path,
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
return sheets
|
|
45
|
+
|
|
46
|
+
@staticmethod
|
|
47
|
+
def _parse_relationships(zin: zipfile.ZipFile, rels_path: str) -> dict[str, str]:
|
|
48
|
+
"""Maps rId -> Target path."""
|
|
49
|
+
rels_root = etree.fromstring(zin.read(rels_path))
|
|
50
|
+
return {
|
|
51
|
+
rel_id: target
|
|
52
|
+
for rel in rels_root.findall(f"{{{NS_REL_PKG}}}Relationship")
|
|
53
|
+
if (rel_id := rel.get("Id")) and (target := rel.get("Target"))
|
|
54
|
+
}
|
wixlf/utils/__init__.py
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
from .coords import col_to_idx, format_coord, idx_to_col, parse_coord
|
|
2
|
+
from .xml_text import sanitize_xml_text, to_excel_serial
|
|
3
|
+
from .zip_io import (
|
|
4
|
+
clone_zip_info,
|
|
5
|
+
copy_disk_file_to_zip,
|
|
6
|
+
resolve_zip_path,
|
|
7
|
+
stream_zip_entry,
|
|
8
|
+
)
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"clone_zip_info",
|
|
12
|
+
"col_to_idx",
|
|
13
|
+
"copy_disk_file_to_zip",
|
|
14
|
+
"format_coord",
|
|
15
|
+
"idx_to_col",
|
|
16
|
+
"parse_coord",
|
|
17
|
+
"resolve_zip_path",
|
|
18
|
+
"sanitize_xml_text",
|
|
19
|
+
"stream_zip_entry",
|
|
20
|
+
"to_excel_serial",
|
|
21
|
+
]
|
wixlf/utils/coords.py
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
def col_to_idx(col_str: str) -> int:
|
|
2
|
+
"""Converts column letters ('A' -> 1, 'Z' -> 26, 'AA' -> 27) to 1-based index."""
|
|
3
|
+
idx = 0
|
|
4
|
+
for ch in col_str.upper():
|
|
5
|
+
idx = idx * 26 + (ord(ch) - 64)
|
|
6
|
+
return idx
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def idx_to_col(col_idx: int) -> str:
|
|
10
|
+
"""Converts 1-based column index (1 -> 'A', 27 -> 'AA') to column letters."""
|
|
11
|
+
chars: list[str] = []
|
|
12
|
+
n = col_idx
|
|
13
|
+
while n > 0:
|
|
14
|
+
n, rem = divmod(n - 1, 26)
|
|
15
|
+
chars.append(chr(65 + rem))
|
|
16
|
+
chars.reverse()
|
|
17
|
+
return "".join(chars)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def parse_coord(coord: str) -> tuple[int, int]:
|
|
21
|
+
"""
|
|
22
|
+
Parses 'AA105' or '$AA$105' into (row_idx, col_idx) 1-based integers
|
|
23
|
+
using pure string/character operations without regex.
|
|
24
|
+
"""
|
|
25
|
+
cleaned = coord.strip()
|
|
26
|
+
cleaned = cleaned.removeprefix("$")
|
|
27
|
+
|
|
28
|
+
split_idx = 0
|
|
29
|
+
length = len(cleaned)
|
|
30
|
+
while split_idx < length and cleaned[split_idx].isascii() and cleaned[split_idx].isalpha():
|
|
31
|
+
split_idx += 1
|
|
32
|
+
|
|
33
|
+
col_letters = cleaned[:split_idx]
|
|
34
|
+
row_part = cleaned[split_idx:]
|
|
35
|
+
row_part = row_part.removeprefix("$")
|
|
36
|
+
|
|
37
|
+
if (
|
|
38
|
+
not (1 <= len(col_letters) <= 3)
|
|
39
|
+
or not row_part
|
|
40
|
+
or not (row_part.isascii() and row_part.isdigit())
|
|
41
|
+
):
|
|
42
|
+
raise ValueError(f"Invalid Excel cell coordinate: {coord!r}")
|
|
43
|
+
|
|
44
|
+
row_idx = int(row_part)
|
|
45
|
+
if row_idx < 1:
|
|
46
|
+
raise ValueError(f"Invalid Excel cell coordinate: {coord!r}")
|
|
47
|
+
|
|
48
|
+
return row_idx, col_to_idx(col_letters)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def format_coord(row_idx: int, col_idx: int) -> str:
|
|
52
|
+
"""Formats 1-based (row_idx, col_idx) into 'AA105'."""
|
|
53
|
+
return f"{idx_to_col(col_idx)}{row_idx}"
|
wixlf/utils/xml_text.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
from datetime import date, datetime, time
|
|
2
|
+
from typing import Final
|
|
3
|
+
|
|
4
|
+
# Translation table mapping illegal XML 1.0 characters to None (fast C-level str.translate)
|
|
5
|
+
_ILLEGAL_XML_TRANS: Final[dict[int, None]] = dict.fromkeys(
|
|
6
|
+
[
|
|
7
|
+
*range(0x00, 0x09), # NUL..BS (keeps 0x09 TAB, 0x0A LF)
|
|
8
|
+
0x0B, # VT
|
|
9
|
+
0x0C, # FF (keeps 0x0D CR)
|
|
10
|
+
*range(0x0E, 0x20), # SO..US
|
|
11
|
+
*range(0xD800, 0xE000), # UTF-16 surrogates
|
|
12
|
+
0xFFFE,
|
|
13
|
+
0xFFFF,
|
|
14
|
+
],
|
|
15
|
+
None,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
# Excel 1900 epoch (with Excel's intentional 1900 leap-year bug offset)
|
|
19
|
+
_EXCEL_EPOCH: Final[datetime] = datetime(1899, 12, 30)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def sanitize_xml_text(text: str) -> str:
|
|
23
|
+
"""Strips characters forbidden in XML 1.0 using C-accelerated str.translate."""
|
|
24
|
+
return text.translate(_ILLEGAL_XML_TRANS)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def to_excel_serial(dt_val: datetime | date | time) -> float:
|
|
28
|
+
"""Converts Python date/datetime/time into Excel 1900 serial float."""
|
|
29
|
+
if isinstance(dt_val, datetime):
|
|
30
|
+
naive = dt_val.replace(tzinfo=None)
|
|
31
|
+
delta = naive - _EXCEL_EPOCH
|
|
32
|
+
serial = delta.days + (delta.seconds + delta.microseconds / 1_000_000) / 86400.0
|
|
33
|
+
elif isinstance(dt_val, date):
|
|
34
|
+
naive = datetime(dt_val.year, dt_val.month, dt_val.day)
|
|
35
|
+
serial = float((naive - _EXCEL_EPOCH).days)
|
|
36
|
+
else: # time
|
|
37
|
+
serial = (
|
|
38
|
+
dt_val.hour * 3600
|
|
39
|
+
+ dt_val.minute * 60
|
|
40
|
+
+ dt_val.second
|
|
41
|
+
+ dt_val.microsecond / 1_000_000
|
|
42
|
+
) / 86400.0
|
|
43
|
+
|
|
44
|
+
# Adjust for Excel's fictional Feb 29, 1900 (serial 60)
|
|
45
|
+
if not isinstance(dt_val, time) and serial <= 60:
|
|
46
|
+
serial -= 1.0
|
|
47
|
+
return serial
|
wixlf/utils/zip_io.py
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import posixpath
|
|
2
|
+
import shutil
|
|
3
|
+
import zipfile
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def resolve_zip_path(base_file: str, target: str) -> str:
|
|
7
|
+
"""Resolves relative or root-anchored OOXML targets to zip entry names."""
|
|
8
|
+
if target.startswith("/"):
|
|
9
|
+
return target.lstrip("/")
|
|
10
|
+
base_dir = posixpath.dirname(base_file)
|
|
11
|
+
return posixpath.normpath(posixpath.join(base_dir, target))
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def clone_zip_info(src_info: zipfile.ZipInfo) -> zipfile.ZipInfo:
|
|
15
|
+
"""Preserves filename, timestamp, and compression type while resetting sizes."""
|
|
16
|
+
info = zipfile.ZipInfo(
|
|
17
|
+
filename=src_info.filename, date_time=src_info.date_time
|
|
18
|
+
)
|
|
19
|
+
info.compress_type = src_info.compress_type
|
|
20
|
+
info.create_system = src_info.create_system
|
|
21
|
+
info.external_attr = src_info.external_attr
|
|
22
|
+
return info
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def stream_zip_entry(
|
|
26
|
+
zin: zipfile.ZipFile,
|
|
27
|
+
zout: zipfile.ZipFile,
|
|
28
|
+
src_info: zipfile.ZipInfo,
|
|
29
|
+
chunk_size: int,
|
|
30
|
+
) -> None:
|
|
31
|
+
"""Copies a zip entry chunk-by-chunk with constant memory usage."""
|
|
32
|
+
dst_info = clone_zip_info(src_info)
|
|
33
|
+
with zin.open(src_info, "r") as src_f, zout.open(dst_info, "w") as dst_f:
|
|
34
|
+
shutil.copyfileobj(src_f, dst_f, length=chunk_size)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def copy_disk_file_to_zip(
|
|
38
|
+
zout: zipfile.ZipFile,
|
|
39
|
+
src_info: zipfile.ZipInfo,
|
|
40
|
+
disk_path: str,
|
|
41
|
+
chunk_size: int,
|
|
42
|
+
) -> None:
|
|
43
|
+
"""Streams a patched temporary XML file from disk into the zip archive."""
|
|
44
|
+
dst_info = clone_zip_info(src_info)
|
|
45
|
+
with open(disk_path, "rb") as src_f, zout.open(dst_info, "w") as dst_f:
|
|
46
|
+
shutil.copyfileobj(src_f, dst_f, length=chunk_size)
|
|
@@ -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`.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
wixlf/__init__.py,sha256=MCsME5ZdX15GPDSLXFC5IYcsUPpPo3AsyKdkbEFSD8I,1627
|
|
2
|
+
wixlf/assembler.py,sha256=huS9Blf_K6Oe3HecGsGqL82LGuGFXtLOz_lMVaBE5Aw,7651
|
|
3
|
+
wixlf/constants.py,sha256=Zt0ZqPmarVXZ2Vd8gUEPEXzi9ymZV2n3Ym_qskLB1tM,1482
|
|
4
|
+
wixlf/models.py,sha256=pKyyNO4psQQi4LmPcZ5GELNm7rGyJlW3FJCFA6dRTtc,2449
|
|
5
|
+
wixlf/patcher.py,sha256=ODyuYv0dNScah7hSDsJaCmEqCRWXNS1XjVsH2g1mN-Q,10634
|
|
6
|
+
wixlf/reader.py,sha256=4YYZU74jpI8kvwvhObz38tUn6Swmjo-oWtq9Gi_sf70,1853
|
|
7
|
+
wixlf/utils/__init__.py,sha256=NOeO8rAonY9wtIqVbINEd74YuWjfOfag2iY866Ufd94,479
|
|
8
|
+
wixlf/utils/coords.py,sha256=Am-Csi66b2LCTsYeHHc3jQkwHMmtVdV5xqRyV1_FuI8,1597
|
|
9
|
+
wixlf/utils/xml_text.py,sha256=SmdXX58SYDnqPOBdOyJnarHnBs3HDKzHL_Qe20oqV1Q,1680
|
|
10
|
+
wixlf/utils/zip_io.py,sha256=zemZWkVo2o2_OgJVCE3PyWPDdeSecP44rFBjukdeSx8,1554
|
|
11
|
+
wixlf-0.1.1.dist-info/METADATA,sha256=fO_cKJ2ssZVj5w5WQR4qht61_1WuTwDtTxqEPuYKm2A,9107
|
|
12
|
+
wixlf-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
13
|
+
wixlf-0.1.1.dist-info/RECORD,,
|