@kevlns/xlmerge 1.3.1 → 2.0.1

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.
@@ -1,2 +1,2 @@
1
- # -*- coding: utf-8 -*-
2
- """Debussy XLSX/XLSM 冲突解析器(detect/prepare/launch/apply)。"""
1
+ # -*- coding: utf-8 -*-
2
+ """xlmerge XLSX/XLSM 冲突解析器(detect/prepare/launch/apply)。"""
@@ -1,4 +1,4 @@
1
- from xlsx_resolver.resolve_xlsx_conflict import main
2
-
3
- if __name__ == "__main__":
4
- raise SystemExit(main())
1
+ from xlsx_resolver.resolve_xlsx_conflict import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())
@@ -0,0 +1,565 @@
1
+ """Safe, Excel-backed formula materialisation for the conflict resolver.
2
+
3
+ This module deliberately has a small trust boundary. Excel is only ever given a
4
+ temporary copy, with links and macros disabled. The result produced by Excel is
5
+ read back as cached values and written into a copy of the original package with
6
+ openpyxl. We do not use ``data_only`` as a source workbook: a stale cache is not
7
+ an acceptable answer for a conflict resolver.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ import math
14
+ import os
15
+ import re
16
+ import shutil
17
+ import subprocess
18
+ import tempfile
19
+ import time
20
+ import zipfile
21
+ from datetime import date, datetime, time as datetime_time
22
+ from pathlib import Path
23
+ from typing import Any, Iterable
24
+ from xml.etree import ElementTree
25
+
26
+ from openpyxl import load_workbook
27
+ from openpyxl.cell.rich_text import CellRichText, InlineFont, TextBlock
28
+ from openpyxl.formula import Tokenizer
29
+ from openpyxl.utils.cell import range_boundaries
30
+
31
+
32
+ class FormulaValueError(RuntimeError):
33
+ """Raised when a workbook cannot be evaluated and verified safely."""
34
+
35
+
36
+ DEFAULT_TIMEOUT_SECONDS = 120
37
+ _ERROR_VALUES = {"#NULL!", "#DIV/0!", "#VALUE!", "#REF!", "#NAME?", "#NUM!", "#N/A", "#GETTING_DATA"}
38
+ _VOLATILE_FUNCTIONS = {
39
+ "NOW", "TODAY", "RAND", "RANDBETWEEN", "RANDARRAY", "RTD", "OFFSET", "INDIRECT",
40
+ "CELL", "INFO",
41
+ }
42
+ _DYNAMIC_FUNCTIONS = {
43
+ "FILTER", "SORT", "SORTBY", "UNIQUE", "SEQUENCE", "RANDARRAY", "TRANSPOSE",
44
+ "TOCOL", "TOROW", "TAKE", "DROP", "CHOOSECOLS", "CHOOSEROWS", "EXPAND",
45
+ "VSTACK", "HSTACK", "WRAPROWS", "WRAPCOLS", "XLOOKUP", "XMATCH", "LAMBDA",
46
+ }
47
+
48
+ # Function names are checked before opening Excel. This is intentionally a
49
+ # broad list of ordinary worksheet functions, but unknown calls are rejected so
50
+ # a disabled VBA UDF can never be silently accepted merely because it returned a
51
+ # plausible value in a cached workbook.
52
+ _BUILTIN_FUNCTIONS = {
53
+ name
54
+ for name in """
55
+ ABS ACOS ACOSH ACOT ACOTH AGGREGATE ARABIC ASIN ASINH ATAN ATAN2 ATANH BASE
56
+ CEILING CEILING.MATH CEILING.PRECISE COMBIN COMBINA COS COSH COT COTH CSC CSCH
57
+ DECIMAL DEGREES EVEN EXP FACT FACTDOUBLE FLOOR FLOOR.MATH FLOOR.PRECISE GCD
58
+ INT ISO.CEILING LCM LN LOG LOG10 MDETERM MINVERSE MMULT MOD MROUND MULTINOMIAL
59
+ MUNIT ODD PI POWER PRODUCT QUOTIENT RADIANS ROMAN ROUND ROUNDDOWN ROUNDUP SEC
60
+ SECH SIGN SIN SINH SQRT SUM SUMIF SUMIFS SUMPRODUCT SUMSQ TAN TANH TRUNC
61
+ ACCRINT ACCRINTM AMORDEGRC AMORLINC COUPDAYBS COUPDAYS COUPDAYSNC COUPNCD
62
+ COUPNUM COUPPCD CUMIPMT CUMPRINC DB DDB DISC DOLLARDE DOLLARFR DURATION EFFECT
63
+ FV FVSCHEDULE INTRATE IPMT IRR ISPMT MDURATION MIRR NOMINAL NPER NPV PDURATION
64
+ PMT PPMT PRICE PRICEDISC PRICEMAT PV RATE RECEIVED RRI SLN SYD TBILLEQ TBILLPRICE
65
+ TBILLYIELD VDB XIRR XNPV YIELD YIELDDISC YIELDMAT
66
+ AND FALSE IF IFERROR IFNA NOT OR TRUE XOR SWITCH IFS CHOOSE
67
+ ADDRESS AREAS COLUMN COLUMNS FORMULATEXT HLOOKUP HYPERLINK INDEX INDIRECT
68
+ LOOKUP MATCH ROW ROWS TRANSPOSE VLOOKUP OFFSET
69
+ CELL ERROR.TYPE INFO ISBLANK ISERR ISERROR ISEVEN ISFORMULA ISLOGICAL ISNA
70
+ ISNONTEXT ISNUMBER ISODD ISREF ISTEXT N TYPE NA
71
+ CONCAT CONCATENATE EXACT FIND FINDB LEFT LEFTB LEN LENB LOWER MID MIDB NUMBERVALUE
72
+ PHONETIC PROPER REPLACE REPLACEB REPT RIGHT RIGHTB SEARCH SEARCHB SUBSTITUTE T
73
+ TEXT TEXTAFTER TEXTBEFORE TEXTJOIN TEXTSPLIT TRIM UNICHAR UNICODE UPPER VALUE
74
+ ASC CHAR CLEAN CODE DBCS FIXED JIS LOWER UPPER
75
+ DATE DATEVALUE DAY DAYS DAYS360 EDATE EOMONTH HOUR ISOWEEKNUM MINUTE MONTH
76
+ NETWORKDAYS NETWORKDAYS.INTL SECOND TIME TIMEVALUE WEEKDAY WEEKNUM WORKDAY
77
+ WORKDAY.INTL YEAR YEARFRAC
78
+ COUNT COUNTA COUNTBLANK COUNTIF COUNTIFS MAX MAXIFS MIN MINIFS AVERAGE
79
+ AVERAGEIF AVERAGEIFS MEDIAN MODE.MULT MODE.SNGL LARGE SMALL RANK.EQ RANK.AVG
80
+ PERCENTILE.EXC PERCENTILE.INC PERCENTRANK.EXC PERCENTRANK.INC QUARTILE.EXC
81
+ QUARTILE.INC STANDARDIZE STDEV.P STDEV.S STDEVA STDEVPA VAR.P VAR.S VARA VARPA
82
+ CORREL COVARIANCE.P COVARIANCE.S GEOMEAN HARMEAN KURT SKEW SKEW.P SLOPE
83
+ INTERCEPT FORECAST FORECAST.LINEAR FREQUENCY GROWTH LINEST LOGEST PEARSON RSQ
84
+ TREND
85
+ DEC2BIN DEC2HEX DEC2OCT HEX2BIN HEX2DEC HEX2OCT OCT2BIN OCT2DEC OCT2HEX
86
+ BITAND BITLSHIFT BITOR BITRSHIFT BITXOR CONVERT DELTA ERF ERF.PRECISE ERFC
87
+ ERFC.PRECISE GESTEP IMSUM IMABS IMAGINARY IMARGUMENT IMCONJUGATE IMCOS IMCOSH
88
+ IMCOT IMCSC IMCSCH IMDIV IMEXP IMLN IMLOG10 IMLOG2 IMPOWER IMPRODUCT IMREAL
89
+ IMSEC IMSECH IMSIN IMSINH IMSQRT IMSUB IMTAN IMTANH COMPLEX
90
+ CUBEMEMBER CUBEVALUE GETPIVOTDATA
91
+ LET LAMBDA MAP REDUCE SCAN MAKEARRAY BYROW BYCOL
92
+ """.split()
93
+ }
94
+
95
+ _FUNCTION_CALL_RE = re.compile(r"(?<![A-Za-z0-9_.])([A-Za-z_][A-Za-z0-9_.]*)\s*\(")
96
+ _EXTERNAL_REF_RE = re.compile(r"\[[^\]]+\][^!]*!")
97
+ _DYNAMIC_SPILL_RE = re.compile(r"(?:[A-Z]{1,3}\$?\d+|\))#(?=$|[\s,;)])", re.IGNORECASE)
98
+
99
+
100
+ def _powershell_executable() -> str:
101
+ # Windows PowerShell is part of the supported host. Do not fall back to a
102
+ # different Python/COM package; pywin32 is intentionally not required.
103
+ return shutil.which("powershell.exe") or shutil.which("powershell") or "powershell.exe"
104
+
105
+
106
+ def _formula_text(value: Any) -> str | None:
107
+ if isinstance(value, str) and value.startswith("="):
108
+ return value
109
+ return None
110
+
111
+
112
+ def _without_string_literals(formula: str) -> str:
113
+ """Blank double-quoted Excel string literals before syntax/security scans."""
114
+ out: list[str] = []
115
+ quoted = False
116
+ index = 0
117
+ while index < len(formula):
118
+ char = formula[index]
119
+ if char == '"':
120
+ if quoted and index + 1 < len(formula) and formula[index + 1] == '"':
121
+ out.extend(" ")
122
+ index += 2
123
+ continue
124
+ quoted = not quoted
125
+ out.append(" ")
126
+ else:
127
+ out.append(" " if quoted else char)
128
+ index += 1
129
+ return "".join(out)
130
+
131
+
132
+ def _iter_formula_cells(workbook: Any) -> Iterable[tuple[Any, Any]]:
133
+ for worksheet in workbook.worksheets:
134
+ for row in worksheet.iter_rows():
135
+ for cell in row:
136
+ # A literal string beginning with '=' is data_type='s' and is
137
+ # deliberately not a formula. Only Excel's formula cell type
138
+ # (including openpyxl ArrayFormula objects) enters this path.
139
+ if cell.data_type == "f":
140
+ yield worksheet, cell
141
+
142
+
143
+ def _scan_package(path: Path) -> None:
144
+ """Reject package features that can cause I/O or code execution in Excel."""
145
+ try:
146
+ with zipfile.ZipFile(path) as archive:
147
+ archive_names = {name.replace("\\", "/").lower(): name for name in archive.namelist()}
148
+ names = set(archive_names)
149
+ dangerous_parts = (
150
+ "xl/externallinks/", "xl/connections.xml", "xl/querytables/",
151
+ "xl/ddelinks/", "xl/macrosheets/", "xl/dialogsheets/",
152
+ )
153
+ for part in dangerous_parts:
154
+ if any(name.startswith(part) or name == part.rstrip("/") for name in names):
155
+ raise FormulaValueError(f"Workbook contains unsupported external or executable part: {part}")
156
+
157
+ for name in names:
158
+ if not name.endswith(".xml") and not name.endswith(".rels"):
159
+ continue
160
+ raw = archive.read(archive_names[name])
161
+ lowered = raw.lower()
162
+ if b"<ddelink" in lowered or b"<olelink" in lowered:
163
+ raise FormulaValueError(f"Workbook contains DDE/OLE link data: {name}")
164
+ if name.endswith(".rels") and b'targetmode="external"' in lowered:
165
+ # External hyperlinks are harmless, but an external target
166
+ # in workbook/externalLink relationships is not. Reject
167
+ # only relationship files whose type names indicate a link
168
+ # or connection, avoiding false positives for user URLs.
169
+ if b"externallink" in lowered or b"externalconnection" in lowered:
170
+ raise FormulaValueError(f"Workbook contains an external relationship: {name}")
171
+ # Shared and array formulas are represented by attributes that are
172
+ # not faithfully round-trippable through openpyxl. Refuse the
173
+ # whole workbook rather than replacing only the anchor and leaving
174
+ # a silently wrong spill/shared range.
175
+ for name in names:
176
+ if not name.startswith("xl/worksheets/") or not name.endswith(".xml"):
177
+ continue
178
+ root = ElementTree.fromstring(archive.read(archive_names[name]))
179
+ for formula_node in root.iter():
180
+ if formula_node.tag.rsplit("}", 1)[-1] != "f":
181
+ continue
182
+ attrs = {key.rsplit("}", 1)[-1]: value for key, value in formula_node.attrib.items()}
183
+ kind = attrs.get("t", "").lower()
184
+ if kind in {"shared", "array", "datatable"} or "ref" in attrs:
185
+ raise FormulaValueError(f"Unsupported shared/array formula in {name}")
186
+ if formula_node.text is None and kind:
187
+ raise FormulaValueError(f"Unsupported formula without body in {name}")
188
+ except ElementTree.ParseError as exc:
189
+ raise FormulaValueError(f"Cannot inspect workbook XML safely: {path}") from exc
190
+ except (OSError, zipfile.BadZipFile) as exc:
191
+ raise FormulaValueError(f"Cannot inspect workbook package: {path}") from exc
192
+
193
+
194
+ def _scan_formulas(workbook: Any) -> list[tuple[str, str, str]]:
195
+ formulas: list[tuple[str, str, str]] = []
196
+ for worksheet, cell in _iter_formula_cells(workbook):
197
+ formula = cell.value.text if hasattr(cell.value, "text") else cell.value
198
+ if not isinstance(formula, str):
199
+ raise FormulaValueError(f"Unsupported formula object at {worksheet.title}!{cell.coordinate}")
200
+ if not formula.startswith("="):
201
+ formula = "=" + formula
202
+ scan_formula = _without_string_literals(formula)
203
+ upper = scan_formula.upper()
204
+ if _EXTERNAL_REF_RE.search(scan_formula) or re.search(r"\bDDE\s*\(", scan_formula, re.IGNORECASE):
205
+ raise FormulaValueError(f"External workbook/DDE reference at {worksheet.title}!{cell.coordinate}")
206
+ if any(token in upper for token in ("_XLFN.", "_XLWS.")):
207
+ raise FormulaValueError(f"Unsupported modern/dynamic formula at {worksheet.title}!{cell.coordinate}")
208
+ if _DYNAMIC_SPILL_RE.search(scan_formula) or "@" in scan_formula:
209
+ raise FormulaValueError(f"Dynamic/implicit-array formula at {worksheet.title}!{cell.coordinate}")
210
+ if any(re.search(rf"(?<![A-Z0-9_.]){re.escape(name)}\s*\(", upper) for name in _VOLATILE_FUNCTIONS):
211
+ raise FormulaValueError(f"Volatile formula is not reproducible at {worksheet.title}!{cell.coordinate}")
212
+ if "#REF!" in upper:
213
+ raise FormulaValueError(f"Broken formula reference at {worksheet.title}!{cell.coordinate}")
214
+ for match in _FUNCTION_CALL_RE.finditer(scan_formula):
215
+ name = match.group(1).upper()
216
+ if name in _DYNAMIC_FUNCTIONS:
217
+ raise FormulaValueError(f"Dynamic-array formula at {worksheet.title}!{cell.coordinate}")
218
+ if name.startswith("_XLFN.") or name.startswith("_XLWS.") or name not in _BUILTIN_FUNCTIONS:
219
+ raise FormulaValueError(f"Unknown/UDF formula function {name} at {worksheet.title}!{cell.coordinate}")
220
+ formulas.append((worksheet.title, cell.coordinate, formula))
221
+ _detect_formula_cycles(workbook)
222
+ return formulas
223
+
224
+
225
+ def _detect_formula_cycles(workbook: Any) -> None:
226
+ """Fail closed on cycles or references we cannot statically account for."""
227
+ nodes = {(ws.title, cell.coordinate): cell for ws, cell in _iter_formula_cells(workbook)}
228
+ graph = {}
229
+ sheet_names = {ws.title.casefold(): ws.title for ws in workbook.worksheets}
230
+ global_names = {name.casefold(): value for name, value in workbook.defined_names.items()}
231
+ local_names = {ws.title: {name.casefold(): value for name, value in ws.defined_names.items()}
232
+ for ws in workbook.worksheets}
233
+ by_sheet = {}
234
+ for key, cell in nodes.items():
235
+ by_sheet.setdefault(key[0], []).append((key, cell.row, cell.column))
236
+ ref_re = re.compile(r"^(?:\$?[A-Z]{1,3}\$?\d+(?::\$?[A-Z]{1,3}\$?\d+)?|\$?[A-Z]{1,3}:\$?[A-Z]{1,3}|\$?\d+:\$?\d+)$", re.I)
237
+
238
+ def dependencies(formula, context_sheet, name_stack=()):
239
+ try:
240
+ tokens = Tokenizer(formula if formula.startswith('=') else '=' + formula).items
241
+ except Exception as exc:
242
+ raise FormulaValueError(f"Unable to parse formula dependencies in {context_sheet}") from exc
243
+ result = set()
244
+ for token in tokens:
245
+ if token.type != "OPERAND" or token.subtype != "RANGE":
246
+ continue
247
+ raw = token.value.strip()
248
+ if "!" in raw:
249
+ sheet_text, raw_ref = raw.rsplit("!", 1)
250
+ if ":" in sheet_text:
251
+ raise FormulaValueError(f"Unsupported 3-D formula reference: {raw}")
252
+ if sheet_text.startswith("'") and sheet_text.endswith("'"):
253
+ sheet_text = sheet_text[1:-1].replace("''", "'")
254
+ target_sheet = sheet_names.get(sheet_text.casefold())
255
+ if target_sheet is None:
256
+ raise FormulaValueError(f"Unknown formula reference sheet: {raw}")
257
+ else:
258
+ raw_ref, target_sheet = raw, context_sheet
259
+ if ref_re.fullmatch(raw_ref):
260
+ # Relative references in defined names are anchored to Excel's
261
+ # active-cell context, not necessarily the formula cell. Do
262
+ # not guess that context when checking dependencies.
263
+ if name_stack and not re.fullmatch(
264
+ r'(?:\$[A-Z]{1,3}\$\d+(?::\$[A-Z]{1,3}\$\d+)?|\$[A-Z]{1,3}:\$[A-Z]{1,3}|\$\d+:\$\d+)',
265
+ raw_ref, re.I,
266
+ ):
267
+ raise FormulaValueError(f"Relative defined-name reference is unsupported: {raw}")
268
+ min_col, min_row, max_col, max_row = range_boundaries(raw_ref.upper())
269
+ min_col, min_row = min_col or 1, min_row or 1
270
+ max_col, max_row = max_col or 16384, max_row or 1048576
271
+ if not (1 <= min_col <= max_col <= 16384 and 1 <= min_row <= max_row <= 1048576):
272
+ raise FormulaValueError(f"Invalid formula range: {raw}")
273
+ result.update(key for key, row, col in by_sheet.get(target_sheet, [])
274
+ if min_col <= col <= max_col and min_row <= row <= max_row)
275
+ else:
276
+ name_key = raw_ref.casefold()
277
+ defined = local_names.get(target_sheet, {}).get(name_key) or global_names.get(name_key)
278
+ if defined is None:
279
+ raise FormulaValueError(f"Unsupported or unknown formula reference: {raw}")
280
+ identity = (target_sheet, name_key)
281
+ if identity in name_stack or len(name_stack) >= 100:
282
+ raise FormulaValueError(f"Circular or excessively nested defined name: {raw}")
283
+ result.update(dependencies(str(defined.attr_text or ''), target_sheet, (*name_stack, identity)))
284
+ return result
285
+
286
+ for node, cell in nodes.items():
287
+ formula = cell.value.text if hasattr(cell.value, "text") else str(cell.value)
288
+ graph[node] = dependencies(formula, node[0])
289
+ # Iterative topological elimination supports long formula chains.
290
+ reverse = {node: set() for node in graph}
291
+ counts = {node: len(edges) for node, edges in graph.items()}
292
+ for node, edges in graph.items():
293
+ for edge in edges:
294
+ reverse[edge].add(node)
295
+ ready = [node for node, count in counts.items() if count == 0]
296
+ visited = 0
297
+ while ready:
298
+ node = ready.pop()
299
+ visited += 1
300
+ for dependent in reverse[node]:
301
+ counts[dependent] -= 1
302
+ if counts[dependent] == 0:
303
+ ready.append(dependent)
304
+ if visited != len(graph):
305
+ node = next(node for node, count in counts.items() if count)
306
+ raise FormulaValueError(f"Circular formula dependency detected at {node[0]}!{node[1]}")
307
+
308
+
309
+ def _scan_defined_names(workbook: Any) -> None:
310
+ """Reject names which smuggle an external link or executable reference."""
311
+ all_names = [*workbook.defined_names.values(),
312
+ *(name for ws in workbook.worksheets for name in ws.defined_names.values())]
313
+ for defined_name in all_names:
314
+ text = str(getattr(defined_name, "attr_text", "") or "")
315
+ scan_text = _without_string_literals(text)
316
+ scan_upper = scan_text.upper()
317
+ if _EXTERNAL_REF_RE.search(scan_text) or re.search(r"\bDDE\s*\(", scan_text, re.IGNORECASE) or "#REF!" in scan_upper:
318
+ name = getattr(defined_name, "name", "<unnamed>")
319
+ raise FormulaValueError(f"Defined name contains an unsafe reference: {name}")
320
+ name = getattr(defined_name, "name", "<unnamed>")
321
+ if any(re.search(rf"(?<![A-Z0-9_.]){re.escape(function)}\s*\(", scan_upper)
322
+ for function in _VOLATILE_FUNCTIONS):
323
+ raise FormulaValueError(f"Defined name contains a volatile formula: {name}")
324
+ if _DYNAMIC_SPILL_RE.search(scan_text) or "@" in scan_text:
325
+ raise FormulaValueError(f"Defined name contains a dynamic-array formula: {name}")
326
+ for match in _FUNCTION_CALL_RE.finditer(scan_text):
327
+ function = match.group(1).upper()
328
+ if function in _DYNAMIC_FUNCTIONS or function.startswith(("_XLFN.", "_XLWS.")) \
329
+ or function not in _BUILTIN_FUNCTIONS:
330
+ raise FormulaValueError(f"Defined name contains unknown/UDF function {function}: {name}")
331
+
332
+
333
+ def _read_state(path: Path) -> dict[str, Any]:
334
+ try:
335
+ text = path.read_text(encoding="utf-8-sig")
336
+ value = json.loads(text)
337
+ return value if isinstance(value, dict) else {}
338
+ except (OSError, ValueError, json.JSONDecodeError):
339
+ return {}
340
+
341
+
342
+ def _cleanup_excel_process(state_path: Path) -> None:
343
+ """Stop only the Excel PID and start time recorded by our PS harness."""
344
+ state = _read_state(state_path)
345
+ pid = state.get("pid")
346
+ start_filetime = state.get("startFileTimeUtc")
347
+ if not isinstance(pid, int) or not isinstance(start_filetime, int):
348
+ return
349
+ helper = Path(__file__).with_name("recalculate_workbook.ps1")
350
+ try:
351
+ # Pass ownership data as JSON, never as PowerShell source/arguments.
352
+ # The helper validates both PID and process creation time before stop.
353
+ subprocess.run(
354
+ [_powershell_executable(), "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
355
+ "-File", str(helper), "-CleanupParametersPath", str(state_path)],
356
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=10, check=False,
357
+ )
358
+ except (OSError, subprocess.TimeoutExpired):
359
+ pass
360
+
361
+
362
+ def _run_excel_recalculate(source: Path, result: Path, timeout_seconds: int) -> None:
363
+ script = Path(__file__).with_name("recalculate_workbook.ps1")
364
+ if not script.is_file():
365
+ raise FormulaValueError(f"Excel recalculation helper is missing: {script}")
366
+ with tempfile.TemporaryDirectory(prefix="xlmerge-excel-state-") as state_dir:
367
+ state_path = Path(state_dir) / "state.json"
368
+ params_path = Path(state_dir) / "params.json"
369
+ params_path.write_text(json.dumps({
370
+ "source": str(source), "result": str(result), "state": str(state_path),
371
+ "timeoutSeconds": int(timeout_seconds),
372
+ }), encoding="utf-8")
373
+ command = [_powershell_executable(), "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
374
+ "-File", str(script), "-ParametersPath", str(params_path)]
375
+ try:
376
+ completed = subprocess.run(command, capture_output=True, text=True,
377
+ encoding="utf-8", errors="replace",
378
+ timeout=max(1, int(timeout_seconds) + 20), check=False)
379
+ except subprocess.TimeoutExpired as exc:
380
+ _cleanup_excel_process(state_path)
381
+ raise FormulaValueError("Excel recalculation exceeded the hard timeout") from exc
382
+ finally:
383
+ # The helper normally closes Excel itself. This also handles a
384
+ # PowerShell error path without ever scanning/killing user Excel.
385
+ if state_path.exists() and _read_state(state_path).get("status") not in {"completed", "failed"}:
386
+ _cleanup_excel_process(state_path)
387
+ if completed.returncode != 0:
388
+ state = _read_state(state_path)
389
+ detail = state.get("error") or completed.stderr.strip() or completed.stdout.strip()
390
+ raise FormulaValueError(f"Excel could not safely calculate workbook: {detail or 'unknown error'}")
391
+ if not result.is_file() or result.stat().st_size == 0:
392
+ raise FormulaValueError("Excel reported success but did not export a result workbook")
393
+
394
+
395
+ def _set_literal(cell: Any, value: Any) -> None:
396
+ """Assign a value without allowing a string beginning '=' to become a formula."""
397
+ if isinstance(value, str):
398
+ # openpyxl classifies strings such as '#N/A' as error cells and strings
399
+ # beginning '=' as formulas. Cached formula text is data, regardless
400
+ # of its spelling, so force the serialized string type for all text.
401
+ cell.data_type = "s"
402
+ if value == "":
403
+ # openpyxl normally omits an empty string cell entirely on write,
404
+ # which reloads as None. A zero-length rich-text run is a valid
405
+ # inline string and round-trips as a typed empty string.
406
+ cell._value = CellRichText(TextBlock(InlineFont(), ""))
407
+ else:
408
+ cell._value = value
409
+ else:
410
+ cell.value = value
411
+
412
+
413
+ def _validate_result(value: Any, worksheet: str, coordinate: str, data_type: str | None = None) -> None:
414
+ # Use the serialized cell type, not the displayed text: a formula may
415
+ # intentionally return the literal string "#N/A", while an Excel error is
416
+ # represented by cell type ``e``.
417
+ if data_type == "e":
418
+ raise FormulaValueError(f"Excel returned an error value at {worksheet}!{coordinate}: {value}")
419
+ if isinstance(value, float) and not math.isfinite(value):
420
+ raise FormulaValueError(f"Excel returned non-finite numeric value at {worksheet}!{coordinate}")
421
+ if value is not None and not isinstance(value, (str, bool, int, float, date, datetime, datetime_time)):
422
+ raise FormulaValueError(f"Unsupported Excel result type at {worksheet}!{coordinate}: {type(value).__name__}")
423
+
424
+
425
+ def _formula_cache_presence(path: Path) -> dict[tuple[str, str], bool]:
426
+ """Return whether each formula cell has a serialized ``<v>`` cache.
427
+
428
+ Excel writes an empty-string result as ``<v></v>`` (which openpyxl exposes
429
+ as ``None`` on some Excel versions), whereas an uncalculated formula has no
430
+ ``<v>`` element. Keeping this distinction is essential for fail-closed
431
+ calculation verification.
432
+ """
433
+ result: dict[tuple[str, str], bool] = {}
434
+ try:
435
+ with zipfile.ZipFile(path) as archive:
436
+ wb_root = ElementTree.fromstring(archive.read("xl/workbook.xml"))
437
+ rel_root = ElementTree.fromstring(archive.read("xl/_rels/workbook.xml.rels"))
438
+ rel_targets = {}
439
+ for rel in rel_root:
440
+ rid = rel.attrib.get("Id") or rel.attrib.get("{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id")
441
+ target = rel.attrib.get("Target")
442
+ if rid and target:
443
+ rel_targets[rid] = "xl/" + target.lstrip("/") if not target.startswith("/") else target.lstrip("/")
444
+ for sheet in wb_root.iter():
445
+ if sheet.tag.rsplit("}", 1)[-1] != "sheet":
446
+ continue
447
+ sheet_name = sheet.attrib.get("name")
448
+ rid = sheet.attrib.get("{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id")
449
+ target = rel_targets.get(rid)
450
+ if not sheet_name or not target or target not in archive.namelist():
451
+ continue
452
+ root = ElementTree.fromstring(archive.read(target))
453
+ for cell in root.iter():
454
+ if cell.tag.rsplit("}", 1)[-1] != "c" or not cell.attrib.get("r"):
455
+ continue
456
+ if any(child.tag.rsplit("}", 1)[-1] == "f" for child in cell):
457
+ result[(sheet_name, cell.attrib["r"])] = any(
458
+ child.tag.rsplit("}", 1)[-1] == "v" for child in cell
459
+ )
460
+ except (OSError, KeyError, zipfile.BadZipFile, ElementTree.ParseError):
461
+ return {}
462
+ return result
463
+
464
+
465
+ def _materialize_from_result(source: Path, calculated: Path, output: Path,
466
+ formula_keys: set[tuple[str, str]]) -> Path:
467
+ keep_vba = source.suffix.lower() == ".xlsm"
468
+ try:
469
+ original = load_workbook(source, data_only=False, keep_links=True, keep_vba=keep_vba)
470
+ values = load_workbook(calculated, data_only=True, keep_links=False, keep_vba=keep_vba)
471
+ except Exception as exc:
472
+ raise FormulaValueError(f"Cannot read Excel calculation result: {exc}") from exc
473
+ try:
474
+ cache_presence = _formula_cache_presence(calculated)
475
+ for sheet_name, coordinate in formula_keys:
476
+ if sheet_name not in values.sheetnames or sheet_name not in original.sheetnames:
477
+ raise FormulaValueError(f"Calculation result lost sheet {sheet_name!r}")
478
+ source_cell = original[sheet_name][coordinate]
479
+ result_cell = values[sheet_name][coordinate]
480
+ value = result_cell.value
481
+ _validate_result(value, sheet_name, coordinate, result_cell.data_type)
482
+ # A missing <v> cache is different from a legitimate cached empty
483
+ # string. Excel's data_only reader returns None in both unusual
484
+ # cases; normal formulas returning "" have a string cache and are
485
+ # accepted. Missing cache is rejected by the post-save formula
486
+ # count/result verification below if Excel did not calculate it.
487
+ if value is None:
488
+ if result_cell.data_type not in ('s', 'str') or not cache_presence.get((sheet_name, coordinate), False):
489
+ raise FormulaValueError(f"Excel did not provide a cached result at {sheet_name}!{coordinate}")
490
+ # Excel's empty-string cache can be represented by an empty
491
+ # <v> with no Python value. It is still a string result.
492
+ value = ""
493
+ _set_literal(source_cell, value)
494
+
495
+ output.parent.mkdir(parents=True, exist_ok=True)
496
+ temp_output = output.with_name(f".{output.stem}.tmp-{os.getpid()}-{time.time_ns()}{output.suffix}")
497
+ try:
498
+ original.save(temp_output)
499
+ check = load_workbook(temp_output, data_only=False, keep_links=False, keep_vba=keep_vba)
500
+ try:
501
+ leftovers = [(ws.title, c.coordinate) for ws, c in _iter_formula_cells(check)]
502
+ finally:
503
+ check.close()
504
+ if leftovers:
505
+ raise FormulaValueError(f"Formula values remained after materialization: {leftovers[:3]}")
506
+ os.replace(temp_output, output)
507
+ finally:
508
+ if temp_output.exists():
509
+ temp_output.unlink(missing_ok=True)
510
+ finally:
511
+ original.close()
512
+ values.close()
513
+ return output
514
+
515
+
516
+ def materialize_values(source_path: Path | str, output_path: Path | str) -> Path:
517
+ """Calculate every formula in ``source_path`` and emit a literal snapshot.
518
+
519
+ The source is never opened by Excel and is never modified. A workbook with
520
+ no formulas is returned unchanged, as an explicit fast path.
521
+ """
522
+ source = Path(source_path).resolve()
523
+ output = Path(output_path).resolve()
524
+ if not source.is_file():
525
+ raise FormulaValueError(f"Workbook does not exist: {source}")
526
+ if source == output:
527
+ raise FormulaValueError("Output path must differ from source path")
528
+ if source.suffix.lower() not in {".xlsx", ".xlsm"}:
529
+ raise FormulaValueError(f"Unsupported workbook extension: {source.suffix}")
530
+ if output.suffix.lower() != source.suffix.lower():
531
+ raise FormulaValueError("Output extension must match source extension")
532
+
533
+ _scan_package(source)
534
+ keep_vba = source.suffix.lower() == ".xlsm"
535
+ try:
536
+ workbook = load_workbook(source, data_only=False, keep_links=True, keep_vba=keep_vba)
537
+ except Exception as exc:
538
+ raise FormulaValueError(f"Cannot open workbook for formula inspection: {exc}") from exc
539
+ try:
540
+ formulas = _scan_formulas(workbook)
541
+ _scan_defined_names(workbook)
542
+ finally:
543
+ workbook.close()
544
+ if not formulas:
545
+ return source
546
+
547
+ timeout_setting = os.environ.get("XLMERGE_EXCEL_TIMEOUT_SECONDS", str(DEFAULT_TIMEOUT_SECONDS))
548
+ try:
549
+ timeout_seconds = max(1, int(timeout_setting))
550
+ except ValueError as exc:
551
+ raise FormulaValueError("XLMERGE_EXCEL_TIMEOUT_SECONDS must be an integer") from exc
552
+
553
+ temp_dir = Path(tempfile.mkdtemp(prefix="xlmerge-formula-values-"))
554
+ temporary_source = temp_dir / source.name
555
+ temporary_result = temp_dir / ("calculated" + source.suffix.lower())
556
+ try:
557
+ shutil.copy2(source, temporary_source)
558
+ _run_excel_recalculate(temporary_source, temporary_result, timeout_seconds)
559
+ return _materialize_from_result(source, temporary_result, output,
560
+ {(sheet, coordinate) for sheet, coordinate, _ in formulas})
561
+ finally:
562
+ shutil.rmtree(temp_dir, ignore_errors=True)
563
+
564
+
565
+ __all__ = ["FormulaValueError", "materialize_values"]