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.
- wolfdocx/__init__.py +25 -0
- wolfdocx/_cache_root.py +24 -0
- wolfdocx/_comment_threads.py +278 -0
- wolfdocx/_inspection_cache.py +374 -0
- wolfdocx/_version.py +3 -0
- wolfdocx/admission.py +163 -0
- wolfdocx/assembly.py +463 -0
- wolfdocx/authoring.py +2773 -0
- wolfdocx/canonical.py +267 -0
- wolfdocx/content.py +963 -0
- wolfdocx/document.py +215 -0
- wolfdocx/errors.py +169 -0
- wolfdocx/find_replace.py +1210 -0
- wolfdocx/formatting.py +3160 -0
- wolfdocx/inspect.py +3999 -0
- wolfdocx/model.py +1038 -0
- wolfdocx/numbering_authoring.py +1422 -0
- wolfdocx/output.py +13 -0
- wolfdocx/package.py +2313 -0
- wolfdocx/package_profile.py +128 -0
- wolfdocx/page_setup.py +2483 -0
- wolfdocx/paragraph_authoring.py +1842 -0
- wolfdocx/properties.py +2728 -0
- wolfdocx/protection.py +1909 -0
- wolfdocx/regions.py +1993 -0
- wolfdocx/render_warnings.py +106 -0
- wolfdocx/reporting.py +943 -0
- wolfdocx/review.py +2862 -0
- wolfdocx/run_text.py +117 -0
- wolfdocx/section_break.py +1810 -0
- wolfdocx/session_ops/__init__.py +45 -0
- wolfdocx/session_ops/_bridge.py +151 -0
- wolfdocx/session_ops/lists.py +104 -0
- wolfdocx/session_ops/paragraphs.py +39 -0
- wolfdocx/session_ops/rich_objects.py +2598 -0
- wolfdocx/session_ops/run_edits.py +70 -0
- wolfdocx/session_ops/runs.py +313 -0
- wolfdocx/session_ops/sections.py +109 -0
- wolfdocx/session_ops/styling.py +99 -0
- wolfdocx/session_ops/tables.py +247 -0
- wolfdocx/styles_authoring.py +2822 -0
- wolfdocx/table_cell_properties.py +1458 -0
- wolfdocx/table_column.py +1501 -0
- wolfdocx/table_delete.py +942 -0
- wolfdocx/table_insert.py +1114 -0
- wolfdocx/table_merge.py +1863 -0
- wolfdocx/table_properties.py +2429 -0
- wolfdocx/table_row_properties.py +1095 -0
- wolfdocx/table_structure.py +1044 -0
- wolfdocx/text_effects.py +1438 -0
- wolfdocx-0.1.0.dist-info/METADATA +127 -0
- wolfdocx-0.1.0.dist-info/RECORD +54 -0
- wolfdocx-0.1.0.dist-info/WHEEL +4 -0
- 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("&", "&").replace("<", "<").replace(">", ">").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))
|