wolfdocx 0.1.0__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.
Files changed (54) hide show
  1. wolfdocx/__init__.py +25 -0
  2. wolfdocx/_cache_root.py +24 -0
  3. wolfdocx/_comment_threads.py +278 -0
  4. wolfdocx/_inspection_cache.py +374 -0
  5. wolfdocx/_version.py +3 -0
  6. wolfdocx/admission.py +163 -0
  7. wolfdocx/assembly.py +463 -0
  8. wolfdocx/authoring.py +2773 -0
  9. wolfdocx/canonical.py +267 -0
  10. wolfdocx/content.py +963 -0
  11. wolfdocx/document.py +215 -0
  12. wolfdocx/errors.py +169 -0
  13. wolfdocx/find_replace.py +1210 -0
  14. wolfdocx/formatting.py +3160 -0
  15. wolfdocx/inspect.py +3999 -0
  16. wolfdocx/model.py +1038 -0
  17. wolfdocx/numbering_authoring.py +1422 -0
  18. wolfdocx/output.py +13 -0
  19. wolfdocx/package.py +2313 -0
  20. wolfdocx/package_profile.py +128 -0
  21. wolfdocx/page_setup.py +2483 -0
  22. wolfdocx/paragraph_authoring.py +1842 -0
  23. wolfdocx/properties.py +2728 -0
  24. wolfdocx/protection.py +1909 -0
  25. wolfdocx/regions.py +1993 -0
  26. wolfdocx/render_warnings.py +106 -0
  27. wolfdocx/reporting.py +943 -0
  28. wolfdocx/review.py +2862 -0
  29. wolfdocx/run_text.py +117 -0
  30. wolfdocx/section_break.py +1810 -0
  31. wolfdocx/session_ops/__init__.py +45 -0
  32. wolfdocx/session_ops/_bridge.py +151 -0
  33. wolfdocx/session_ops/lists.py +104 -0
  34. wolfdocx/session_ops/paragraphs.py +39 -0
  35. wolfdocx/session_ops/rich_objects.py +2598 -0
  36. wolfdocx/session_ops/run_edits.py +70 -0
  37. wolfdocx/session_ops/runs.py +313 -0
  38. wolfdocx/session_ops/sections.py +109 -0
  39. wolfdocx/session_ops/styling.py +99 -0
  40. wolfdocx/session_ops/tables.py +247 -0
  41. wolfdocx/styles_authoring.py +2822 -0
  42. wolfdocx/table_cell_properties.py +1458 -0
  43. wolfdocx/table_column.py +1501 -0
  44. wolfdocx/table_delete.py +942 -0
  45. wolfdocx/table_insert.py +1114 -0
  46. wolfdocx/table_merge.py +1863 -0
  47. wolfdocx/table_properties.py +2429 -0
  48. wolfdocx/table_row_properties.py +1095 -0
  49. wolfdocx/table_structure.py +1044 -0
  50. wolfdocx/text_effects.py +1438 -0
  51. wolfdocx-0.1.0.dist-info/METADATA +127 -0
  52. wolfdocx-0.1.0.dist-info/RECORD +54 -0
  53. wolfdocx-0.1.0.dist-info/WHEEL +4 -0
  54. wolfdocx-0.1.0.dist-info/licenses/LICENSE +21 -0
wolfdocx/authoring.py ADDED
@@ -0,0 +1,2773 @@
1
+ """Conservative, source-bound authoring for Word cells and split-run text."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import hashlib
7
+ import json
8
+ import os
9
+ import tempfile
10
+ import zipfile
11
+ from collections.abc import Mapping
12
+ from dataclasses import dataclass, replace
13
+ from pathlib import Path
14
+ from typing import Any
15
+ from xml.etree import ElementTree as ET
16
+ from xml.parsers import expat
17
+
18
+ from .content import (
19
+ ContentScope,
20
+ _evaluate_target_changes,
21
+ _matching_elements,
22
+ )
23
+ from .inspect import (
24
+ SUPPORTED_WORD_NAMESPACES,
25
+ Q,
26
+ _inspect_docx,
27
+ _require_verify_mode,
28
+ _verify_changed_parts,
29
+ inspect_docx,
30
+ )
31
+ from .package import PackageError, PackageGraph
32
+
33
+ _SHA256_LENGTH = 64
34
+ _MAX_TEXT_CHARACTERS = 32_768
35
+ _REFUSED = "refused"
36
+ _PUBLISHED = "published"
37
+ # A session edit held in memory until ``Document.save`` publishes it.
38
+ _APPLIED = "applied"
39
+ _XML_SPACE_ATTRIBUTE = "{http://www.w3.org/XML/1998/namespace}space"
40
+ _MATH_NAMESPACE = "http://schemas.openxmlformats.org/officeDocument/2006/math"
41
+ _STRICT_MATH_NAMESPACE = "http://purl.oclc.org/ooxml/officeDocument/math"
42
+ _MATHML_NAMESPACE = "http://www.w3.org/1998/Math/MathML"
43
+ _MATH_REQUEST_FIELDS = frozenset(
44
+ {
45
+ "source",
46
+ "destination",
47
+ "source_sha256",
48
+ "structure_fingerprint_sha256",
49
+ "target",
50
+ "omml_xml",
51
+ "mathml_xml",
52
+ }
53
+ )
54
+
55
+
56
+ _CONTEXT_FEATURES = frozenset(
57
+ {
58
+ "commentRangeStart",
59
+ "commentRangeEnd",
60
+ "commentReference",
61
+ "customXml",
62
+ "del",
63
+ "fldChar",
64
+ "fldSimple",
65
+ "hyperlink",
66
+ "ins",
67
+ "moveFrom",
68
+ "moveTo",
69
+ "sdt",
70
+ "sdtContent",
71
+ }
72
+ )
73
+
74
+
75
+ class CellRequestLimitError(ValueError):
76
+ """A content-safe refusal for one bounded caller-supplied text field."""
77
+
78
+ def __init__(self, field: str, requested_characters: int) -> None:
79
+ self.field = field
80
+ self.requested_characters = requested_characters
81
+ super().__init__(
82
+ f"{field} has {requested_characters} characters; maximum is "
83
+ f"{_MAX_TEXT_CHARACTERS}. Shorten it or choose a smaller span."
84
+ )
85
+
86
+ @property
87
+ def code(self) -> str:
88
+ return f"cell_{self.field}_character_limit"
89
+
90
+ def to_dict(self) -> dict[str, Any]:
91
+ return {
92
+ "schema_version": 1,
93
+ "operation": "cell",
94
+ "passed": False,
95
+ "status": _REFUSED,
96
+ "code": self.code,
97
+ "limit": {
98
+ "field": self.field,
99
+ "maximum_characters": _MAX_TEXT_CHARACTERS,
100
+ "requested_characters": self.requested_characters,
101
+ "recovery": "Shorten the value or choose a smaller span.",
102
+ },
103
+ }
104
+
105
+
106
+ class SpanRequestLimitError(CellRequestLimitError):
107
+ """A content-safe refusal for one bounded span request text field."""
108
+
109
+ @property
110
+ def code(self) -> str:
111
+ return f"span_{self.field}_character_limit"
112
+
113
+ def to_dict(self) -> dict[str, Any]:
114
+ return {
115
+ "schema_version": 1,
116
+ "operation": "span",
117
+ "passed": False,
118
+ "status": _REFUSED,
119
+ "code": self.code,
120
+ "limit": {
121
+ "field": self.field,
122
+ "maximum_characters": _MAX_TEXT_CHARACTERS,
123
+ "requested_characters": self.requested_characters,
124
+ "recovery": "Shorten the value or choose a smaller span.",
125
+ },
126
+ }
127
+
128
+
129
+ @dataclass(frozen=True)
130
+ class CellTextRequest:
131
+ """One source-bound replacement for a simple table-cell text node."""
132
+
133
+ source: Path
134
+ destination: Path
135
+ source_sha256: str
136
+ expected_old_text: str
137
+ structure_fingerprint_sha256: str
138
+ table: int
139
+ row: int
140
+ cell: int
141
+ text: str
142
+
143
+ @property
144
+ def target_scope(self) -> ContentScope:
145
+ return ContentScope(kind="table_cell", table=self.table, row=self.row, cell=self.cell)
146
+
147
+
148
+ @dataclass(frozen=True)
149
+ class CellTextAuthoringReport:
150
+ """Content-safe public result for a cell text authoring request."""
151
+
152
+ status: str
153
+ code: str | None
154
+ source_sha256: str
155
+ target: dict[str, int]
156
+ structure_fingerprint_sha256: str | None = None
157
+ destination_sha256: str | None = None
158
+ target_change_report: dict[str, Any] | None = None
159
+ non_target_parts_preserved: bool | None = None
160
+
161
+ @property
162
+ def passed(self) -> bool:
163
+ return self.status in (_PUBLISHED, _APPLIED)
164
+
165
+ def to_dict(self) -> dict[str, Any]:
166
+ return {
167
+ "schema_version": 1,
168
+ "operation": "cell",
169
+ "passed": self.passed,
170
+ "status": self.status,
171
+ "code": self.code,
172
+ "source_sha256": self.source_sha256,
173
+ "target": self.target,
174
+ "structure_fingerprint_sha256": self.structure_fingerprint_sha256,
175
+ "destination_sha256": self.destination_sha256,
176
+ "target_change_report": self.target_change_report,
177
+ "non_target_parts_preserved": self.non_target_parts_preserved,
178
+ }
179
+
180
+
181
+ def _sha256_file(path: Path) -> str:
182
+ digest = hashlib.sha256()
183
+ with path.open("rb") as stream:
184
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
185
+ digest.update(chunk)
186
+ return digest.hexdigest()
187
+
188
+
189
+ def _refusal(request: CellTextRequest, code: str) -> CellTextAuthoringReport:
190
+ return CellTextAuthoringReport(
191
+ status=_REFUSED,
192
+ code=code,
193
+ source_sha256=request.source_sha256,
194
+ target=request.target_scope.to_dict(),
195
+ )
196
+
197
+
198
+ def _require_sha256(value: Any, label: str) -> str:
199
+ if not isinstance(value, str) or len(value) != _SHA256_LENGTH:
200
+ raise ValueError(f"{label}_invalid")
201
+ try:
202
+ int(value, 16)
203
+ except ValueError as error:
204
+ raise ValueError(f"{label}_invalid") from error
205
+ return value.lower()
206
+
207
+
208
+ def _require_positive_coordinate(value: Any, label: str) -> int:
209
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
210
+ raise ValueError(f"{label}_invalid")
211
+ return value
212
+
213
+
214
+ def parse_cell_text_request(value: Any) -> CellTextRequest:
215
+ """Parse the intentionally small public request schema without coercion."""
216
+
217
+ if not isinstance(value, Mapping):
218
+ raise TypeError("cell_request_invalid")
219
+ expected_keys = {
220
+ "source",
221
+ "destination",
222
+ "source_sha256",
223
+ "expected_old_text",
224
+ "structure_fingerprint_sha256",
225
+ "target",
226
+ "text",
227
+ }
228
+ if set(value) != expected_keys:
229
+ raise ValueError("cell_request_fields_invalid")
230
+ source = value["source"]
231
+ destination = value["destination"]
232
+ expected_old_text = value["expected_old_text"]
233
+ text = value["text"]
234
+ target = value["target"]
235
+ if not isinstance(source, str) or not source:
236
+ raise ValueError("cell_source_invalid")
237
+ if not isinstance(destination, str) or not destination:
238
+ raise ValueError("cell_destination_invalid")
239
+ if not isinstance(expected_old_text, str):
240
+ raise TypeError("cell_expected_old_text_invalid")
241
+ if len(expected_old_text) > _MAX_TEXT_CHARACTERS:
242
+ raise CellRequestLimitError("expected_old_text", len(expected_old_text))
243
+ if not isinstance(text, str):
244
+ raise TypeError("cell_text_invalid")
245
+ if len(text) > _MAX_TEXT_CHARACTERS:
246
+ raise CellRequestLimitError("text", len(text))
247
+ if not isinstance(target, Mapping) or set(target) != {"table", "row", "cell"}:
248
+ raise ValueError("cell_target_invalid")
249
+ return CellTextRequest(
250
+ source=Path(source),
251
+ destination=Path(destination),
252
+ source_sha256=_require_sha256(value["source_sha256"], "cell_source_sha256"),
253
+ expected_old_text=expected_old_text,
254
+ structure_fingerprint_sha256=_require_sha256(
255
+ value["structure_fingerprint_sha256"], "cell_structure_fingerprint_sha256"
256
+ ),
257
+ table=_require_positive_coordinate(target["table"], "cell_target_table"),
258
+ row=_require_positive_coordinate(target["row"], "cell_target_row"),
259
+ cell=_require_positive_coordinate(target["cell"], "cell_target_cell"),
260
+ text=text,
261
+ )
262
+
263
+
264
+ def load_cell_text_request(path: str | Path) -> CellTextRequest:
265
+ """Load one UTF-8 JSON request file with no path data in its result surface."""
266
+
267
+ with Path(path).open(encoding="utf-8") as stream:
268
+ return parse_cell_text_request(json.load(stream))
269
+
270
+
271
+ def _word_namespace(root: ET.Element) -> str | None:
272
+ if not isinstance(root.tag, str) or not root.tag.startswith("{"):
273
+ return None
274
+ namespace = root.tag[1:].split("}", 1)[0]
275
+ return namespace if namespace in SUPPORTED_WORD_NAMESPACES else None
276
+
277
+
278
+ def _selected_cell(
279
+ root: ET.Element, request: CellTextRequest, word_namespace: str
280
+ ) -> ET.Element | None:
281
+ def word(local):
282
+ return Q(word_namespace, local)
283
+ tables = list(root.iter(word("tbl")))
284
+ if request.table > len(tables):
285
+ return None
286
+ rows = tables[request.table - 1].findall(word("tr"))
287
+ if request.row > len(rows):
288
+ return None
289
+ cells = rows[request.row - 1].findall(word("tc"))
290
+ if request.cell > len(cells):
291
+ return None
292
+ return cells[request.cell - 1]
293
+
294
+
295
+ def _cell_structure_fingerprint(cell: ET.Element) -> str:
296
+ """Hash the selected cell's XML structure while deliberately masking text."""
297
+
298
+ def project(element: ET.Element) -> list[Any]:
299
+ return [
300
+ element.tag,
301
+ sorted(element.attrib.items()),
302
+ None if element.tag.rsplit("}", 1)[-1] == "t" else element.text,
303
+ element.tail,
304
+ [project(child) for child in element],
305
+ ]
306
+
307
+ canonical = json.dumps(project(cell), ensure_ascii=False, separators=(",", ":"))
308
+ return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
309
+
310
+
311
+ def _has_unsupported_feature(cell: ET.Element, word_namespace: str) -> bool:
312
+ unsupported = {
313
+ "commentRangeStart",
314
+ "commentRangeEnd",
315
+ "commentReference",
316
+ "del",
317
+ "delText",
318
+ "fldChar",
319
+ "fldSimple",
320
+ "hyperlink",
321
+ "ins",
322
+ "instrText",
323
+ "moveFrom",
324
+ "moveFromRangeEnd",
325
+ "moveFromRangeStart",
326
+ "moveTo",
327
+ "moveToRangeEnd",
328
+ "moveToRangeStart",
329
+ }
330
+ tags = {Q(word_namespace, local) for local in unsupported}
331
+ return any(child.tag in tags for child in cell.iter())
332
+
333
+
334
+ class _ContextState:
335
+ """Ancestor and sibling-range admission state, consumed in XML start order."""
336
+
337
+ def __init__(self, word_namespace: str) -> None:
338
+ def word(local):
339
+ return Q(word_namespace, local)
340
+ self.context_tags = {word(feature) for feature in _CONTEXT_FEATURES}
341
+ self.range_starts = {
342
+ word("commentRangeStart"): "comment",
343
+ word("moveFromRangeStart"): "moveFrom",
344
+ word("moveToRangeStart"): "moveTo",
345
+ }
346
+ self.range_ends = {
347
+ word("commentRangeEnd"): "comment",
348
+ word("moveFromRangeEnd"): "moveFrom",
349
+ word("moveToRangeEnd"): "moveTo",
350
+ }
351
+ self.state_tags = set(self.range_starts) | set(self.range_ends) | {word("fldChar")}
352
+ self.active_ranges: set[tuple[str, str]] = set()
353
+ self.active_fields = 0
354
+ self.id_attribute = word("id")
355
+ self.field_char = word("fldChar")
356
+ self.field_char_type = word("fldCharType")
357
+
358
+ def enter(self, element: ET.Element, ancestor_context: bool) -> tuple[bool, bool]:
359
+ unsupported = bool(self.active_ranges) or self.active_fields > 0 or ancestor_context
360
+ child_context = ancestor_context or element.tag in self.context_tags
361
+ if element.tag not in self.state_tags:
362
+ return unsupported, child_context
363
+ range_kind = self.range_starts.get(element.tag)
364
+ if range_kind is not None:
365
+ self.active_ranges.add((range_kind, element.attrib.get(self.id_attribute, "")))
366
+ elif element.tag == self.field_char:
367
+ field_type = element.attrib.get(self.field_char_type)
368
+ if field_type == "begin":
369
+ self.active_fields += 1
370
+ elif field_type == "end" and self.active_fields:
371
+ self.active_fields -= 1
372
+ else:
373
+ range_kind = self.range_ends.get(element.tag)
374
+ if range_kind is not None:
375
+ self.active_ranges.discard((range_kind, element.attrib.get(self.id_attribute, "")))
376
+ return unsupported, child_context
377
+
378
+
379
+ class _ContextReached(Exception):
380
+ """Ends a context walk at the one element whose context was asked for."""
381
+
382
+
383
+ def _unsupported_context_by_element(
384
+ root: ET.Element, word_namespace: str, *, stop_at: ET.Element | None = None
385
+ ) -> dict[int, bool]:
386
+ """Index the existing ancestor/range refusal semantics in one document walk.
387
+
388
+ An element's context depends only on what precedes it in document order, so with
389
+ ``stop_at`` the walk ends once that element's context is recorded.
390
+ """
391
+
392
+ state = _ContextState(word_namespace)
393
+ unsupported: dict[int, bool] = {}
394
+
395
+ def visit(element: ET.Element, ancestor_context: bool) -> None:
396
+ context, child_context = state.enter(element, ancestor_context)
397
+ unsupported[id(element)] = context
398
+ if element is stop_at:
399
+ raise _ContextReached
400
+ for child in element:
401
+ visit(child, child_context)
402
+
403
+ try:
404
+ visit(root, False)
405
+ except _ContextReached:
406
+ pass
407
+ return unsupported
408
+
409
+
410
+ def _has_unsupported_ancestor(root: ET.Element, selected: ET.Element, word_namespace: str) -> bool:
411
+ """Refuse wrapper contexts and active sibling ranges around a target."""
412
+
413
+ return _unsupported_context_by_element(root, word_namespace, stop_at=selected).get(
414
+ id(selected), True
415
+ )
416
+
417
+
418
+ def _start_tag_end(document_xml: bytes, start: int) -> int | None:
419
+ quote: int | None = None
420
+ for index in range(start, len(document_xml)):
421
+ current = document_xml[index]
422
+ if quote is not None:
423
+ if current == quote:
424
+ quote = None
425
+ elif current in {ord('"'), ord("'")}:
426
+ quote = current
427
+ elif current == ord(">"):
428
+ return index + 1
429
+ return None
430
+
431
+
432
+ def _escape_xml_text(text: str) -> bytes:
433
+ return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").encode("utf-8")
434
+
435
+
436
+ class _TargetResolved(Exception):
437
+ """Stops the patch scan once the target text node's byte range is decided."""
438
+
439
+
440
+ def _patch_xml_text(
441
+ document_xml: bytes, *, word_namespace: str, occurrence: int, text: str
442
+ ) -> bytes | None:
443
+ """Replace exactly one parsed Word text-node content range without reserializing XML.
444
+
445
+ ``document_xml`` is already known to parse (the caller's tree came from exactly
446
+ these bytes), so the scan stops at the target's end tag, or at its start tag when
447
+ the target cannot be patched; the patched bytes are re-parsed by the caller.
448
+ """
449
+
450
+ parser = expat.ParserCreate(namespace_separator="}")
451
+ element_stack: list[str] = []
452
+ # Local names of the open elements, so each start tag checks the p/r/t suffix
453
+ # without re-splitting its ancestors' names.
454
+ local_stack: list[str] = []
455
+ found = 0
456
+ target_depth: int | None = None
457
+ content_start: int | None = None
458
+ content_end: int | None = None
459
+ patchable = True
460
+ target_active = False
461
+ target_name = f"{word_namespace}" + "}t"
462
+
463
+ def start_element(name: str, attributes: dict[str, str]) -> None:
464
+ nonlocal content_start, found, patchable, target_active, target_depth
465
+ del attributes
466
+ element_stack.append(name)
467
+ local_stack.append(name.rsplit("}", 1)[-1])
468
+ if (
469
+ local_stack[-1] == "t"
470
+ and len(local_stack) >= 3
471
+ and local_stack[-2] == "r"
472
+ and local_stack[-3] == "p"
473
+ ):
474
+ found += 1
475
+ if found == occurrence:
476
+ start = parser.CurrentByteIndex
477
+ content_start = _start_tag_end(document_xml, start)
478
+ target_depth = len(element_stack)
479
+ target_active = True
480
+ if (
481
+ name != target_name
482
+ or content_start is None
483
+ or document_xml[start : content_start - 1].rstrip().endswith(b"/")
484
+ ):
485
+ patchable = False
486
+ raise _TargetResolved
487
+
488
+ def end_element(name: str) -> None:
489
+ nonlocal content_end, target_active
490
+ if target_active and target_depth == len(element_stack) and name == target_name:
491
+ content_end = parser.CurrentByteIndex
492
+ target_active = False
493
+ raise _TargetResolved
494
+ element_stack.pop()
495
+ local_stack.pop()
496
+
497
+ parser.StartElementHandler = start_element
498
+ parser.EndElementHandler = end_element
499
+ try:
500
+ parser.Parse(document_xml, True)
501
+ except _TargetResolved:
502
+ pass
503
+ except expat.ExpatError:
504
+ return None
505
+ if not patchable or content_start is None or content_end is None or content_start > content_end:
506
+ return None
507
+ return document_xml[:content_start] + _escape_xml_text(text) + document_xml[content_end:]
508
+
509
+
510
+ def _simple_text_node(cell: ET.Element, word_namespace: str) -> tuple[ET.Element, str] | None:
511
+ """Return the only supported ``w:t`` and its current cell text.
512
+
513
+ Policy: the selected cell must be unmerged and contain exactly one direct
514
+ paragraph, exactly one direct run, and exactly one direct text node. Its
515
+ ``w:pPr`` and ``w:rPr`` children are retained verbatim. Whitespace policy is
516
+ checked against the text node's effective ``xml:space`` before patching.
517
+ """
518
+
519
+ def word(local):
520
+ return Q(word_namespace, local)
521
+ if _has_unsupported_feature(cell, word_namespace):
522
+ return None
523
+ tc_pr = cell.find(word("tcPr"))
524
+ if tc_pr is not None and (
525
+ tc_pr.find(word("vMerge")) is not None
526
+ or tc_pr.find(word("hMerge")) is not None
527
+ or tc_pr.find(word("gridSpan")) is not None
528
+ ):
529
+ return None
530
+ if any(child.tag not in {word("tcPr"), word("p")} for child in cell):
531
+ return None
532
+ paragraphs = cell.findall(word("p"))
533
+ if len(paragraphs) != 1:
534
+ return None
535
+ paragraph = paragraphs[0]
536
+ if any(child.tag not in {word("pPr"), word("r")} for child in paragraph):
537
+ return None
538
+ runs = paragraph.findall(word("r"))
539
+ if len(runs) != 1:
540
+ return None
541
+ run = runs[0]
542
+ if any(child.tag not in {word("rPr"), word("t")} for child in run):
543
+ return None
544
+ text_nodes = run.findall(word("t"))
545
+ if len(text_nodes) != 1:
546
+ return None
547
+ text = text_nodes[0].text or ""
548
+ return text_nodes[0], text
549
+
550
+
551
+ def _xml_text_occurrence(root: ET.Element, target: ET.Element) -> int:
552
+ """1-based pre-order rank of ``target`` among elements on a ``p/r/t`` local path."""
553
+ count = 0
554
+
555
+ def visit(element: ET.Element, grandparent: str | None, parent: str | None) -> bool:
556
+ nonlocal count
557
+ name = element.tag.rsplit("}", 1)[-1]
558
+ if name == "t" and parent == "r" and grandparent == "p":
559
+ count += 1
560
+ if element is target:
561
+ return True
562
+ for child in element:
563
+ if visit(child, parent, name):
564
+ return True
565
+ return False
566
+
567
+ if visit(root, None, None):
568
+ return count
569
+ raise ValueError("cell_target_text_missing")
570
+
571
+
572
+ def _verification_xml_text_occurrence(root: ET.Element, target: ET.Element) -> int:
573
+ """Return the target occurrence under the generic verifier's path grammar."""
574
+
575
+ scope = ContentScope(
576
+ kind="xml_text",
577
+ part="word/document.xml",
578
+ element_path=("p", "r", "t"),
579
+ occurrence=1,
580
+ )
581
+ for occurrence, element in enumerate(_matching_elements(root, scope), start=1):
582
+ if element is target:
583
+ return occurrence
584
+ raise ValueError("cell_target_text_missing")
585
+
586
+
587
+ def _non_target_part_bytes_preserved(source: Path, candidate: Path) -> bool:
588
+ with zipfile.ZipFile(source) as baseline, zipfile.ZipFile(candidate) as rewritten:
589
+ baseline_names = set(baseline.namelist())
590
+ candidate_names = set(rewritten.namelist())
591
+ if baseline_names != candidate_names:
592
+ return False
593
+ return all(
594
+ baseline.read(name) == rewritten.read(name)
595
+ for name in baseline_names
596
+ if name != "word/document.xml"
597
+ )
598
+
599
+
600
+ def _write_staged_package(source: Path, staged: Path, document_xml: bytes) -> None:
601
+ with (
602
+ zipfile.ZipFile(source) as baseline,
603
+ zipfile.ZipFile(staged, "w", compression=zipfile.ZIP_DEFLATED) as rewritten,
604
+ ):
605
+ for info in baseline.infolist():
606
+ data = (
607
+ document_xml
608
+ if info.filename == "word/document.xml"
609
+ else baseline.read(info.filename)
610
+ )
611
+ rewritten.writestr(copy.copy(info), data)
612
+
613
+
614
+ def _cell_text_from_inspection(report: Any, scope: ContentScope) -> str | None:
615
+ table = scope.table
616
+ row = scope.row
617
+ cell = scope.cell
618
+ assert table is not None and row is not None and cell is not None
619
+ tables = report.fingerprint.tables
620
+ if table > len(tables):
621
+ return None
622
+ rows = tables[table - 1]["rows"]
623
+ if row > len(rows):
624
+ return None
625
+ cells = rows[row - 1]["cells"]
626
+ if cell > len(cells):
627
+ return None
628
+ return cells[cell - 1]["text"]
629
+
630
+
631
+ @dataclass(frozen=True)
632
+ class _CellPlan:
633
+ """One validated simple-cell replacement, patched into the document part bytes."""
634
+
635
+ document_xml: bytes
636
+ word_namespace: str
637
+ target_change_scope: ContentScope
638
+
639
+
640
+ def _plan_cell_text(
641
+ request: CellTextRequest, root: ET.Element, document_xml: bytes
642
+ ) -> _CellPlan | str:
643
+ """Validate one cell request against ``root`` and patch ``document_xml`` in place.
644
+
645
+ ``root`` is only read; it must be parsed from exactly ``document_xml``. Returns a
646
+ refusal code or the patched part bytes with the scope the edit may change.
647
+ """
648
+ word_namespace = _word_namespace(root)
649
+ if word_namespace is None:
650
+ return "source_word_namespace_unsupported"
651
+ selected_cell = _selected_cell(root, request, word_namespace)
652
+ if selected_cell is None:
653
+ return "cell_coordinate_missing"
654
+ if _cell_structure_fingerprint(selected_cell) != request.structure_fingerprint_sha256:
655
+ return "cell_structure_mismatch"
656
+ if _has_unsupported_ancestor(root, selected_cell, word_namespace):
657
+ return "cell_context_unsupported"
658
+ simple_text = _simple_text_node(selected_cell, word_namespace)
659
+ if simple_text is None:
660
+ return "cell_structure_unsupported"
661
+ text_node, old_text = simple_text
662
+ source_has_padding = old_text[:1].isspace() or old_text[-1:].isspace()
663
+ if source_has_padding and not _text_replacements_preserve_whitespace(
664
+ root, {id(text_node): old_text}
665
+ ):
666
+ return "cell_structure_unsupported"
667
+ if old_text != request.expected_old_text:
668
+ return "expected_old_text_mismatch"
669
+ if request.text == old_text:
670
+ return "replacement_unchanged"
671
+ if (
672
+ not source_has_padding
673
+ and (request.text[:1].isspace() or request.text[-1:].isspace())
674
+ and not _text_replacements_preserve_whitespace(root, {id(text_node): request.text})
675
+ ):
676
+ return "replacement_whitespace_unsupported"
677
+
678
+ patch_occurrence = _xml_text_occurrence(root, text_node)
679
+ verification_occurrence = _verification_xml_text_occurrence(root, text_node)
680
+ target_change_scope = ContentScope(
681
+ kind="xml_text",
682
+ part="word/document.xml",
683
+ element_path=("p", "r", "t"),
684
+ occurrence=verification_occurrence,
685
+ )
686
+ patched_document_xml = _patch_xml_text(
687
+ document_xml,
688
+ word_namespace=word_namespace,
689
+ occurrence=patch_occurrence,
690
+ text=request.text,
691
+ )
692
+ if patched_document_xml is None:
693
+ return "cell_text_patch_unsupported"
694
+ return _CellPlan(patched_document_xml, word_namespace, target_change_scope)
695
+
696
+
697
+ def _cell_text_landed(
698
+ candidate_root: ET.Element, request: CellTextRequest, word_namespace: str
699
+ ) -> bool:
700
+ """True when a re-parsed document holds the requested text in an unchanged cell."""
701
+ candidate_cell = _selected_cell(candidate_root, request, word_namespace)
702
+ candidate_text = (
703
+ _simple_text_node(candidate_cell, word_namespace) if candidate_cell is not None else None
704
+ )
705
+ return (
706
+ candidate_cell is not None
707
+ and candidate_text is not None
708
+ and candidate_text[1] == request.text
709
+ and _cell_structure_fingerprint(candidate_cell) == request.structure_fingerprint_sha256
710
+ )
711
+
712
+
713
+ def author_cell_text(request: CellTextRequest, *, verify: str = "full") -> CellTextAuthoringReport:
714
+ """Publish one verified simple-cell replacement only after all checks pass.
715
+
716
+ ``verify="full"`` (the default) re-inspects the whole staged package, including
717
+ its document fingerprint, before publishing. ``verify="changed-parts"`` keeps every
718
+ request check and the source-hash re-check, re-parses ``word/document.xml`` under
719
+ the package limits, proves every other part (relationships included) is
720
+ byte-identical to the validated source and re-checks the target cell, but skips
721
+ re-inspecting and fingerprinting the unchanged parts of the staged package.
722
+ """
723
+
724
+ _require_verify_mode(verify)
725
+ source = request.source.resolve()
726
+ destination = request.destination.resolve()
727
+ if source == destination:
728
+ return _refusal(request, "source_destination_same")
729
+ if not source.is_file():
730
+ return _refusal(request, "source_missing")
731
+ if not destination.parent.is_dir():
732
+ return _refusal(request, "destination_parent_missing")
733
+ if _sha256_file(source) != request.source_sha256:
734
+ return _refusal(request, "source_hash_mismatch")
735
+
736
+ baseline = _inspect_docx(source)
737
+ if not baseline.valid or baseline.file_sha256 != request.source_sha256:
738
+ return _refusal(request, "source_inspection_invalid")
739
+ try:
740
+ source_graph = PackageGraph.from_file(source)
741
+ if source_graph.file_sha256 != request.source_sha256:
742
+ return _refusal(request, "source_hash_changed")
743
+ document_xml = source_graph.read_part_bytes("word/document.xml")
744
+ except PackageError:
745
+ return _refusal(request, "source_document_missing")
746
+ # The baseline tree was parsed from these exact bytes (same package digest); it is
747
+ # shared, so this function only reads it.
748
+ root = baseline.parsed_xml.get("word/document.xml")
749
+ if root is None:
750
+ return _refusal(request, "source_document_invalid")
751
+ plan = _plan_cell_text(request, root, document_xml)
752
+ if isinstance(plan, str):
753
+ return _refusal(request, plan)
754
+ word_namespace = plan.word_namespace
755
+ patched_document_xml = plan.document_xml
756
+ target_change_scope = plan.target_change_scope
757
+ staged_path: Path | None = None
758
+ try:
759
+ with tempfile.NamedTemporaryFile(
760
+ dir=destination.parent,
761
+ prefix=f".{destination.name}.",
762
+ suffix=".tmp",
763
+ delete=False,
764
+ ) as staged:
765
+ staged_path = Path(staged.name)
766
+ _write_staged_package(source, staged_path, patched_document_xml)
767
+ if verify == "full":
768
+ candidate = _inspect_docx(staged_path, reuse=baseline)
769
+ target_content_ok = (
770
+ _cell_text_from_inspection(candidate.report, request.target_scope) == request.text
771
+ )
772
+ candidate_valid = candidate.valid
773
+ destination_sha256 = candidate.file_sha256
774
+ target_change_report = _evaluate_target_changes(
775
+ [target_change_scope],
776
+ baseline.part_sha256,
777
+ candidate.part_sha256,
778
+ load_baseline_root=baseline.mutable_root,
779
+ load_candidate_root=candidate.mutable_root,
780
+ )
781
+ non_target_parts_preserved = _non_target_part_bytes_preserved(source, staged_path)
782
+ else:
783
+ verified = _verify_changed_parts(
784
+ baseline, staged_path, {"word/document.xml": patched_document_xml}
785
+ )
786
+ if verified is None:
787
+ return _refusal(request, "staged_verification_failed")
788
+ destination_sha256, candidate_roots = verified
789
+ candidate_valid = True
790
+ target_content_ok = _cell_text_landed(
791
+ candidate_roots["word/document.xml"], request, word_namespace
792
+ )
793
+ target_change_report = _evaluate_target_changes(
794
+ [target_change_scope],
795
+ baseline.part_sha256,
796
+ {
797
+ **baseline.part_sha256,
798
+ "word/document.xml": hashlib.sha256(patched_document_xml).hexdigest(),
799
+ },
800
+ load_baseline_root=baseline.mutable_root,
801
+ load_candidate_root=candidate_roots.get,
802
+ )
803
+ non_target_parts_preserved = True
804
+ source_still_bound = _sha256_file(source) == request.source_sha256
805
+ if not (
806
+ candidate_valid
807
+ and target_change_report.passed
808
+ and target_content_ok
809
+ and non_target_parts_preserved
810
+ and source_still_bound
811
+ ):
812
+ return _refusal(
813
+ request,
814
+ "staged_verification_failed" if source_still_bound else "source_hash_changed",
815
+ )
816
+ os.replace(staged_path, destination)
817
+ staged_path = None
818
+ return CellTextAuthoringReport(
819
+ status=_PUBLISHED,
820
+ code=None,
821
+ source_sha256=request.source_sha256,
822
+ target=request.target_scope.to_dict(),
823
+ structure_fingerprint_sha256=request.structure_fingerprint_sha256,
824
+ destination_sha256=destination_sha256,
825
+ target_change_report=target_change_report.to_dict(),
826
+ non_target_parts_preserved=True,
827
+ )
828
+ finally:
829
+ if staged_path is not None:
830
+ staged_path.unlink(missing_ok=True)
831
+
832
+
833
+ def cell_structure_fingerprint(
834
+ source: str | Path, *, table: int, row: int, cell: int
835
+ ) -> str | None:
836
+ """Return the bounded selected-cell structural fingerprint for request construction."""
837
+
838
+ document = Path(source)
839
+ inspection = _inspect_docx(document)
840
+ if not inspection.valid:
841
+ return None
842
+ root = inspection.parsed_xml.get("word/document.xml")
843
+ if root is None:
844
+ return None
845
+ namespace = _word_namespace(root)
846
+ if namespace is None:
847
+ return None
848
+ request = CellTextRequest(
849
+ source=document,
850
+ destination=document.with_suffix(".unused.docx"),
851
+ source_sha256=inspection.file_sha256,
852
+ expected_old_text="",
853
+ structure_fingerprint_sha256="0" * _SHA256_LENGTH,
854
+ table=table,
855
+ row=row,
856
+ cell=cell,
857
+ text="",
858
+ )
859
+ selected = _selected_cell(root, request, namespace)
860
+ if selected is None:
861
+ return None
862
+ return _cell_structure_fingerprint(selected)
863
+
864
+
865
+ @dataclass(frozen=True)
866
+ class SpanTextRequest:
867
+ source: Path
868
+ destination: Path
869
+ source_sha256: str
870
+ expected_old_text: str
871
+ structure_fingerprint_sha256: str
872
+ paragraph: int
873
+ text: str
874
+
875
+
876
+ def parse_span_text_request(value: Any) -> SpanTextRequest:
877
+ if not isinstance(value, Mapping):
878
+ raise TypeError("span_request_invalid")
879
+ if set(value) != {
880
+ "source",
881
+ "destination",
882
+ "source_sha256",
883
+ "expected_old_text",
884
+ "structure_fingerprint_sha256",
885
+ "paragraph",
886
+ "text",
887
+ }:
888
+ raise ValueError("span_request_fields_invalid")
889
+ expected_old_text = value["expected_old_text"]
890
+ text = value["text"]
891
+ if not isinstance(expected_old_text, str) or not isinstance(text, str):
892
+ raise TypeError("span_text_invalid")
893
+ if not expected_old_text:
894
+ raise ValueError("span_expected_old_text_empty")
895
+ if len(expected_old_text) > _MAX_TEXT_CHARACTERS:
896
+ raise SpanRequestLimitError("expected_old_text", len(expected_old_text))
897
+ if len(text) > _MAX_TEXT_CHARACTERS:
898
+ raise SpanRequestLimitError("text", len(text))
899
+ source, destination = value["source"], value["destination"]
900
+ if (
901
+ not isinstance(source, str)
902
+ or not source
903
+ or not isinstance(destination, str)
904
+ or not destination
905
+ ):
906
+ raise ValueError("span_path_invalid")
907
+ return SpanTextRequest(
908
+ Path(source),
909
+ Path(destination),
910
+ _require_sha256(value["source_sha256"], "span_source_sha256"),
911
+ expected_old_text,
912
+ _require_sha256(value["structure_fingerprint_sha256"], "span_structure_fingerprint_sha256"),
913
+ _require_positive_coordinate(value["paragraph"], "span_paragraph"),
914
+ text,
915
+ )
916
+
917
+
918
+ def load_span_text_request(path: str | Path) -> SpanTextRequest:
919
+ with Path(path).open(encoding="utf-8") as stream:
920
+ return parse_span_text_request(json.load(stream))
921
+
922
+
923
+ def _paragraph_structure_fingerprint(paragraph: ET.Element) -> str:
924
+ return _cell_structure_fingerprint(paragraph)
925
+
926
+
927
+ def paragraph_structure_fingerprint(source: str | Path, *, paragraph: int) -> str | None:
928
+ inspection = inspect_docx(source)
929
+ if not inspection.valid:
930
+ return None
931
+ try:
932
+ root = ET.fromstring(PackageGraph.from_file(source).read_part_bytes("word/document.xml"))
933
+ except (ET.ParseError, PackageError):
934
+ return None
935
+ namespace = _word_namespace(root)
936
+ if namespace is None:
937
+ return None
938
+ paragraphs = list(root.iter(Q(namespace, "p")))
939
+ if paragraph <= 0 or paragraph > len(paragraphs):
940
+ return None
941
+ return _paragraph_structure_fingerprint(paragraphs[paragraph - 1])
942
+
943
+
944
+ @dataclass(frozen=True)
945
+ class SpanTextAuthoringReport:
946
+ """Content-safe public result for a paragraph-fragment authoring request."""
947
+
948
+ status: str
949
+ code: str | None
950
+ source_sha256: str
951
+ target: dict[str, int]
952
+ structure_fingerprint_sha256: str | None = None
953
+ destination_sha256: str | None = None
954
+ target_change_report: dict[str, Any] | None = None
955
+ non_target_document_bytes_preserved: bool | None = None
956
+ non_target_parts_preserved: bool | None = None
957
+
958
+ @property
959
+ def passed(self) -> bool:
960
+ return self.status == _PUBLISHED
961
+
962
+ def to_dict(self) -> dict[str, Any]:
963
+ return {
964
+ "schema_version": 1,
965
+ "operation": "span",
966
+ "passed": self.passed,
967
+ "status": self.status,
968
+ "code": self.code,
969
+ "source_sha256": self.source_sha256,
970
+ "target": self.target,
971
+ "structure_fingerprint_sha256": self.structure_fingerprint_sha256,
972
+ "destination_sha256": self.destination_sha256,
973
+ "target_change_report": self.target_change_report,
974
+ "non_target_document_bytes_preserved": (self.non_target_document_bytes_preserved),
975
+ "non_target_parts_preserved": self.non_target_parts_preserved,
976
+ }
977
+
978
+
979
+ @dataclass(frozen=True)
980
+ class _SpanTextNode:
981
+ node: ET.Element
982
+ text: str
983
+ start: int
984
+ end: int
985
+
986
+
987
+ def _span_refusal(request: SpanTextRequest, code: str) -> SpanTextAuthoringReport:
988
+ return SpanTextAuthoringReport(
989
+ status=_REFUSED,
990
+ code=code,
991
+ source_sha256=request.source_sha256,
992
+ target={"paragraph": request.paragraph},
993
+ )
994
+
995
+
996
+ def _selected_paragraph(
997
+ root: ET.Element, request: SpanTextRequest, word_namespace: str
998
+ ) -> ET.Element | None:
999
+ paragraphs = list(root.iter(Q(word_namespace, "p")))
1000
+ if request.paragraph > len(paragraphs):
1001
+ return None
1002
+ return paragraphs[request.paragraph - 1]
1003
+
1004
+
1005
+ def _span_text_nodes(paragraph: ET.Element, word_namespace: str) -> list[_SpanTextNode] | None:
1006
+ """Return direct simple-run text nodes whose lexical runs can be patched.
1007
+
1008
+ This deliberately accepts only direct ``w:r`` children with one ``w:t``.
1009
+ Any revision, field, comment, annotation, control, or unsupported inline
1010
+ content in the paragraph is refused rather than crossed or normalized.
1011
+ """
1012
+
1013
+ def word(local):
1014
+ return Q(word_namespace, local)
1015
+ if _has_unsupported_feature(paragraph, word_namespace):
1016
+ return None
1017
+ if any(child.tag not in {word("pPr"), word("r")} for child in paragraph):
1018
+ return None
1019
+ nodes: list[_SpanTextNode] = []
1020
+ offset = 0
1021
+ for run in paragraph.findall(word("r")):
1022
+ if any(child.tag not in {word("rPr"), word("t")} for child in run):
1023
+ return None
1024
+ text_nodes = run.findall(word("t"))
1025
+ if len(text_nodes) != 1 or len(text_nodes[0]) != 0:
1026
+ return None
1027
+ text = text_nodes[0].text or ""
1028
+ nodes.append(
1029
+ _SpanTextNode(
1030
+ node=text_nodes[0],
1031
+ text=text,
1032
+ start=offset,
1033
+ end=offset + len(text),
1034
+ )
1035
+ )
1036
+ offset += len(text)
1037
+ return nodes or None
1038
+
1039
+
1040
+ def _span_match(nodes: list[_SpanTextNode], *, start: int, end: int) -> list[_SpanTextNode] | None:
1041
+ selected = [node for node in nodes if node.start < end and start < node.end]
1042
+ return selected if len(selected) >= 2 else None
1043
+
1044
+
1045
+ def _span_replacements(
1046
+ selected: list[_SpanTextNode], *, start: int, end: int, text: str
1047
+ ) -> dict[int, str]:
1048
+ replacements: dict[int, str] = {}
1049
+ for index, node in enumerate(selected):
1050
+ local_start = max(start, node.start) - node.start
1051
+ local_end = min(end, node.end) - node.start
1052
+ prefix = node.text[:local_start] if index == 0 else ""
1053
+ suffix = node.text[local_end:] if index == len(selected) - 1 else ""
1054
+ replacements[id(node.node)] = prefix + text + suffix if index == 0 else suffix
1055
+ return replacements
1056
+
1057
+
1058
+ def _effective_xml_space_by_element(root: ET.Element) -> dict[int, str | None]:
1059
+ """Index effective ``xml:space`` inheritance without changing XML markup."""
1060
+
1061
+ effective_spaces: dict[int, str | None] = {}
1062
+
1063
+ def visit(element: ET.Element, inherited_space: str | None) -> None:
1064
+ effective_space = element.attrib.get(_XML_SPACE_ATTRIBUTE, inherited_space)
1065
+ effective_spaces[id(element)] = effective_space
1066
+ for child in element:
1067
+ visit(child, effective_space)
1068
+
1069
+ visit(root, None)
1070
+ return effective_spaces
1071
+
1072
+
1073
+ def _text_replacements_preserve_whitespace(
1074
+ root: ET.Element,
1075
+ replacements: Mapping[int, str],
1076
+ *,
1077
+ effective_spaces: Mapping[int, str | None] | None = None,
1078
+ ) -> bool:
1079
+ """Require existing effective ``xml:space="preserve"`` for edge whitespace."""
1080
+
1081
+ whitespace_targets = {
1082
+ node_id
1083
+ for node_id, text in replacements.items()
1084
+ if text[:1].isspace() or text[-1:].isspace()
1085
+ }
1086
+ if not whitespace_targets:
1087
+ return True
1088
+ spaces = _effective_xml_space_by_element(root) if effective_spaces is None else effective_spaces
1089
+ return all(spaces.get(node_id) == "preserve" for node_id in whitespace_targets)
1090
+
1091
+
1092
+ class _PatchTargetsClosed(Exception):
1093
+ """Ends a patch scan once every target text node has closed."""
1094
+
1095
+
1096
+ def _patch_xml_texts(
1097
+ document_xml: bytes,
1098
+ *,
1099
+ word_namespace: str,
1100
+ replacements: Mapping[int, str],
1101
+ ) -> bytes | None:
1102
+ """Patch selected direct ``w:p/w:r/w:t`` contents without reserializing XML.
1103
+
1104
+ Callers pass bytes they have already parsed whole, so the scan stops when the last
1105
+ target closes: the unchanged remainder cannot alter which ranges are patched.
1106
+ """
1107
+
1108
+ parser = expat.ParserCreate(namespace_separator="}")
1109
+ local_stack: list[str] = []
1110
+ occurrence = 0
1111
+ active: tuple[int, int, int] | None = None
1112
+ ranges: list[tuple[int, int, str]] = []
1113
+ target_name = f"{word_namespace}" + "}t"
1114
+ run_text_path = ["p", "r", "t"]
1115
+ patchable = True
1116
+ found: set[int] = set()
1117
+
1118
+ def start_element(name: str, attributes: dict[str, str]) -> None:
1119
+ nonlocal active, occurrence, patchable
1120
+ del attributes
1121
+ local_stack.append(name.rsplit("}", 1)[-1])
1122
+ if local_stack[-3:] != run_text_path:
1123
+ return
1124
+ occurrence += 1
1125
+ if occurrence not in replacements:
1126
+ return
1127
+ start = parser.CurrentByteIndex
1128
+ content_start = _start_tag_end(document_xml, start)
1129
+ if (
1130
+ name != target_name
1131
+ or content_start is None
1132
+ or document_xml[start : content_start - 1].rstrip().endswith(b"/")
1133
+ ):
1134
+ patchable = False
1135
+ return
1136
+ active = (occurrence, content_start, len(local_stack))
1137
+
1138
+ def end_element(name: str) -> None:
1139
+ nonlocal active, patchable
1140
+ if active is not None and len(local_stack) == active[2]:
1141
+ target_occurrence, content_start, _ = active
1142
+ if name != target_name:
1143
+ patchable = False
1144
+ else:
1145
+ ranges.append(
1146
+ (
1147
+ content_start,
1148
+ parser.CurrentByteIndex,
1149
+ replacements[target_occurrence],
1150
+ )
1151
+ )
1152
+ found.add(target_occurrence)
1153
+ active = None
1154
+ local_stack.pop()
1155
+ if len(found) == len(replacements):
1156
+ raise _PatchTargetsClosed
1157
+
1158
+ parser.StartElementHandler = start_element
1159
+ parser.EndElementHandler = end_element
1160
+ try:
1161
+ parser.Parse(document_xml, True)
1162
+ except _PatchTargetsClosed:
1163
+ pass
1164
+ except expat.ExpatError:
1165
+ return None
1166
+ if (
1167
+ not patchable
1168
+ or active is not None
1169
+ or found != set(replacements)
1170
+ or len(ranges) != len(replacements)
1171
+ ):
1172
+ return None
1173
+ patched = document_xml
1174
+ for content_start, content_end, text in reversed(ranges):
1175
+ if content_start > content_end:
1176
+ return None
1177
+ patched = patched[:content_start] + _escape_xml_text(text) + patched[content_end:]
1178
+ return patched
1179
+
1180
+
1181
+ def _span_text_occurrences(root: ET.Element, selected: list[_SpanTextNode]) -> dict[int, int]:
1182
+ targets = {id(node.node) for node in selected}
1183
+ occurrences: dict[int, int] = {}
1184
+ occurrence = 0
1185
+
1186
+ def visit(element: ET.Element, parent: str | None, grandparent: str | None) -> None:
1187
+ nonlocal occurrence
1188
+ local = element.tag.rsplit("}", 1)[-1]
1189
+ if grandparent == "p" and parent == "r" and local == "t":
1190
+ occurrence += 1
1191
+ if id(element) in targets:
1192
+ occurrences[id(element)] = occurrence
1193
+ for child in element:
1194
+ visit(child, local, parent)
1195
+
1196
+ visit(root, None, None)
1197
+ if set(occurrences) != targets:
1198
+ raise ValueError("span_target_text_missing")
1199
+ return occurrences
1200
+
1201
+
1202
+ def _span_text_from_root(
1203
+ root: ET.Element, request: SpanTextRequest, word_namespace: str
1204
+ ) -> str | None:
1205
+ paragraph = _selected_paragraph(root, request, word_namespace)
1206
+ if paragraph is None:
1207
+ return None
1208
+ nodes = _span_text_nodes(paragraph, word_namespace)
1209
+ return "".join(node.text for node in nodes) if nodes is not None else None
1210
+
1211
+
1212
+ def _span_target_change_report(
1213
+ request: SpanTextRequest,
1214
+ *,
1215
+ source_text: str,
1216
+ start: int,
1217
+ end: int,
1218
+ candidate_text: str | None,
1219
+ candidate_fingerprint: str | None,
1220
+ ) -> dict[str, Any]:
1221
+ expected_text = source_text[:start] + request.text + source_text[end:]
1222
+ target_found = candidate_text is not None
1223
+ target_changed = target_found and candidate_text != source_text
1224
+ structure_preserved = candidate_fingerprint == request.structure_fingerprint_sha256
1225
+ return {
1226
+ "scope": {"kind": "paragraph", "index": request.paragraph},
1227
+ "target_found": target_found,
1228
+ "target_changed": target_changed,
1229
+ "expected_text_sha256": hashlib.sha256(expected_text.encode("utf-8")).hexdigest(),
1230
+ "candidate_text_sha256": (
1231
+ hashlib.sha256(candidate_text.encode("utf-8")).hexdigest()
1232
+ if candidate_text is not None
1233
+ else None
1234
+ ),
1235
+ "paragraph_structure_preserved": structure_preserved,
1236
+ "passed": (
1237
+ target_found
1238
+ and target_changed
1239
+ and candidate_text == expected_text
1240
+ and structure_preserved
1241
+ ),
1242
+ }
1243
+
1244
+
1245
+ def author_span_text(request: SpanTextRequest) -> SpanTextAuthoringReport:
1246
+ """Publish one source-bound replacement spanning at least two simple runs.
1247
+
1248
+ The replacement is inserted into the first selected run, so that run's
1249
+ ``w:rPr`` supplies the replacement formatting. The selected final run
1250
+ retains only its suffix; all other runs and paragraph properties are left
1251
+ byte-for-byte intact.
1252
+ """
1253
+
1254
+ source = request.source.resolve()
1255
+ destination = request.destination.resolve()
1256
+ if source == destination:
1257
+ return _span_refusal(request, "source_destination_same")
1258
+ if not source.is_file():
1259
+ return _span_refusal(request, "source_missing")
1260
+ if not destination.parent.is_dir():
1261
+ return _span_refusal(request, "destination_parent_missing")
1262
+ if _sha256_file(source) != request.source_sha256:
1263
+ return _span_refusal(request, "source_hash_mismatch")
1264
+ if not request.text:
1265
+ return _span_refusal(request, "replacement_empty_unsupported")
1266
+ if request.text == request.expected_old_text:
1267
+ return _span_refusal(request, "replacement_unchanged")
1268
+ if request.text[:1].isspace() or request.text[-1:].isspace():
1269
+ return _span_refusal(request, "replacement_whitespace_unsupported")
1270
+
1271
+ baseline = inspect_docx(source)
1272
+ if not baseline.valid or baseline.file_sha256 != request.source_sha256:
1273
+ return _span_refusal(request, "source_inspection_invalid")
1274
+ try:
1275
+ source_graph = PackageGraph.from_file(source)
1276
+ if source_graph.file_sha256 != request.source_sha256:
1277
+ return _span_refusal(request, "source_hash_changed")
1278
+ document_xml = source_graph.read_part_bytes("word/document.xml")
1279
+ root = ET.fromstring(document_xml)
1280
+ except PackageError:
1281
+ return _span_refusal(request, "source_document_missing")
1282
+ except ET.ParseError:
1283
+ return _span_refusal(request, "source_document_invalid")
1284
+ word_namespace = _word_namespace(root)
1285
+ if word_namespace is None:
1286
+ return _span_refusal(request, "source_word_namespace_unsupported")
1287
+ paragraph = _selected_paragraph(root, request, word_namespace)
1288
+ if paragraph is None:
1289
+ return _span_refusal(request, "paragraph_coordinate_missing")
1290
+ if _paragraph_structure_fingerprint(paragraph) != request.structure_fingerprint_sha256:
1291
+ return _span_refusal(request, "paragraph_structure_mismatch")
1292
+ if _has_unsupported_ancestor(root, paragraph, word_namespace):
1293
+ return _span_refusal(request, "paragraph_context_unsupported")
1294
+ nodes = _span_text_nodes(paragraph, word_namespace)
1295
+ if nodes is None:
1296
+ return _span_refusal(request, "span_structure_unsupported")
1297
+ source_text = "".join(node.text for node in nodes)
1298
+ start = source_text.find(request.expected_old_text)
1299
+ if start < 0:
1300
+ return _span_refusal(request, "expected_old_text_mismatch")
1301
+ if source_text.find(request.expected_old_text, start + 1) >= 0:
1302
+ return _span_refusal(request, "span_occurrence_ambiguous")
1303
+ end = start + len(request.expected_old_text)
1304
+ selected = _span_match(nodes, start=start, end=end)
1305
+ if selected is None:
1306
+ return _span_refusal(request, "span_not_cross_run")
1307
+ replacements_by_node = _span_replacements(selected, start=start, end=end, text=request.text)
1308
+ if not _text_replacements_preserve_whitespace(root, replacements_by_node):
1309
+ return _span_refusal(request, "span_whitespace_unsupported")
1310
+ try:
1311
+ occurrences = _span_text_occurrences(root, selected)
1312
+ except ValueError:
1313
+ return _span_refusal(request, "span_target_text_missing")
1314
+ patched_document_xml = _patch_xml_texts(
1315
+ document_xml,
1316
+ word_namespace=word_namespace,
1317
+ replacements={occurrences[node_id]: text for node_id, text in replacements_by_node.items()},
1318
+ )
1319
+ if patched_document_xml is None:
1320
+ return _span_refusal(request, "span_text_patch_unsupported")
1321
+
1322
+ staged_path: Path | None = None
1323
+ try:
1324
+ with tempfile.NamedTemporaryFile(
1325
+ dir=destination.parent,
1326
+ prefix=f".{destination.name}.",
1327
+ suffix=".tmp",
1328
+ delete=False,
1329
+ ) as staged:
1330
+ staged_path = Path(staged.name)
1331
+ _write_staged_package(source, staged_path, patched_document_xml)
1332
+ candidate = inspect_docx(staged_path)
1333
+ candidate_document_xml: bytes | None = None
1334
+ candidate_text: str | None = None
1335
+ candidate_fingerprint: str | None = None
1336
+ if candidate.valid:
1337
+ try:
1338
+ candidate_document_xml = PackageGraph.from_file(staged_path).read_part_bytes(
1339
+ "word/document.xml"
1340
+ )
1341
+ candidate_root = ET.fromstring(candidate_document_xml)
1342
+ candidate_namespace = _word_namespace(candidate_root)
1343
+ if candidate_namespace is not None:
1344
+ candidate_text = _span_text_from_root(
1345
+ candidate_root, request, candidate_namespace
1346
+ )
1347
+ candidate_paragraph = _selected_paragraph(
1348
+ candidate_root, request, candidate_namespace
1349
+ )
1350
+ if candidate_paragraph is not None:
1351
+ candidate_fingerprint = _paragraph_structure_fingerprint(
1352
+ candidate_paragraph
1353
+ )
1354
+ except (ET.ParseError, PackageError):
1355
+ pass
1356
+ target_change_report = _span_target_change_report(
1357
+ request,
1358
+ source_text="".join(node.text for node in nodes),
1359
+ start=start,
1360
+ end=end,
1361
+ candidate_text=candidate_text,
1362
+ candidate_fingerprint=candidate_fingerprint,
1363
+ )
1364
+ non_target_document_bytes_preserved = candidate_document_xml == patched_document_xml
1365
+ non_target_parts_preserved = _non_target_part_bytes_preserved(source, staged_path)
1366
+ source_still_bound = _sha256_file(source) == request.source_sha256
1367
+ if not (
1368
+ candidate.valid
1369
+ and target_change_report["passed"]
1370
+ and non_target_document_bytes_preserved
1371
+ and non_target_parts_preserved
1372
+ and source_still_bound
1373
+ ):
1374
+ return _span_refusal(
1375
+ request,
1376
+ "staged_verification_failed" if source_still_bound else "source_hash_changed",
1377
+ )
1378
+ os.replace(staged_path, destination)
1379
+ staged_path = None
1380
+ return SpanTextAuthoringReport(
1381
+ status=_PUBLISHED,
1382
+ code=None,
1383
+ source_sha256=request.source_sha256,
1384
+ target={"paragraph": request.paragraph},
1385
+ structure_fingerprint_sha256=request.structure_fingerprint_sha256,
1386
+ destination_sha256=candidate.file_sha256,
1387
+ target_change_report=target_change_report,
1388
+ non_target_document_bytes_preserved=True,
1389
+ non_target_parts_preserved=True,
1390
+ )
1391
+ finally:
1392
+ if staged_path is not None:
1393
+ staged_path.unlink(missing_ok=True)
1394
+
1395
+
1396
+ @dataclass(frozen=True)
1397
+ class MathRequest:
1398
+ """Source-bound insert, edit or delete of math in a body paragraph.
1399
+
1400
+ Edit/delete select the unique direct math container in that paragraph, or
1401
+ the immediately following body-level display equation. Ambiguous targets
1402
+ are refused. Delete accepts an optional input but never inserts it.
1403
+ """
1404
+
1405
+ source: Path
1406
+ destination: Path
1407
+ source_sha256: str
1408
+ structure_fingerprint_sha256: str
1409
+ paragraph: int
1410
+ omml_xml: str | None
1411
+ mathml_xml: str | None
1412
+ latex: str | None = None
1413
+ operation: str = "insert"
1414
+
1415
+
1416
+ @dataclass(frozen=True)
1417
+ class MathAuthoringReport:
1418
+ """Content-safe result for one atomically published math mutation."""
1419
+
1420
+ status: str
1421
+ code: str | None
1422
+ source_sha256: str
1423
+ target: dict[str, int]
1424
+ input_format: str | None = None
1425
+ inserted_container: str | None = None
1426
+ structure_fingerprint_sha256: str | None = None
1427
+ destination_sha256: str | None = None
1428
+ non_target_document_bytes_preserved: bool | None = None
1429
+ non_target_parts_preserved: bool | None = None
1430
+
1431
+ @property
1432
+ def passed(self) -> bool:
1433
+ return self.status == _PUBLISHED
1434
+
1435
+ def to_dict(self) -> dict[str, Any]:
1436
+ return {
1437
+ "schema_version": 1,
1438
+ "operation": "math",
1439
+ "passed": self.passed,
1440
+ "status": self.status,
1441
+ "code": self.code,
1442
+ "source_sha256": self.source_sha256,
1443
+ "target": self.target,
1444
+ "input_format": self.input_format,
1445
+ "inserted_container": self.inserted_container,
1446
+ "structure_fingerprint_sha256": self.structure_fingerprint_sha256,
1447
+ "destination_sha256": self.destination_sha256,
1448
+ "non_target_document_bytes_preserved": self.non_target_document_bytes_preserved,
1449
+ "non_target_parts_preserved": self.non_target_parts_preserved,
1450
+ }
1451
+
1452
+
1453
+ def _math_refusal(request: MathRequest, code: str) -> MathAuthoringReport:
1454
+ return MathAuthoringReport(
1455
+ status=_REFUSED,
1456
+ code=code,
1457
+ source_sha256=request.source_sha256,
1458
+ target={"paragraph": request.paragraph},
1459
+ )
1460
+
1461
+
1462
+ def parse_math_request(value: Any) -> MathRequest:
1463
+ """Parse a source-bound math mutation; insertion remains the default."""
1464
+
1465
+ if not isinstance(value, Mapping):
1466
+ raise TypeError("math_request_invalid")
1467
+ fields = set(value)
1468
+ if fields - {"latex", "operation"} != _MATH_REQUEST_FIELDS:
1469
+ raise ValueError("math_request_fields_invalid")
1470
+ operation = value.get("operation", "insert")
1471
+ if operation not in ("insert", "edit", "delete"):
1472
+ raise ValueError("math_operation_invalid")
1473
+ source = value["source"]
1474
+ destination = value["destination"]
1475
+ target = value["target"]
1476
+ omml_xml = value["omml_xml"]
1477
+ mathml_xml = value["mathml_xml"]
1478
+ latex = value.get("latex")
1479
+ if not isinstance(source, str) or not source:
1480
+ raise ValueError("math_source_invalid")
1481
+ if not isinstance(destination, str) or not destination:
1482
+ raise ValueError("math_destination_invalid")
1483
+ if not isinstance(target, Mapping) or set(target) != {"paragraph"}:
1484
+ raise ValueError("math_target_invalid")
1485
+ if not isinstance(omml_xml, str | type(None)):
1486
+ raise TypeError("math_omml_xml_invalid")
1487
+ if not isinstance(mathml_xml, str | type(None)):
1488
+ raise TypeError("math_mathml_xml_invalid")
1489
+ if not isinstance(latex, str | type(None)):
1490
+ raise TypeError("math_latex_invalid")
1491
+ inputs = [item for item in (omml_xml, mathml_xml, latex) if item is not None]
1492
+ if len(inputs) != 1 and not (operation == "delete" and not inputs):
1493
+ raise ValueError("math_input_ambiguous")
1494
+ if inputs:
1495
+ payload = inputs[0]
1496
+ if not payload:
1497
+ raise ValueError("math_input_empty")
1498
+ if len(payload) > _MAX_TEXT_CHARACTERS:
1499
+ raise ValueError("math_input_character_limit")
1500
+ return MathRequest(
1501
+ source=Path(source),
1502
+ destination=Path(destination),
1503
+ source_sha256=_require_sha256(value["source_sha256"], "math_source_sha256"),
1504
+ structure_fingerprint_sha256=_require_sha256(
1505
+ value["structure_fingerprint_sha256"], "math_structure_fingerprint_sha256"
1506
+ ),
1507
+ paragraph=_require_positive_coordinate(target["paragraph"], "math_target_paragraph"),
1508
+ omml_xml=omml_xml,
1509
+ mathml_xml=mathml_xml,
1510
+ latex=latex,
1511
+ operation=operation,
1512
+ )
1513
+
1514
+
1515
+ def load_math_request(path: str | Path) -> MathRequest:
1516
+ """Load one UTF-8 JSON math mutation request."""
1517
+
1518
+ with Path(path).open(encoding="utf-8") as stream:
1519
+ return parse_math_request(json.load(stream))
1520
+
1521
+
1522
+ def _math_element(name: str, text: str | None = None) -> ET.Element:
1523
+ element = ET.Element(Q(_MATH_NAMESPACE, name))
1524
+ if text is not None:
1525
+ element.text = text
1526
+ return element
1527
+
1528
+
1529
+ def _math_value(name: str, value: str) -> ET.Element:
1530
+ element = _math_element(name)
1531
+ element.set(Q(_MATH_NAMESPACE, "val"), value)
1532
+ return element
1533
+
1534
+
1535
+ def _math_container(name: str, items: list[ET.Element]) -> ET.Element:
1536
+ container = _math_element(name)
1537
+ container.extend(items)
1538
+ return container
1539
+
1540
+
1541
+ def _math_run(text: str, *, style: str | None = None, script: str | None = None) -> ET.Element:
1542
+ """One OMML run; ``style`` is ``m:sty`` (``p`` upright), ``nor`` marks normal text."""
1543
+
1544
+ run = _math_element("r")
1545
+ if style is not None or script is not None:
1546
+ properties = _math_element("rPr")
1547
+ if style == "nor":
1548
+ properties.append(_math_element("nor"))
1549
+ else:
1550
+ if script is not None:
1551
+ properties.append(_math_value("scr", script))
1552
+ if style is not None:
1553
+ properties.append(_math_value("sty", style))
1554
+ run.append(properties)
1555
+ text_element = _math_element("t", text)
1556
+ if text != text.strip(" \t\r\n"):
1557
+ text_element.set(_XML_SPACE_ATTRIBUTE, "preserve")
1558
+ run.append(text_element)
1559
+ return run
1560
+
1561
+
1562
+ def _math_fraction(numerator: list[ET.Element], denominator: list[ET.Element]) -> ET.Element:
1563
+ fraction = _math_element("f")
1564
+ fraction.extend((_math_container("num", numerator), _math_container("den", denominator)))
1565
+ return fraction
1566
+
1567
+
1568
+ def _math_scripts(
1569
+ base: list[ET.Element], sub: list[ET.Element] | None, sup: list[ET.Element] | None
1570
+ ) -> ET.Element:
1571
+ if sub is not None and sup is not None:
1572
+ name, parts = "sSubSup", (("e", base), ("sub", sub), ("sup", sup))
1573
+ elif sub is not None:
1574
+ name, parts = "sSub", (("e", base), ("sub", sub))
1575
+ elif sup is not None:
1576
+ name, parts = "sSup", (("e", base), ("sup", sup))
1577
+ else:
1578
+ raise ValueError("math_script_missing")
1579
+ scripted = _math_element(name)
1580
+ scripted.extend(_math_container(role, items) for role, items in parts)
1581
+ return scripted
1582
+
1583
+
1584
+ def _math_radical(radicand: list[ET.Element], degree: list[ET.Element] | None) -> ET.Element:
1585
+ radical = _math_element("rad")
1586
+ if degree is None:
1587
+ properties = _math_element("radPr")
1588
+ properties.append(_math_value("degHide", "1"))
1589
+ radical.append(properties)
1590
+ radical.extend((_math_container("deg", degree or []), _math_container("e", radicand)))
1591
+ return radical
1592
+
1593
+
1594
+ def _math_delimiter(begin: str, end: str, items: list[ET.Element]) -> ET.Element:
1595
+ delimiter = _math_element("d")
1596
+ if begin != "(" or end != ")":
1597
+ properties = _math_element("dPr")
1598
+ properties.extend((_math_value("begChr", begin), _math_value("endChr", end)))
1599
+ delimiter.append(properties)
1600
+ delimiter.append(_math_container("e", items))
1601
+ return delimiter
1602
+
1603
+
1604
+ def _math_matrix(rows: list[list[list[ET.Element]]]) -> ET.Element:
1605
+ if not rows or any(not row for row in rows):
1606
+ raise ValueError("math_matrix_empty")
1607
+ matrix = _math_element("m")
1608
+ for row in rows:
1609
+ matrix_row = _math_element("mr")
1610
+ matrix_row.extend(_math_container("e", cell) for cell in row)
1611
+ matrix.append(matrix_row)
1612
+ return matrix
1613
+
1614
+
1615
+ def _math_accent(character: str, base: list[ET.Element]) -> ET.Element:
1616
+ accent = _math_element("acc")
1617
+ properties = _math_element("accPr")
1618
+ properties.append(_math_value("chr", character))
1619
+ accent.extend((properties, _math_container("e", base)))
1620
+ return accent
1621
+
1622
+
1623
+ def _math_limit(name: str, base: list[ET.Element], limit: list[ET.Element]) -> ET.Element:
1624
+ element = _math_element(name)
1625
+ element.extend((_math_container("e", base), _math_container("lim", limit)))
1626
+ return element
1627
+
1628
+
1629
+ #: Large operators that become ``m:nary``; integrals keep their limits at the side.
1630
+ _NARY_OPERATORS = frozenset("∫∬∭∮∯∰∑∏∐⋃⋂⋁⋀⨁⨂⨀")
1631
+ _INTEGRAL_OPERATORS = frozenset("∫∬∭∮∯∰")
1632
+ #: Relations end the operand of a preceding n-ary operator.
1633
+ _MATH_RELATIONS = frozenset("=<>≤≥≠≈≡∼≃≅∝→←↔⇒⇐⇔↦∈∉∋⊂⊆⊃⊇≪≫")
1634
+ #: Spacing accents are written as the combining characters Word stores in ``m:chr``.
1635
+ _ACCENT_CHARACTERS = {
1636
+ "^": "\u0302",
1637
+ "ˆ": "\u0302",
1638
+ "\u0302": "\u0302",
1639
+ "¯": "\u0305",
1640
+ "‾": "\u0305",
1641
+ "\u0305": "\u0305",
1642
+ "→": "\u20d7",
1643
+ "\u20d7": "\u20d7",
1644
+ "˙": "\u0307",
1645
+ "\u0307": "\u0307",
1646
+ "¨": "\u0308",
1647
+ "\u0308": "\u0308",
1648
+ "~": "\u0303",
1649
+ "˜": "\u0303",
1650
+ "\u0303": "\u0303",
1651
+ }
1652
+
1653
+
1654
+ @dataclass
1655
+ class _Nary:
1656
+ """An n-ary operator whose operand is the rest of its row up to a relation."""
1657
+
1658
+ character: str
1659
+ limits: str
1660
+ sub: list[ET.Element] | None
1661
+ sup: list[ET.Element] | None
1662
+
1663
+ def build(self, operand: list[ET.Element]) -> ET.Element:
1664
+ nary = _math_element("nary")
1665
+ properties = _math_element("naryPr")
1666
+ properties.append(_math_value("chr", self.character))
1667
+ properties.append(_math_value("limLoc", self.limits))
1668
+ if self.sub is None:
1669
+ properties.append(_math_value("subHide", "1"))
1670
+ if self.sup is None:
1671
+ properties.append(_math_value("supHide", "1"))
1672
+ nary.extend(
1673
+ (
1674
+ properties,
1675
+ _math_container("sub", self.sub or []),
1676
+ _math_container("sup", self.sup or []),
1677
+ _math_container("e", operand),
1678
+ )
1679
+ )
1680
+ return nary
1681
+
1682
+
1683
+ _MathItem = list[ET.Element] | _Nary
1684
+
1685
+
1686
+ def _is_relation(item: _MathItem) -> bool:
1687
+ if isinstance(item, _Nary) or len(item) != 1 or item[0].tag != Q(_MATH_NAMESPACE, "r"):
1688
+ return False
1689
+ return "".join(item[0].itertext()) in _MATH_RELATIONS
1690
+
1691
+
1692
+ def _math_row(items: list[_MathItem]) -> list[ET.Element]:
1693
+ """Flatten one row, giving each n-ary operator its operand up to a relation."""
1694
+
1695
+ out: list[ET.Element] = []
1696
+ index = 0
1697
+ while index < len(items):
1698
+ item = items[index]
1699
+ if isinstance(item, _Nary):
1700
+ end = index + 1
1701
+ while end < len(items) and not _is_relation(items[end]):
1702
+ end += 1
1703
+ out.append(item.build(_math_row(items[index + 1 : end])))
1704
+ index = end
1705
+ continue
1706
+ out.extend(item)
1707
+ index += 1
1708
+ return out
1709
+
1710
+
1711
+ def _mathml_children(element: ET.Element) -> list[ET.Element]:
1712
+ return [child for child in element if isinstance(child.tag, str)]
1713
+
1714
+
1715
+ def _mathml_local(element: ET.Element) -> str:
1716
+ if not isinstance(element.tag, str) or not element.tag.startswith("{"):
1717
+ raise ValueError("mathml_namespace_invalid")
1718
+ namespace, local = element.tag[1:].split("}", 1)
1719
+ if namespace != _MATHML_NAMESPACE:
1720
+ raise ValueError("mathml_namespace_invalid")
1721
+ return local
1722
+
1723
+
1724
+ def _mathml_operator(element: ET.Element) -> str | None:
1725
+ """The text of one ``mo`` element, or ``None`` for any other element."""
1726
+
1727
+ if _mathml_local(element) != "mo":
1728
+ return None
1729
+ return "".join(element.itertext()).strip()
1730
+
1731
+
1732
+ def _mathml_to_omml(element: ET.Element) -> list[ET.Element]:
1733
+ """Convert one MathML element to the OMML items it stands for."""
1734
+
1735
+ return _math_row([_mathml_item(element)])
1736
+
1737
+
1738
+ def _mathml_row(children: list[ET.Element]) -> list[ET.Element]:
1739
+ items: list[_MathItem] = []
1740
+ index = 0
1741
+ while index < len(children):
1742
+ if _mathml_operator(children[index]) == "\u2061":
1743
+ if not items or index + 1 == len(children) or isinstance(items[-1], _Nary):
1744
+ raise ValueError("mathml_function_invalid")
1745
+ function = _math_element("func")
1746
+ function.extend(
1747
+ (
1748
+ _math_container("fName", items.pop()),
1749
+ _math_container("e", _mathml_to_omml(children[index + 1])),
1750
+ )
1751
+ )
1752
+ items.append([function])
1753
+ index += 2
1754
+ else:
1755
+ items.append(_mathml_item(children[index]))
1756
+ index += 1
1757
+ return _math_row(items)
1758
+
1759
+
1760
+ _MATHML_VARIANTS = {
1761
+ "normal": (None, "p"),
1762
+ "bold": (None, "b"),
1763
+ "italic": (None, "i"),
1764
+ "bold-italic": (None, "bi"),
1765
+ "double-struck": ("double-struck", "p"),
1766
+ "script": ("script", None),
1767
+ "fraktur": ("fraktur", None),
1768
+ }
1769
+
1770
+
1771
+ # The operator dictionary's fences: an ``mrow`` that opens with one and closes with
1772
+ # another is a delimiter pair unless either operator says ``fence="false"``.
1773
+ _MATHML_OPENING_FENCES = frozenset("([{|‖⟨⌊⌈")
1774
+ _MATHML_CLOSING_FENCES = frozenset(")]}|‖⟩⌋⌉")
1775
+ _MATHML_NAMED_SPACES = {
1776
+ "thinmathspace": "0.1667em",
1777
+ "mediummathspace": "0.2222em",
1778
+ "thickmathspace": "0.2778em",
1779
+ }
1780
+ # The Unicode space each positive ``mspace`` width rounds to, matching the LaTeX
1781
+ # spacing commands: ``\,``, ``\:``/``\;``, ``\quad`` and ``\qquad``.
1782
+ _MATHML_SPACE_WIDTHS = (
1783
+ (0.17, "\u2009"),
1784
+ (0.28, "\u2005"),
1785
+ (1.0, "\u2003"),
1786
+ (2.0, "\u2003\u2003"),
1787
+ )
1788
+
1789
+
1790
+ def _mathml_fence(element: ET.Element, text: str, fences: frozenset[str]) -> bool:
1791
+ default = "true" if text in fences else "false"
1792
+ return element.get("fence", default) == "true"
1793
+
1794
+
1795
+ def _mathml_item(element: ET.Element) -> _MathItem:
1796
+ local = _mathml_local(element)
1797
+ children = _mathml_children(element)
1798
+ if local in {"math", "mrow", "mstyle"}:
1799
+ first = _mathml_operator(children[0]) if children else None
1800
+ last = _mathml_operator(children[-1]) if len(children) > 1 else None
1801
+ if (
1802
+ local == "mrow"
1803
+ and first is not None
1804
+ and last is not None
1805
+ and _mathml_fence(children[0], first, _MATHML_OPENING_FENCES)
1806
+ and _mathml_fence(children[-1], last, _MATHML_CLOSING_FENCES)
1807
+ ):
1808
+ return [_math_delimiter(first, last, _mathml_row(children[1:-1]))]
1809
+ return _mathml_row(children)
1810
+ if local == "semantics":
1811
+ if not children:
1812
+ raise ValueError("mathml_structure_invalid")
1813
+ return _mathml_item(children[0])
1814
+ if local == "mspace":
1815
+ width = element.get("width", "0em").strip()
1816
+ width = _MATHML_NAMED_SPACES.get(width, width)
1817
+ if not width.endswith("em"):
1818
+ raise ValueError("mathml_space_unsupported")
1819
+ try:
1820
+ ems = float(width[:-2])
1821
+ except ValueError:
1822
+ raise ValueError("mathml_space_unsupported") from None
1823
+ if ems <= 0:
1824
+ return []
1825
+ space = next((character for limit, character in _MATHML_SPACE_WIDTHS if ems <= limit), None)
1826
+ if space is None:
1827
+ raise ValueError("mathml_space_unsupported")
1828
+ return [_math_run(space)]
1829
+ if local in {"mi", "mn", "mo", "mtext"}:
1830
+ text = "".join(element.itertext())
1831
+ if local != "mtext":
1832
+ text = text.strip()
1833
+ if not text:
1834
+ raise ValueError("mathml_text_empty")
1835
+ if local == "mo" and text in _NARY_OPERATORS:
1836
+ return _Nary(text, "subSup" if text in _INTEGRAL_OPERATORS else "undOvr", None, None)
1837
+ if local == "mtext":
1838
+ return [_math_run(text, style="nor")]
1839
+ variant = element.get("mathvariant")
1840
+ if variant is not None:
1841
+ if variant not in _MATHML_VARIANTS:
1842
+ raise ValueError("mathml_variant_unsupported")
1843
+ script, style = _MATHML_VARIANTS[variant]
1844
+ return [_math_run(text, style=style, script=script)]
1845
+ if local == "mi" and len(text) > 1:
1846
+ return [_math_run(text, style="p")]
1847
+ return [_math_run(text)]
1848
+ if local == "mfrac":
1849
+ if len(children) != 2:
1850
+ raise ValueError("mathml_fraction_invalid")
1851
+ return [_math_fraction(_mathml_to_omml(children[0]), _mathml_to_omml(children[1]))]
1852
+ if local in {"msqrt", "mroot"}:
1853
+ if local == "msqrt":
1854
+ return [_math_radical(_mathml_row(children), None)]
1855
+ if len(children) != 2:
1856
+ raise ValueError("mathml_root_invalid")
1857
+ return [_math_radical(_mathml_to_omml(children[0]), _mathml_to_omml(children[1]))]
1858
+ scripts = {
1859
+ "msub": ("sub",),
1860
+ "msup": ("sup",),
1861
+ "msubsup": ("sub", "sup"),
1862
+ "munder": ("sub",),
1863
+ "mover": ("sup",),
1864
+ "munderover": ("sub", "sup"),
1865
+ }
1866
+ if local in scripts:
1867
+ roles = scripts[local]
1868
+ if len(children) != len(roles) + 1:
1869
+ raise ValueError("mathml_script_invalid")
1870
+ operator = _mathml_operator(children[0])
1871
+ parts = {
1872
+ role: _mathml_to_omml(child) for role, child in zip(roles, children[1:], strict=True)
1873
+ }
1874
+ if operator in _NARY_OPERATORS:
1875
+ limits = "undOvr" if local.startswith("mu") or local == "mover" else "subSup"
1876
+ return _Nary(operator, limits, parts.get("sub"), parts.get("sup"))
1877
+ base = _mathml_to_omml(children[0])
1878
+ if local in {"msub", "msup", "msubsup"}:
1879
+ return [_math_scripts(base, parts.get("sub"), parts.get("sup"))]
1880
+ if local in {"munder", "mover"}:
1881
+ character = _mathml_operator(children[1])
1882
+ if character in {"\u23df", "\u23de"}:
1883
+ group = _math_element("groupChr")
1884
+ properties = _math_element("groupChrPr")
1885
+ properties.extend(
1886
+ (
1887
+ _math_value("chr", character),
1888
+ _math_value("pos", "bot" if local == "munder" else "top"),
1889
+ _math_value("vertJc", "top" if local == "munder" else "bot"),
1890
+ )
1891
+ )
1892
+ group.extend((properties, _math_container("e", base)))
1893
+ return [group]
1894
+ if local == "mover" and element.get("accent") == "true":
1895
+ accent = _mathml_operator(children[1]) or "".join(children[1].itertext()).strip()
1896
+ if accent not in _ACCENT_CHARACTERS:
1897
+ raise ValueError("mathml_accent_unsupported")
1898
+ return [_math_accent(_ACCENT_CHARACTERS[accent], base)]
1899
+ if local == "munder":
1900
+ return [_math_limit("limLow", base, parts["sub"])]
1901
+ if local == "mover":
1902
+ return [_math_limit("limUpp", base, parts["sup"])]
1903
+ return [_math_limit("limUpp", [_math_limit("limLow", base, parts["sub"])], parts["sup"])]
1904
+ if local == "mtable":
1905
+ rows: list[list[list[ET.Element]]] = []
1906
+ for row in children:
1907
+ if _mathml_local(row) != "mtr":
1908
+ raise ValueError("mathml_table_invalid")
1909
+ cells = _mathml_children(row)
1910
+ if any(_mathml_local(cell) != "mtd" for cell in cells):
1911
+ raise ValueError("mathml_table_invalid")
1912
+ rows.append([_mathml_row(_mathml_children(cell)) for cell in cells])
1913
+ return [_math_matrix(rows)]
1914
+ if local == "mfenced":
1915
+ begin = element.get("open", "(")
1916
+ end = element.get("close", ")")
1917
+ separators = element.get("separators", ",").strip()
1918
+ items: list[_MathItem] = []
1919
+ for position, child in enumerate(children):
1920
+ if position and separators:
1921
+ items.append([_math_run(separators[min(position - 1, len(separators) - 1)])])
1922
+ items.append(_mathml_item(child))
1923
+ return [_math_delimiter(begin, end, _math_row(items))]
1924
+ raise ValueError("mathml_element_unsupported")
1925
+
1926
+
1927
+ # -- LaTeX --------------------------------------------------------------------
1928
+
1929
+ _LATEX_IDENTIFIERS = {
1930
+ "alpha": "α",
1931
+ "beta": "β",
1932
+ "gamma": "γ",
1933
+ "delta": "δ",
1934
+ "epsilon": "ϵ",
1935
+ "varepsilon": "ε",
1936
+ "zeta": "ζ",
1937
+ "eta": "η",
1938
+ "theta": "θ",
1939
+ "vartheta": "ϑ",
1940
+ "iota": "ι",
1941
+ "kappa": "κ",
1942
+ "lambda": "λ",
1943
+ "mu": "μ",
1944
+ "nu": "ν",
1945
+ "xi": "ξ",
1946
+ "pi": "π",
1947
+ "varpi": "ϖ",
1948
+ "rho": "ρ",
1949
+ "varrho": "ϱ",
1950
+ "sigma": "σ",
1951
+ "varsigma": "ς",
1952
+ "tau": "τ",
1953
+ "upsilon": "υ",
1954
+ "phi": "ϕ",
1955
+ "varphi": "φ",
1956
+ "chi": "χ",
1957
+ "psi": "ψ",
1958
+ "omega": "ω",
1959
+ "Gamma": "Γ",
1960
+ "Delta": "Δ",
1961
+ "Theta": "Θ",
1962
+ "Lambda": "Λ",
1963
+ "Xi": "Ξ",
1964
+ "Pi": "Π",
1965
+ "Sigma": "Σ",
1966
+ "Upsilon": "Υ",
1967
+ "Phi": "Φ",
1968
+ "Psi": "Ψ",
1969
+ "Omega": "Ω",
1970
+ "infty": "∞",
1971
+ "partial": "∂",
1972
+ "nabla": "∇",
1973
+ "ell": "ℓ",
1974
+ "hbar": "ℏ",
1975
+ "emptyset": "∅",
1976
+ "aleph": "ℵ",
1977
+ }
1978
+ _LATEX_OPERATORS = {
1979
+ "pm": "±",
1980
+ "mp": "∓",
1981
+ "times": "×",
1982
+ "cdot": "⋅",
1983
+ "div": "÷",
1984
+ "ast": "∗",
1985
+ "star": "⋆",
1986
+ "circ": "∘",
1987
+ "bullet": "∙",
1988
+ "oplus": "⊕",
1989
+ "otimes": "⊗",
1990
+ "leq": "≤",
1991
+ "le": "≤",
1992
+ "geq": "≥",
1993
+ "ge": "≥",
1994
+ "neq": "≠",
1995
+ "ne": "≠",
1996
+ "approx": "≈",
1997
+ "equiv": "≡",
1998
+ "sim": "∼",
1999
+ "simeq": "≃",
2000
+ "cong": "≅",
2001
+ "propto": "∝",
2002
+ "ll": "≪",
2003
+ "gg": "≫",
2004
+ "to": "→",
2005
+ "rightarrow": "→",
2006
+ "leftarrow": "←",
2007
+ "leftrightarrow": "↔",
2008
+ "Rightarrow": "⇒",
2009
+ "Leftarrow": "⇐",
2010
+ "Leftrightarrow": "⇔",
2011
+ "implies": "⇒",
2012
+ "iff": "⇔",
2013
+ "mapsto": "↦",
2014
+ "in": "∈",
2015
+ "notin": "∉",
2016
+ "ni": "∋",
2017
+ "subset": "⊂",
2018
+ "subseteq": "⊆",
2019
+ "supset": "⊃",
2020
+ "supseteq": "⊇",
2021
+ "cup": "∪",
2022
+ "cap": "∩",
2023
+ "setminus": "∖",
2024
+ "wedge": "∧",
2025
+ "land": "∧",
2026
+ "vee": "∨",
2027
+ "lor": "∨",
2028
+ "neg": "¬",
2029
+ "forall": "∀",
2030
+ "exists": "∃",
2031
+ "perp": "⊥",
2032
+ "parallel": "∥",
2033
+ "mid": "∣",
2034
+ "ldots": "…",
2035
+ "dots": "…",
2036
+ "cdots": "⋯",
2037
+ "vdots": "⋮",
2038
+ "ddots": "⋱",
2039
+ "prime": "′",
2040
+ "langle": "⟨",
2041
+ "rangle": "⟩",
2042
+ "lfloor": "⌊",
2043
+ "rfloor": "⌋",
2044
+ "lceil": "⌈",
2045
+ "rceil": "⌉",
2046
+ "{": "{",
2047
+ "}": "}",
2048
+ "|": "‖",
2049
+ "%": "%",
2050
+ "#": "#",
2051
+ "&": "&",
2052
+ "_": "_",
2053
+ }
2054
+ _LATEX_NARY = {
2055
+ "int": "∫",
2056
+ "iint": "∬",
2057
+ "iiint": "∭",
2058
+ "oint": "∮",
2059
+ "sum": "∑",
2060
+ "prod": "∏",
2061
+ "coprod": "∐",
2062
+ "bigcup": "⋃",
2063
+ "bigcap": "⋂",
2064
+ "bigvee": "⋁",
2065
+ "bigwedge": "⋀",
2066
+ "bigoplus": "⨁",
2067
+ "bigotimes": "⨂",
2068
+ }
2069
+ _LATEX_FUNCTIONS = frozenset(
2070
+ {
2071
+ "sin",
2072
+ "cos",
2073
+ "tan",
2074
+ "cot",
2075
+ "sec",
2076
+ "csc",
2077
+ "arcsin",
2078
+ "arccos",
2079
+ "arctan",
2080
+ "sinh",
2081
+ "cosh",
2082
+ "tanh",
2083
+ "coth",
2084
+ "log",
2085
+ "ln",
2086
+ "lg",
2087
+ "exp",
2088
+ "det",
2089
+ "dim",
2090
+ "ker",
2091
+ "deg",
2092
+ "gcd",
2093
+ "arg",
2094
+ "max",
2095
+ "min",
2096
+ "sup",
2097
+ "inf",
2098
+ "Pr",
2099
+ "hom",
2100
+ }
2101
+ )
2102
+ _LATEX_LIMIT_FUNCTIONS = frozenset({"lim", "limsup", "liminf"})
2103
+ _LATEX_ACCENTS = {
2104
+ "hat": "\u0302",
2105
+ "widehat": "\u0302",
2106
+ "bar": "\u0305",
2107
+ "vec": "\u20d7",
2108
+ "dot": "\u0307",
2109
+ "ddot": "\u0308",
2110
+ "tilde": "\u0303",
2111
+ "widetilde": "\u0303",
2112
+ }
2113
+ _LATEX_SPACES = {
2114
+ ",": "\u2009",
2115
+ ":": "\u2005",
2116
+ ";": "\u2005",
2117
+ "quad": "\u2003",
2118
+ "qquad": "\u2003\u2003",
2119
+ }
2120
+ _LATEX_IGNORED = frozenset({"!", "displaystyle", "textstyle", "limits", "nolimits"})
2121
+ _LATEX_FONTS = {
2122
+ "mathrm": (None, "p"),
2123
+ "operatorname": (None, "p"),
2124
+ "mathbf": (None, "b"),
2125
+ "mathit": (None, "i"),
2126
+ "mathbb": ("double-struck", "p"),
2127
+ "mathcal": ("script", None),
2128
+ "mathfrak": ("fraktur", None),
2129
+ }
2130
+ _LATEX_MATRICES = {
2131
+ "matrix": None,
2132
+ "pmatrix": ("(", ")"),
2133
+ "bmatrix": ("[", "]"),
2134
+ "Bmatrix": ("{", "}"),
2135
+ "vmatrix": ("|", "|"),
2136
+ "Vmatrix": ("‖", "‖"),
2137
+ }
2138
+ _LATEX_CHARACTER_OPERATORS = {"-": "−", "*": "∗", "'": "′"}
2139
+ _LATEX_DELIMITERS = {
2140
+ "(": "(",
2141
+ ")": ")",
2142
+ "[": "[",
2143
+ "]": "]",
2144
+ "|": "|",
2145
+ ".": "",
2146
+ "\\{": "{",
2147
+ "\\}": "}",
2148
+ "\\|": "‖",
2149
+ "\\langle": "⟨",
2150
+ "\\rangle": "⟩",
2151
+ "\\lfloor": "⌊",
2152
+ "\\rfloor": "⌋",
2153
+ "\\lceil": "⌈",
2154
+ "\\rceil": "⌉",
2155
+ }
2156
+ _MAX_LATEX_DEPTH = 64
2157
+
2158
+
2159
+ def _latex_tokens(source: str) -> list[tuple[str, int, int]]:
2160
+ """Split LaTeX math into commands (``\\name``), numbers and single characters."""
2161
+
2162
+ tokens: list[tuple[str, int, int]] = []
2163
+ index = 0
2164
+ while index < len(source):
2165
+ character = source[index]
2166
+ if character.isspace():
2167
+ index += 1
2168
+ continue
2169
+ end = index + 1
2170
+ if character == "\\":
2171
+ while end < len(source) and source[end].isascii() and source[end].isalpha():
2172
+ end += 1
2173
+ if end == index + 1:
2174
+ if end >= len(source):
2175
+ raise ValueError("latex_syntax_invalid")
2176
+ end += 1
2177
+ elif character.isdigit():
2178
+ while end < len(source) and (
2179
+ source[end].isdigit()
2180
+ or (source[end] == "." and end + 1 < len(source) and source[end + 1].isdigit())
2181
+ ):
2182
+ end += 1
2183
+ tokens.append((source[index:end], index, end))
2184
+ index = end
2185
+ return tokens
2186
+
2187
+
2188
+ _LATEX_TEXT_ESCAPES = {
2189
+ "\\{": "{",
2190
+ "\\}": "}",
2191
+ "\\%": "%",
2192
+ "\\&": "&",
2193
+ "\\#": "#",
2194
+ "\\_": "_",
2195
+ "\\ ": " ",
2196
+ }
2197
+
2198
+
2199
+ class _LatexParser:
2200
+ """A recursive-descent reader for the LaTeX math subset Word's equation editor imports."""
2201
+
2202
+ def __init__(self, source: str) -> None:
2203
+ self.source = source
2204
+ self.spans = _latex_tokens(source)
2205
+ self.tokens = [token for token, _start, _end in self.spans]
2206
+ self.position = 0
2207
+ self.depth = 0
2208
+
2209
+ def peek(self) -> str | None:
2210
+ return self.tokens[self.position] if self.position < len(self.tokens) else None
2211
+
2212
+ def take(self) -> str:
2213
+ token = self.peek()
2214
+ if token is None:
2215
+ raise ValueError("latex_syntax_invalid")
2216
+ self.position += 1
2217
+ return token
2218
+
2219
+ def expect(self, token: str) -> None:
2220
+ if self.take() != token:
2221
+ raise ValueError("latex_syntax_invalid")
2222
+
2223
+ def parse(self) -> list[ET.Element]:
2224
+ items = self.row(frozenset())
2225
+ if self.peek() is not None:
2226
+ raise ValueError("latex_group_unbalanced")
2227
+ return items
2228
+
2229
+ def row(self, stops: frozenset[str]) -> list[ET.Element]:
2230
+ """Read items until one of ``stops`` (left unread) or the end of input."""
2231
+
2232
+ self.depth += 1
2233
+ if self.depth > _MAX_LATEX_DEPTH:
2234
+ raise ValueError("latex_nesting_limit")
2235
+ items: list[_MathItem] = []
2236
+ while (token := self.peek()) is not None and token not in stops:
2237
+ if token == "}":
2238
+ raise ValueError("latex_group_unbalanced")
2239
+ item = self.atom()
2240
+ if item is None:
2241
+ continue
2242
+ items.append(self.scripts(item))
2243
+ self.depth -= 1
2244
+ return _math_row(items)
2245
+
2246
+ def group(self) -> list[ET.Element]:
2247
+ """One required argument: a braced group or a single atom."""
2248
+
2249
+ if self.peek() == "{":
2250
+ self.take()
2251
+ items = self.row(frozenset({"}"}))
2252
+ self.expect("}")
2253
+ return items
2254
+ item = self.atom()
2255
+ if item is None or isinstance(item, _Nary):
2256
+ raise ValueError("latex_argument_invalid")
2257
+ return item
2258
+
2259
+ def raw_group(self) -> str:
2260
+ """The verbatim source text of one braced argument, for ``\\text`` and names."""
2261
+
2262
+ self.expect("{")
2263
+ start = self.spans[self.position - 1][2]
2264
+ depth = 1
2265
+ while depth:
2266
+ token = self.take()
2267
+ depth += {"{": 1, "}": -1}.get(token, 0)
2268
+ text = self.source[start : self.spans[self.position - 1][1]]
2269
+ for escape, character in _LATEX_TEXT_ESCAPES.items():
2270
+ text = text.replace(escape, character)
2271
+ return text
2272
+
2273
+ def scripts(self, item: _MathItem) -> _MathItem:
2274
+ sub: list[ET.Element] | None = None
2275
+ explicit: list[ET.Element] | None = None
2276
+ primes: list[ET.Element] = []
2277
+ limits: str | None = None
2278
+ while (token := self.peek()) in {"_", "^", "'", "\\limits", "\\nolimits"}:
2279
+ self.take()
2280
+ if token == "\\limits":
2281
+ limits = "undOvr"
2282
+ elif token == "\\nolimits":
2283
+ limits = "subSup"
2284
+ elif token == "'":
2285
+ primes.append(_math_run("′"))
2286
+ elif token == "_":
2287
+ if sub is not None:
2288
+ raise ValueError("latex_double_subscript")
2289
+ sub = self.group()
2290
+ else:
2291
+ if explicit is not None:
2292
+ raise ValueError("latex_double_superscript")
2293
+ explicit = self.group()
2294
+ sup = [*primes, *(explicit or [])] if primes or explicit is not None else None
2295
+ if isinstance(item, _Nary):
2296
+ item.sub, item.sup = sub, sup
2297
+ if limits is not None:
2298
+ item.limits = limits
2299
+ return item
2300
+ if sub is None and sup is None:
2301
+ return item
2302
+ if not item:
2303
+ raise ValueError("latex_script_base_missing")
2304
+ if len(item) == 1 and item[0].tag == Q(_MATH_NAMESPACE, "r"):
2305
+ text = "".join(item[0].itertext())
2306
+ if text in {"lim", "lim sup", "lim inf"} and sup is None and sub is not None:
2307
+ return [_math_limit("limLow", item, sub)]
2308
+ return [_math_scripts(item, sub, sup)]
2309
+
2310
+ def atom(self) -> _MathItem | None:
2311
+ token = self.take()
2312
+ if token == "{":
2313
+ items = self.row(frozenset({"}"}))
2314
+ self.expect("}")
2315
+ return items
2316
+ if token in {"_", "^"}:
2317
+ raise ValueError("latex_script_base_missing")
2318
+ if token in {"&", "}"} or token == "\\\\":
2319
+ raise ValueError("latex_syntax_invalid")
2320
+ if not token.startswith("\\"):
2321
+ if token[0].isdigit():
2322
+ return [_math_run(token)]
2323
+ if token.isalpha():
2324
+ return [_math_run(token)]
2325
+ if token == "~":
2326
+ return [_math_run("\u00a0")]
2327
+ return [_math_run(_LATEX_CHARACTER_OPERATORS.get(token, token))]
2328
+ name = token[1:]
2329
+ if name in _LATEX_IGNORED:
2330
+ return None
2331
+ if name in _LATEX_SPACES:
2332
+ return [_math_run(_LATEX_SPACES[name])]
2333
+ if name in _LATEX_IDENTIFIERS:
2334
+ return [_math_run(_LATEX_IDENTIFIERS[name])]
2335
+ if name in _LATEX_OPERATORS:
2336
+ return [_math_run(_LATEX_OPERATORS[name])]
2337
+ if name in _LATEX_NARY:
2338
+ character = _LATEX_NARY[name]
2339
+ return _Nary(
2340
+ character,
2341
+ "subSup" if character in _INTEGRAL_OPERATORS else "undOvr",
2342
+ None,
2343
+ None,
2344
+ )
2345
+ if name in _LATEX_FUNCTIONS or name in _LATEX_LIMIT_FUNCTIONS:
2346
+ return [
2347
+ _math_run(
2348
+ name if name not in {"limsup", "liminf"} else name[:3] + " " + name[3:],
2349
+ style="p",
2350
+ )
2351
+ ]
2352
+ if name in {"frac", "dfrac", "tfrac"}:
2353
+ return [_math_fraction(self.group(), self.group())]
2354
+ if name == "sqrt":
2355
+ degree = None
2356
+ if self.peek() == "[":
2357
+ self.take()
2358
+ degree = self.row(frozenset({"]"}))
2359
+ self.expect("]")
2360
+ return [_math_radical(self.group(), degree)]
2361
+ if name in _LATEX_ACCENTS:
2362
+ return [_math_accent(_LATEX_ACCENTS[name], self.group())]
2363
+ if name in _LATEX_FONTS:
2364
+ script, style = _LATEX_FONTS[name]
2365
+ if self.peek() != "{":
2366
+ raise ValueError("latex_argument_invalid")
2367
+ text = self.raw_group()
2368
+ if not text:
2369
+ raise ValueError("latex_argument_invalid")
2370
+ return [_math_run(text, style=style, script=script)]
2371
+ if name in {"text", "textrm", "mbox"}:
2372
+ text = self.raw_group()
2373
+ if not text:
2374
+ raise ValueError("latex_argument_invalid")
2375
+ return [_math_run(text, style="nor")]
2376
+ if name == "left":
2377
+ begin = self.delimiter()
2378
+ items = self.row(frozenset({"\\right"}))
2379
+ self.expect("\\right")
2380
+ return [_math_delimiter(begin, self.delimiter(), items)]
2381
+ if name == "begin":
2382
+ return [self.environment()]
2383
+ raise ValueError("latex_command_unsupported")
2384
+
2385
+ def delimiter(self) -> str:
2386
+ token = self.take()
2387
+ if token not in _LATEX_DELIMITERS:
2388
+ raise ValueError("latex_delimiter_unsupported")
2389
+ return _LATEX_DELIMITERS[token]
2390
+
2391
+ def environment(self) -> ET.Element:
2392
+ name = self.raw_group()
2393
+ if name not in _LATEX_MATRICES:
2394
+ raise ValueError("latex_environment_unsupported")
2395
+ rows: list[list[list[ET.Element]]] = [[]]
2396
+ stops = frozenset({"&", "\\\\", "\\end"})
2397
+ while True:
2398
+ rows[-1].append(self.row(stops))
2399
+ token = self.take()
2400
+ if token == "\\\\":
2401
+ if self.peek() == "\\end":
2402
+ continue
2403
+ rows.append([])
2404
+ elif token == "\\end":
2405
+ break
2406
+ if self.raw_group() != name:
2407
+ raise ValueError("latex_environment_unbalanced")
2408
+ if len({len(row) for row in rows}) != 1:
2409
+ raise ValueError("latex_matrix_ragged")
2410
+ matrix = _math_matrix(rows)
2411
+ fences = _LATEX_MATRICES[name]
2412
+ if fences is None:
2413
+ return matrix
2414
+ return _math_delimiter(fences[0], fences[1], [matrix])
2415
+
2416
+
2417
+ def latex_to_omml(latex: str) -> ET.Element:
2418
+ """Convert one LaTeX math expression to an ``m:oMath`` element.
2419
+
2420
+ The admitted subset is what equation editors exchange: fractions, radicals,
2421
+ sub- and superscripts and primes, integrals, sums and other n-ary operators
2422
+ (``\\limits``/``\\nolimits``), ``\\left``/``\\right`` delimiters, the matrix
2423
+ environments (``matrix``, ``pmatrix``, ``bmatrix``, ``Bmatrix``, ``vmatrix``,
2424
+ ``Vmatrix``), accents, Greek letters, named functions, ``\\text`` and the
2425
+ ``\\mathrm``/``\\mathbf``/``\\mathbb``/``\\mathcal`` alphabets. An n-ary
2426
+ operator's operand is the rest of its group up to the next relation. Anything
2427
+ else is refused with a ``latex_*`` code rather than written approximately.
2428
+ """
2429
+
2430
+ if not latex.strip():
2431
+ raise ValueError("math_input_empty")
2432
+ items = _LatexParser(latex).parse()
2433
+ if not items:
2434
+ raise ValueError("math_input_empty")
2435
+ return _math_container("oMath", items)
2436
+
2437
+
2438
+ def _math_payload(request: MathRequest, word_namespace: str) -> tuple[bytes, str, str]:
2439
+ """Return schema-positioned OMML bytes, input format, and root container."""
2440
+
2441
+ inputs = [
2442
+ item for item in (request.omml_xml, request.mathml_xml, request.latex) if item is not None
2443
+ ]
2444
+ if len(inputs) != 1:
2445
+ raise ValueError("math_input_ambiguous")
2446
+ try:
2447
+ if request.omml_xml is not None:
2448
+ root = ET.fromstring(request.omml_xml)
2449
+ input_format = "omml"
2450
+ elif request.latex is not None:
2451
+ root = latex_to_omml(request.latex)
2452
+ input_format = "latex"
2453
+ else:
2454
+ mathml = ET.fromstring(request.mathml_xml or "")
2455
+ root = _math_container("oMath", _mathml_to_omml(mathml))
2456
+ if _mathml_local(mathml) == "math" and mathml.get("display") == "block":
2457
+ root = _math_container("oMathPara", [root])
2458
+ input_format = "mathml"
2459
+ except ET.ParseError as error:
2460
+ raise ValueError("math_xml_invalid") from error
2461
+ if not isinstance(root.tag, str) or not root.tag.startswith("{"):
2462
+ raise ValueError("omml_namespace_invalid")
2463
+ namespace, container = root.tag[1:].split("}", 1)
2464
+ if namespace not in {_MATH_NAMESPACE, _STRICT_MATH_NAMESPACE} or container not in {
2465
+ "oMath",
2466
+ "oMathPara",
2467
+ }:
2468
+ raise ValueError("omml_container_invalid")
2469
+ target_math = (
2470
+ _STRICT_MATH_NAMESPACE
2471
+ if word_namespace == "http://purl.oclc.org/ooxml/wordprocessingml/main"
2472
+ else _MATH_NAMESPACE
2473
+ )
2474
+ namespace_map = {
2475
+ _MATH_NAMESPACE: target_math,
2476
+ _STRICT_MATH_NAMESPACE: target_math,
2477
+ "http://schemas.openxmlformats.org/wordprocessingml/2006/main": word_namespace,
2478
+ "http://purl.oclc.org/ooxml/wordprocessingml/main": word_namespace,
2479
+ }
2480
+ for element in root.iter():
2481
+ if not isinstance(element.tag, str):
2482
+ continue
2483
+ for old, new in namespace_map.items():
2484
+ if element.tag.startswith("{" + old + "}"):
2485
+ element.tag = Q(new, element.tag.split("}", 1)[1])
2486
+ break
2487
+ for name, value in list(element.attrib.items()):
2488
+ for old, new in namespace_map.items():
2489
+ if name.startswith("{" + old + "}"):
2490
+ del element.attrib[name]
2491
+ element.set(Q(new, name.split("}", 1)[1]), value)
2492
+ break
2493
+ ET.register_namespace("m", target_math)
2494
+ ET.register_namespace("w", word_namespace)
2495
+ return ET.tostring(root, encoding="utf-8"), input_format, container
2496
+
2497
+
2498
+ def _paragraph_parent(root: ET.Element, paragraph: ET.Element) -> ET.Element | None:
2499
+ return next((parent for parent in root.iter() if paragraph in parent), None)
2500
+
2501
+
2502
+ def _patch_paragraph_math(
2503
+ document_xml: bytes,
2504
+ *,
2505
+ word_namespace: str,
2506
+ paragraph: int,
2507
+ payload: bytes,
2508
+ container: str | None,
2509
+ operation: str = "insert",
2510
+ ) -> bytes | None:
2511
+ """Patch only lexical target bytes; refuse missing or ambiguous math targets."""
2512
+
2513
+ parser = expat.ParserCreate(namespace_separator="}")
2514
+ stack: list[str] = []
2515
+ found = 0
2516
+ target_depth: int | None = None
2517
+ insertion: int | None = None
2518
+ target_start: int | None = None
2519
+ target_end: int | None = None
2520
+ math_spans: list[tuple[int, int, str]] = []
2521
+ math_start: int | None = None
2522
+ math_depth: int | None = None
2523
+ display_adjacent = False
2524
+ math_names = {
2525
+ f"{ns}" + "}" + name
2526
+ for ns in (_MATH_NAMESPACE, _STRICT_MATH_NAMESPACE)
2527
+ for name in ("oMath", "oMathPara")
2528
+ }
2529
+ target_name = f"{word_namespace}" + "}p"
2530
+
2531
+ def start_element(name: str, attributes: dict[str, str]) -> None:
2532
+ nonlocal found, target_depth, target_start, math_start, math_depth, display_adjacent
2533
+ del attributes
2534
+ stack.append(name)
2535
+ if name == target_name:
2536
+ found += 1
2537
+ if found == paragraph:
2538
+ target_depth = len(stack)
2539
+ target_start = parser.CurrentByteIndex
2540
+ direct_math = target_depth is not None and len(stack) == target_depth + 1
2541
+ adjacent_math = display_adjacent and name in {
2542
+ f"{ns}" + "}oMathPara" for ns in (_MATH_NAMESPACE, _STRICT_MATH_NAMESPACE)
2543
+ }
2544
+ if name in math_names and (direct_math or adjacent_math) and math_depth is None:
2545
+ math_start = parser.CurrentByteIndex
2546
+ math_depth = len(stack)
2547
+ if display_adjacent:
2548
+ display_adjacent = False
2549
+
2550
+ def end_element(name: str) -> None:
2551
+ nonlocal insertion, target_depth, target_end, math_start, math_depth, display_adjacent
2552
+ if math_depth == len(stack):
2553
+ assert math_start is not None
2554
+ end = parser.CurrentByteIndex
2555
+ if document_xml[end : end + 2] == b"</":
2556
+ end = document_xml.find(b">", end) + 1
2557
+ math_spans.append((math_start, end, name.split("}", 1)[1]))
2558
+ math_start = math_depth = None
2559
+ if name == target_name and target_depth == len(stack):
2560
+ insertion = parser.CurrentByteIndex
2561
+ if document_xml[insertion : insertion + 2] == b"</":
2562
+ target_end = document_xml.find(b">", insertion) + 1
2563
+ else:
2564
+ target_end = insertion
2565
+ display_adjacent = True
2566
+ target_depth = None
2567
+ stack.pop()
2568
+
2569
+ parser.StartElementHandler = start_element
2570
+ parser.EndElementHandler = end_element
2571
+ try:
2572
+ parser.Parse(document_xml, True)
2573
+ except expat.ExpatError:
2574
+ return None
2575
+ if insertion is None:
2576
+ return None
2577
+ if operation != "insert":
2578
+ if not math_spans:
2579
+ raise ValueError("math_target_missing")
2580
+ if len(math_spans) != 1:
2581
+ raise ValueError("math_target_ambiguous")
2582
+ start, end, original_container = math_spans[0]
2583
+ if operation == "edit" and container != original_container:
2584
+ raise ValueError("math_container_position_mismatch")
2585
+ return (
2586
+ document_xml[:start] + (b"" if operation == "delete" else payload) + document_xml[end:]
2587
+ )
2588
+ if target_start is not None and target_end == insertion:
2589
+ opening = document_xml[target_start:insertion]
2590
+ if not opening.rstrip().endswith(b"/>"):
2591
+ return None
2592
+ name = opening[1:].split(None, 1)[0].rstrip(b"/>")
2593
+ expanded = opening.rstrip()[:-2] + b">"
2594
+ closing = b"</" + name + b">"
2595
+ addition = payload + closing if container == "oMath" else closing + payload
2596
+ return document_xml[:target_start] + expanded + addition + document_xml[insertion:]
2597
+ if container == "oMath":
2598
+ return document_xml[:insertion] + payload + document_xml[insertion:]
2599
+ end = document_xml.find(b">", insertion)
2600
+ if end < insertion:
2601
+ return None
2602
+ return document_xml[: end + 1] + payload + document_xml[end + 1 :]
2603
+
2604
+
2605
+ def author_paragraph_math(request: MathRequest) -> MathAuthoringReport:
2606
+ """Mutate one equation atomically, preserving every non-target package byte."""
2607
+
2608
+ source = request.source.resolve()
2609
+ destination = request.destination.resolve()
2610
+ if source == destination:
2611
+ return _math_refusal(request, "source_destination_same")
2612
+ if not source.is_file():
2613
+ return _math_refusal(request, "source_missing")
2614
+ if not destination.parent.is_dir():
2615
+ return _math_refusal(request, "destination_parent_missing")
2616
+ if _sha256_file(source) != request.source_sha256:
2617
+ return _math_refusal(request, "source_hash_mismatch")
2618
+ if request.operation not in ("insert", "edit", "delete"):
2619
+ return _math_refusal(request, "math_operation_invalid")
2620
+ baseline = inspect_docx(source)
2621
+ if not baseline.valid or baseline.file_sha256 != request.source_sha256:
2622
+ return _math_refusal(request, "source_inspection_invalid")
2623
+ try:
2624
+ graph = PackageGraph.from_file(source)
2625
+ document_xml = graph.read_part_bytes("word/document.xml")
2626
+ root = ET.fromstring(document_xml)
2627
+ except PackageError:
2628
+ return _math_refusal(request, "source_document_missing")
2629
+ except ET.ParseError:
2630
+ return _math_refusal(request, "source_document_invalid")
2631
+ word_namespace = _word_namespace(root)
2632
+ if word_namespace is None:
2633
+ return _math_refusal(request, "source_word_namespace_unsupported")
2634
+ try:
2635
+ if request.operation == "delete":
2636
+ payload, input_format, container = b"", None, None
2637
+ else:
2638
+ payload, input_format, container = _math_payload(request, word_namespace)
2639
+ except ValueError as error:
2640
+ return _math_refusal(request, str(error))
2641
+ paragraph = _selected_paragraph(root, request, word_namespace)
2642
+ if paragraph is None:
2643
+ return _math_refusal(request, "paragraph_coordinate_missing")
2644
+ if _paragraph_parent(root, paragraph) is not root.find(Q(word_namespace, "body")):
2645
+ return _math_refusal(request, "paragraph_not_body")
2646
+ if _paragraph_structure_fingerprint(paragraph) != request.structure_fingerprint_sha256:
2647
+ return _math_refusal(request, "paragraph_structure_mismatch")
2648
+ if _has_unsupported_ancestor(root, paragraph, word_namespace):
2649
+ return _math_refusal(request, "paragraph_context_unsupported")
2650
+ try:
2651
+ patched = _patch_paragraph_math(
2652
+ document_xml,
2653
+ word_namespace=word_namespace,
2654
+ paragraph=request.paragraph,
2655
+ payload=payload,
2656
+ container=container,
2657
+ operation=request.operation,
2658
+ )
2659
+ except ValueError as error:
2660
+ return _math_refusal(request, str(error))
2661
+ if patched is None:
2662
+ return _math_refusal(request, "paragraph_math_patch_unsupported")
2663
+ staged_path: Path | None = None
2664
+ try:
2665
+ with tempfile.NamedTemporaryFile(
2666
+ dir=destination.parent,
2667
+ prefix=f".{destination.name}.",
2668
+ suffix=".tmp",
2669
+ delete=False,
2670
+ ) as staged:
2671
+ staged_path = Path(staged.name)
2672
+ _write_staged_package(source, staged_path, patched)
2673
+ candidate = inspect_docx(staged_path)
2674
+ candidate_xml: bytes | None = None
2675
+ inserted = request.operation == "delete"
2676
+ if candidate.valid:
2677
+ try:
2678
+ candidate_xml = PackageGraph.from_file(staged_path).read_part_bytes(
2679
+ "word/document.xml"
2680
+ )
2681
+ candidate_root = ET.fromstring(candidate_xml)
2682
+ candidate_paragraph = _selected_paragraph(candidate_root, request, word_namespace)
2683
+ math_namespace = (
2684
+ _STRICT_MATH_NAMESPACE
2685
+ if word_namespace == "http://purl.oclc.org/ooxml/wordprocessingml/main"
2686
+ else _MATH_NAMESPACE
2687
+ )
2688
+ if container == "oMath":
2689
+ inserted = bool(
2690
+ candidate_paragraph is not None
2691
+ and any(
2692
+ child.tag == Q(math_namespace, "oMath") for child in candidate_paragraph
2693
+ )
2694
+ )
2695
+ elif container == "oMathPara":
2696
+ body = candidate_root.find(Q(word_namespace, "body"))
2697
+ inserted = bool(
2698
+ body is not None
2699
+ and any(child.tag == Q(math_namespace, "oMathPara") for child in body)
2700
+ )
2701
+ except (ET.ParseError, PackageError):
2702
+ pass
2703
+ document_preserved = candidate_xml == patched
2704
+ parts_preserved = _non_target_part_bytes_preserved(source, staged_path)
2705
+ source_still_bound = _sha256_file(source) == request.source_sha256
2706
+ if not (
2707
+ candidate.valid
2708
+ and inserted
2709
+ and document_preserved
2710
+ and parts_preserved
2711
+ and source_still_bound
2712
+ ):
2713
+ return _math_refusal(
2714
+ request,
2715
+ "staged_verification_failed" if source_still_bound else "source_hash_changed",
2716
+ )
2717
+ os.replace(staged_path, destination)
2718
+ staged_path = None
2719
+ return MathAuthoringReport(
2720
+ status=_PUBLISHED,
2721
+ code=None,
2722
+ source_sha256=request.source_sha256,
2723
+ target={"paragraph": request.paragraph},
2724
+ input_format=input_format,
2725
+ inserted_container=container,
2726
+ structure_fingerprint_sha256=request.structure_fingerprint_sha256,
2727
+ destination_sha256=candidate.file_sha256,
2728
+ non_target_document_bytes_preserved=True,
2729
+ non_target_parts_preserved=True,
2730
+ )
2731
+ finally:
2732
+ if staged_path is not None:
2733
+ staged_path.unlink(missing_ok=True)
2734
+
2735
+
2736
+ def insert_equation(
2737
+ source: str | Path,
2738
+ destination: str | Path,
2739
+ *,
2740
+ paragraph: int = 1,
2741
+ latex: str | None = None,
2742
+ mathml: str | None = None,
2743
+ omml: str | None = None,
2744
+ ) -> MathAuthoringReport:
2745
+ """Insert one equation, given as LaTeX, MathML or OMML, into a body paragraph.
2746
+
2747
+ Exactly one of ``latex``, ``mathml`` and ``omml`` is accepted. The request is
2748
+ bound to the source's current digest and the paragraph's structure fingerprint,
2749
+ then published through :func:`author_paragraph_math`, so every other package
2750
+ byte is preserved and nothing is written on refusal.
2751
+ """
2752
+
2753
+ source_path = Path(source)
2754
+ request = MathRequest(
2755
+ source=source_path,
2756
+ destination=Path(destination),
2757
+ source_sha256=_sha256_file(source_path) if source_path.is_file() else "",
2758
+ structure_fingerprint_sha256="",
2759
+ paragraph=paragraph,
2760
+ omml_xml=omml,
2761
+ mathml_xml=mathml,
2762
+ latex=latex,
2763
+ )
2764
+ if sum(item is not None for item in (latex, mathml, omml)) != 1:
2765
+ return _math_refusal(request, "math_input_ambiguous")
2766
+ if not source_path.is_file():
2767
+ return _math_refusal(request, "source_missing")
2768
+ if isinstance(paragraph, bool) or not isinstance(paragraph, int) or paragraph < 1:
2769
+ return _math_refusal(request, "math_target_paragraph_invalid")
2770
+ fingerprint = paragraph_structure_fingerprint(source_path, paragraph=paragraph)
2771
+ if fingerprint is None:
2772
+ return _math_refusal(request, "paragraph_coordinate_missing")
2773
+ return author_paragraph_math(replace(request, structure_fingerprint_sha256=fingerprint))