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/find_replace.py
ADDED
|
@@ -0,0 +1,1210 @@
|
|
|
1
|
+
"""Cross-run and cross-paragraph regex find and replace with formatting preservation.
|
|
2
|
+
|
|
3
|
+
Provides atomic search and replacement spanning arbitrary ``w:r`` run boundaries
|
|
4
|
+
within a paragraph or across consecutive paragraphs, preserving boundary formatting,
|
|
5
|
+
paragraph properties, inline wrapper ancestry, and untouched package parts. Discovery
|
|
6
|
+
includes tracked revision text and field instructions; edits to those protected
|
|
7
|
+
values refuse atomically with ``find_replace_protected_text``.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import bisect
|
|
13
|
+
import copy
|
|
14
|
+
import hashlib
|
|
15
|
+
import json
|
|
16
|
+
import re
|
|
17
|
+
import tempfile
|
|
18
|
+
import xml.etree.ElementTree as ET
|
|
19
|
+
import zipfile
|
|
20
|
+
from collections.abc import Callable, Iterator, Mapping
|
|
21
|
+
from dataclasses import dataclass, field
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
from typing import Any
|
|
24
|
+
|
|
25
|
+
from wolfdocx.inspect import (
|
|
26
|
+
_inspect_docx,
|
|
27
|
+
_require_verify_mode,
|
|
28
|
+
_unchanged_parts_identical,
|
|
29
|
+
_verify_changed_parts,
|
|
30
|
+
parse_xml_with_preserved_qnames,
|
|
31
|
+
serialize_xml_with_preserved_qnames,
|
|
32
|
+
)
|
|
33
|
+
from wolfdocx.package import (
|
|
34
|
+
PackageError,
|
|
35
|
+
PackageFormatError,
|
|
36
|
+
PackageGraph,
|
|
37
|
+
PackageSafetyError,
|
|
38
|
+
)
|
|
39
|
+
from wolfdocx.review import _link_no_clobber
|
|
40
|
+
|
|
41
|
+
__all__ = [
|
|
42
|
+
"FindReplaceOptions",
|
|
43
|
+
"FindReplaceReport",
|
|
44
|
+
"FindReplaceRequest",
|
|
45
|
+
"discover_matches",
|
|
46
|
+
"find_replace",
|
|
47
|
+
"load_find_replace_request",
|
|
48
|
+
"parse_find_replace_request",
|
|
49
|
+
]
|
|
50
|
+
_WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
|
|
51
|
+
_XML_SPACE = "{http://www.w3.org/XML/1998/namespace}space"
|
|
52
|
+
_DOCUMENT = "word/document.xml"
|
|
53
|
+
_SHA256_LENGTH = 64
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class _FindReplaceValidationError(ValueError):
|
|
57
|
+
"""Invalid find/replace values or protected text, identified by a refusal code."""
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _q(tag: str, ns: str = _WORD_NS) -> str:
|
|
61
|
+
return f"{{{ns}}}{tag}"
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _local(tag: str) -> str:
|
|
65
|
+
return tag.rsplit("}", 1)[-1] if "}" in tag else tag
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _sha256(path: Path) -> str:
|
|
69
|
+
hasher = hashlib.sha256()
|
|
70
|
+
with path.open("rb") as stream:
|
|
71
|
+
while chunk := stream.read(65536):
|
|
72
|
+
hasher.update(chunk)
|
|
73
|
+
return hasher.hexdigest()
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _word_namespace(root: ET.Element) -> str:
|
|
77
|
+
if root.tag.startswith("{") and "}" in root.tag:
|
|
78
|
+
return root.tag[1 : root.tag.rindex("}")]
|
|
79
|
+
return _WORD_NS
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
@dataclass(frozen=True, slots=True)
|
|
83
|
+
class FindReplaceOptions:
|
|
84
|
+
"""Configuration options for regex find and replace operations.
|
|
85
|
+
|
|
86
|
+
The searched text joins consecutive paragraphs with ``"\\n"``, so a match may span
|
|
87
|
+
paragraphs. ``multiline`` (the default) makes ``^`` and ``$`` anchor at every
|
|
88
|
+
paragraph and line-break boundary, the way they anchor on each paragraph's text.
|
|
89
|
+
Without it they anchor only at the edges of a whole run of consecutive sibling
|
|
90
|
+
paragraphs (a table cell's content, or the body text between tables).
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
ignore_case: bool = False
|
|
94
|
+
multiline: bool = True
|
|
95
|
+
dotall: bool = True
|
|
96
|
+
paragraph_merge_policy: str = "keep_first" # "keep_first" | "keep_last" | "merge"
|
|
97
|
+
max_replacements: int | None = None
|
|
98
|
+
|
|
99
|
+
def __post_init__(self) -> None:
|
|
100
|
+
for name in ("ignore_case", "multiline", "dotall"):
|
|
101
|
+
if not isinstance(getattr(self, name), bool):
|
|
102
|
+
raise _FindReplaceValidationError(f"find_replace_option_invalid:{name}")
|
|
103
|
+
if self.paragraph_merge_policy not in ("keep_first", "keep_last", "merge"):
|
|
104
|
+
raise _FindReplaceValidationError("find_replace_option_invalid:paragraph_merge_policy")
|
|
105
|
+
budget = self.max_replacements
|
|
106
|
+
if budget is not None and (type(budget) is not int or budget < 0):
|
|
107
|
+
raise _FindReplaceValidationError("find_replace_option_invalid:max_replacements")
|
|
108
|
+
|
|
109
|
+
def to_dict(self) -> dict[str, Any]:
|
|
110
|
+
return {
|
|
111
|
+
"ignore_case": self.ignore_case,
|
|
112
|
+
"multiline": self.multiline,
|
|
113
|
+
"dotall": self.dotall,
|
|
114
|
+
"paragraph_merge_policy": self.paragraph_merge_policy,
|
|
115
|
+
"max_replacements": self.max_replacements,
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class FindReplaceRequest:
|
|
120
|
+
"""One bounded find and replace operation over a DOCX package."""
|
|
121
|
+
|
|
122
|
+
source: Path
|
|
123
|
+
source_sha256: str
|
|
124
|
+
destination: Path
|
|
125
|
+
pattern: str
|
|
126
|
+
replacement: str | Callable[[re.Match[str]], str]
|
|
127
|
+
part: str
|
|
128
|
+
options: FindReplaceOptions
|
|
129
|
+
|
|
130
|
+
def __init__(
|
|
131
|
+
self,
|
|
132
|
+
source: str | Path,
|
|
133
|
+
destination: str | Path | None = None,
|
|
134
|
+
*,
|
|
135
|
+
output: str | Path | None = None,
|
|
136
|
+
pattern: str = "",
|
|
137
|
+
replacement: str | Callable[[re.Match[str]], str] = "",
|
|
138
|
+
source_sha256: str | None = None,
|
|
139
|
+
part: str = _DOCUMENT,
|
|
140
|
+
options: FindReplaceOptions | Mapping[str, Any] | None = None,
|
|
141
|
+
) -> None:
|
|
142
|
+
src_path = Path(source)
|
|
143
|
+
object.__setattr__(self, "source", src_path)
|
|
144
|
+
|
|
145
|
+
dest = destination if destination is not None else output
|
|
146
|
+
if dest is None:
|
|
147
|
+
raise ValueError("find_replace_destination_required")
|
|
148
|
+
object.__setattr__(self, "destination", Path(dest))
|
|
149
|
+
|
|
150
|
+
if source_sha256 is not None:
|
|
151
|
+
sha = source_sha256
|
|
152
|
+
elif src_path.is_file():
|
|
153
|
+
sha = _sha256(src_path)
|
|
154
|
+
else:
|
|
155
|
+
sha = ""
|
|
156
|
+
object.__setattr__(self, "source_sha256", sha)
|
|
157
|
+
|
|
158
|
+
object.__setattr__(self, "pattern", str(pattern))
|
|
159
|
+
object.__setattr__(self, "replacement", replacement)
|
|
160
|
+
object.__setattr__(self, "part", str(part))
|
|
161
|
+
|
|
162
|
+
if isinstance(options, FindReplaceOptions):
|
|
163
|
+
opts = options
|
|
164
|
+
elif isinstance(options, Mapping):
|
|
165
|
+
opts = FindReplaceOptions(**options)
|
|
166
|
+
else:
|
|
167
|
+
opts = FindReplaceOptions()
|
|
168
|
+
object.__setattr__(self, "options", opts)
|
|
169
|
+
|
|
170
|
+
@property
|
|
171
|
+
def output(self) -> Path:
|
|
172
|
+
"""Alias for destination."""
|
|
173
|
+
return self.destination
|
|
174
|
+
|
|
175
|
+
def to_dict(self) -> dict[str, Any]:
|
|
176
|
+
return {
|
|
177
|
+
"source": str(self.source),
|
|
178
|
+
"destination": str(self.destination),
|
|
179
|
+
"source_sha256": self.source_sha256,
|
|
180
|
+
"pattern": self.pattern,
|
|
181
|
+
"replacement": (
|
|
182
|
+
self.replacement if isinstance(self.replacement, str) else "<callable>"
|
|
183
|
+
),
|
|
184
|
+
"part": self.part,
|
|
185
|
+
"options": self.options.to_dict(),
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
@dataclass(frozen=True, slots=True)
|
|
190
|
+
class FindReplaceReport:
|
|
191
|
+
"""The receipt of one find and replace operation."""
|
|
192
|
+
|
|
193
|
+
status: str
|
|
194
|
+
code: str | None
|
|
195
|
+
source_sha256: str
|
|
196
|
+
destination: str | None
|
|
197
|
+
match_count: int
|
|
198
|
+
replacement_count: int
|
|
199
|
+
matches: list[dict[str, Any]]
|
|
200
|
+
unselected_parts_preserved: bool
|
|
201
|
+
|
|
202
|
+
@property
|
|
203
|
+
def passed(self) -> bool:
|
|
204
|
+
return self.status in ("published", "applied")
|
|
205
|
+
|
|
206
|
+
def to_dict(self) -> dict[str, Any]:
|
|
207
|
+
return {
|
|
208
|
+
"status": self.status,
|
|
209
|
+
"code": self.code,
|
|
210
|
+
"source_sha256": self.source_sha256,
|
|
211
|
+
"destination": self.destination,
|
|
212
|
+
"match_count": self.match_count,
|
|
213
|
+
"replacement_count": self.replacement_count,
|
|
214
|
+
"matches": self.matches,
|
|
215
|
+
"unselected_parts_preserved": self.unselected_parts_preserved,
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _refusal(
|
|
220
|
+
source_sha256: str,
|
|
221
|
+
code: str,
|
|
222
|
+
destination: Path | None = None,
|
|
223
|
+
) -> FindReplaceReport:
|
|
224
|
+
return FindReplaceReport(
|
|
225
|
+
status="refused",
|
|
226
|
+
code=code,
|
|
227
|
+
source_sha256=source_sha256,
|
|
228
|
+
destination=str(destination) if destination is not None else None,
|
|
229
|
+
match_count=0,
|
|
230
|
+
replacement_count=0,
|
|
231
|
+
matches=[],
|
|
232
|
+
unselected_parts_preserved=True,
|
|
233
|
+
)
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def parse_find_replace_request(data: Any) -> FindReplaceRequest:
|
|
237
|
+
"""Parse and validate a dictionary representation of a FindReplaceRequest."""
|
|
238
|
+
if not isinstance(data, Mapping):
|
|
239
|
+
raise TypeError("find_replace_request_invalid")
|
|
240
|
+
source = data.get("source")
|
|
241
|
+
if not source:
|
|
242
|
+
raise ValueError("find_replace_source_required")
|
|
243
|
+
destination = data.get("destination") or data.get("output")
|
|
244
|
+
if not destination:
|
|
245
|
+
raise ValueError("find_replace_destination_required")
|
|
246
|
+
pattern = data.get("pattern", "")
|
|
247
|
+
replacement = data.get("replacement", "")
|
|
248
|
+
source_sha256 = data.get("source_sha256")
|
|
249
|
+
part = data.get("part", _DOCUMENT)
|
|
250
|
+
raw_opts = data.get("options")
|
|
251
|
+
options = FindReplaceOptions(**raw_opts) if isinstance(raw_opts, Mapping) else None
|
|
252
|
+
return FindReplaceRequest(
|
|
253
|
+
source=source,
|
|
254
|
+
destination=destination,
|
|
255
|
+
pattern=pattern,
|
|
256
|
+
replacement=replacement,
|
|
257
|
+
source_sha256=source_sha256,
|
|
258
|
+
part=part,
|
|
259
|
+
options=options,
|
|
260
|
+
)
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def load_find_replace_request(path: str | Path) -> FindReplaceRequest:
|
|
264
|
+
"""Load and validate a JSON FindReplaceRequest from disk."""
|
|
265
|
+
with Path(path).open("r", encoding="utf-8") as stream:
|
|
266
|
+
return parse_find_replace_request(json.load(stream))
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
# ---------------------------------------------------------------------------
|
|
270
|
+
# DOM Inspection and Run Text Helpers
|
|
271
|
+
# ---------------------------------------------------------------------------
|
|
272
|
+
|
|
273
|
+
_TEXT_TAGS = frozenset({"t", "tab", "br", "cr", "noBreakHyphen"})
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _extract_run_text_segments(run: ET.Element, ns: str) -> list[tuple[str, ET.Element | None]]:
|
|
277
|
+
"""Extract ``(text_piece, source_element)`` from the text-bearing children of a run.
|
|
278
|
+
|
|
279
|
+
``w:t`` text carries no element; ``w:tab``, ``w:br``, ``w:cr`` and ``w:noBreakHyphen``
|
|
280
|
+
carry their source element so a rebuilt run re-emits them as elements. A page break
|
|
281
|
+
contributes no searchable text but is still carried, as a zero-width segment.
|
|
282
|
+
"""
|
|
283
|
+
segments: list[tuple[str, ET.Element | None]] = []
|
|
284
|
+
t_tag = _q("t", ns)
|
|
285
|
+
tab_tag = _q("tab", ns)
|
|
286
|
+
br_tag = _q("br", ns)
|
|
287
|
+
cr_tag = _q("cr", ns)
|
|
288
|
+
hyphen_tag = _q("noBreakHyphen", ns)
|
|
289
|
+
|
|
290
|
+
for child in run:
|
|
291
|
+
tag = child.tag
|
|
292
|
+
if tag == t_tag:
|
|
293
|
+
segments.append((child.text or "", None))
|
|
294
|
+
elif tag == tab_tag:
|
|
295
|
+
segments.append(("\t", child))
|
|
296
|
+
elif tag == br_tag:
|
|
297
|
+
br_type = child.get(_q("type", ns))
|
|
298
|
+
segments.append(("" if br_type == "page" else "\n", child))
|
|
299
|
+
elif tag == cr_tag:
|
|
300
|
+
segments.append(("\r", child))
|
|
301
|
+
elif tag == hyphen_tag:
|
|
302
|
+
segments.append(("-", child))
|
|
303
|
+
return segments
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def _is_text_run(run: ET.Element, ns: str) -> bool:
|
|
307
|
+
"""True if run contains only run properties and text-bearing child elements."""
|
|
308
|
+
rpr_tag = _q("rPr", ns)
|
|
309
|
+
for child in run:
|
|
310
|
+
tag = child.tag
|
|
311
|
+
if tag == rpr_tag:
|
|
312
|
+
continue
|
|
313
|
+
local = _local(tag)
|
|
314
|
+
if local not in _TEXT_TAGS:
|
|
315
|
+
return False
|
|
316
|
+
return True
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
def _make_text(text: str, ns: str) -> ET.Element:
|
|
320
|
+
t_node = ET.Element(_q("t", ns))
|
|
321
|
+
t_node.text = text
|
|
322
|
+
if text.startswith(" ") or text.endswith(" ") or " " in text or "\t" in text:
|
|
323
|
+
t_node.set(_XML_SPACE, "preserve")
|
|
324
|
+
return t_node
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
def _make_run(
|
|
328
|
+
parts: list[str | ET.Element],
|
|
329
|
+
rpr: ET.Element | None,
|
|
330
|
+
ns: str = _WORD_NS,
|
|
331
|
+
) -> ET.Element:
|
|
332
|
+
"""Create a new w:r with a clone of ``rpr`` holding ``parts`` in order.
|
|
333
|
+
|
|
334
|
+
Consecutive characters coalesce into one ``w:t``; elements are cloned in place.
|
|
335
|
+
"""
|
|
336
|
+
run = ET.Element(_q("r", ns))
|
|
337
|
+
if rpr is not None:
|
|
338
|
+
run.append(copy.deepcopy(rpr))
|
|
339
|
+
chars: list[str] = []
|
|
340
|
+
for part in parts:
|
|
341
|
+
if isinstance(part, str):
|
|
342
|
+
chars.append(part)
|
|
343
|
+
continue
|
|
344
|
+
if chars:
|
|
345
|
+
run.append(_make_text("".join(chars), ns))
|
|
346
|
+
chars = []
|
|
347
|
+
run.append(copy.deepcopy(part))
|
|
348
|
+
if chars:
|
|
349
|
+
run.append(_make_text("".join(chars), ns))
|
|
350
|
+
return run
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def _replacement_parts(text: str, ns: str) -> list[str | ET.Element]:
|
|
354
|
+
"""Split replacement text into characters and ``w:tab`` elements for its tabs."""
|
|
355
|
+
if "\t" not in text:
|
|
356
|
+
return [text]
|
|
357
|
+
parts: list[str | ET.Element] = []
|
|
358
|
+
for index, piece in enumerate(text.split("\t")):
|
|
359
|
+
if index:
|
|
360
|
+
parts.append(ET.Element(_q("tab", ns)))
|
|
361
|
+
if piece:
|
|
362
|
+
parts.append(piece)
|
|
363
|
+
return parts
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
def _rpr_signature(rpr: ET.Element | None) -> str:
|
|
367
|
+
"""Canonical string representation of rPr for coalescing runs."""
|
|
368
|
+
if rpr is None:
|
|
369
|
+
return ""
|
|
370
|
+
return ET.tostring(rpr, encoding="unicode")
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
# ---------------------------------------------------------------------------
|
|
374
|
+
# Paragraph Group Processing: Coordinate Mapping & Splicing
|
|
375
|
+
# ---------------------------------------------------------------------------
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
@dataclass
|
|
379
|
+
class _CharCoord:
|
|
380
|
+
char: str
|
|
381
|
+
para_idx: int
|
|
382
|
+
rpr: ET.Element | None
|
|
383
|
+
is_para_break: bool = False
|
|
384
|
+
# The source w:tab/w:br/w:cr/w:noBreakHyphen this character stands for, if any.
|
|
385
|
+
element: ET.Element | None = None
|
|
386
|
+
wrappers: tuple[ET.Element, ...] = ()
|
|
387
|
+
protected: bool = False
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
@dataclass
|
|
391
|
+
class _ParagraphItem:
|
|
392
|
+
"""One element of a paragraph: either an opaque element or a text run."""
|
|
393
|
+
|
|
394
|
+
is_opaque: bool
|
|
395
|
+
opaque_element: ET.Element | None = None
|
|
396
|
+
rpr: ET.Element | None = None
|
|
397
|
+
text: str = ""
|
|
398
|
+
segments: list[tuple[str, ET.Element | None]] = field(default_factory=list)
|
|
399
|
+
wrappers: tuple[ET.Element, ...] = ()
|
|
400
|
+
protected: bool = False
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
def _decompose_paragraph(p: ET.Element, ns: str) -> tuple[ET.Element | None, list[_ParagraphItem]]:
|
|
404
|
+
"""Flatten editable inline content while retaining wrapper ancestry and barriers."""
|
|
405
|
+
ppr = p.find(_q("pPr", ns))
|
|
406
|
+
items: list[_ParagraphItem] = []
|
|
407
|
+
wrapper_tags = {
|
|
408
|
+
_q(tag, ns)
|
|
409
|
+
for tag in ("hyperlink", "sdt", "sdtContent", "customXml", "smartTag", "fldSimple")
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
def visit(child: ET.Element, wrappers: tuple[ET.Element, ...]) -> None:
|
|
413
|
+
if child.tag in {_q("ins", ns), _q("del", ns)}:
|
|
414
|
+
text = "".join(
|
|
415
|
+
node.text or ""
|
|
416
|
+
for node in child.iter()
|
|
417
|
+
if node.tag in {_q("t", ns), _q("delText", ns), _q("instrText", ns)}
|
|
418
|
+
)
|
|
419
|
+
items.append(_ParagraphItem(True, child, text=text, wrappers=wrappers, protected=True))
|
|
420
|
+
elif child.tag in wrapper_tags:
|
|
421
|
+
ancestry = (*wrappers, child)
|
|
422
|
+
# Anchor the shell even when every result character is deleted.
|
|
423
|
+
items.append(_ParagraphItem(True, wrappers=ancestry))
|
|
424
|
+
if child.tag == _q("fldSimple", ns):
|
|
425
|
+
items.append(
|
|
426
|
+
_ParagraphItem(
|
|
427
|
+
False,
|
|
428
|
+
text=child.get(_q("instr", ns), ""),
|
|
429
|
+
wrappers=ancestry,
|
|
430
|
+
protected=True,
|
|
431
|
+
)
|
|
432
|
+
)
|
|
433
|
+
for nested in child:
|
|
434
|
+
visit(nested, ancestry)
|
|
435
|
+
elif child.tag == _q("r", ns) and _is_text_run(child, ns):
|
|
436
|
+
segments = _extract_run_text_segments(child, ns)
|
|
437
|
+
items.append(
|
|
438
|
+
_ParagraphItem(
|
|
439
|
+
False,
|
|
440
|
+
rpr=child.find(_q("rPr", ns)),
|
|
441
|
+
text="".join(seg[0] for seg in segments),
|
|
442
|
+
segments=segments,
|
|
443
|
+
wrappers=wrappers,
|
|
444
|
+
)
|
|
445
|
+
)
|
|
446
|
+
else:
|
|
447
|
+
text = "".join(
|
|
448
|
+
node.text or ""
|
|
449
|
+
for node in child.iter()
|
|
450
|
+
if node.tag in {_q("instrText", ns), _q("delText", ns)}
|
|
451
|
+
)
|
|
452
|
+
items.append(
|
|
453
|
+
_ParagraphItem(True, child, text=text, wrappers=wrappers, protected=bool(text))
|
|
454
|
+
)
|
|
455
|
+
|
|
456
|
+
for child in p:
|
|
457
|
+
if child.tag != _q("pPr", ns):
|
|
458
|
+
visit(child, ())
|
|
459
|
+
return ppr, items
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def _apply_ppr_policy(
|
|
463
|
+
ppr_first: ET.Element | None,
|
|
464
|
+
ppr_last: ET.Element | None,
|
|
465
|
+
policy: str,
|
|
466
|
+
) -> ET.Element | None:
|
|
467
|
+
"""Determine paragraph properties for a merged boundary paragraph."""
|
|
468
|
+
if policy == "keep_last":
|
|
469
|
+
return copy.deepcopy(ppr_last) if ppr_last is not None else None
|
|
470
|
+
if policy == "merge":
|
|
471
|
+
if ppr_first is None:
|
|
472
|
+
return copy.deepcopy(ppr_last) if ppr_last is not None else None
|
|
473
|
+
if ppr_last is None:
|
|
474
|
+
return copy.deepcopy(ppr_first)
|
|
475
|
+
merged = copy.deepcopy(ppr_first)
|
|
476
|
+
first_tags = {child.tag for child in merged}
|
|
477
|
+
for child in ppr_last:
|
|
478
|
+
if child.tag not in first_tags:
|
|
479
|
+
merged.append(copy.deepcopy(child))
|
|
480
|
+
else:
|
|
481
|
+
for idx, existing in enumerate(list(merged)):
|
|
482
|
+
if existing.tag == child.tag:
|
|
483
|
+
merged[idx] = copy.deepcopy(child)
|
|
484
|
+
break
|
|
485
|
+
return merged
|
|
486
|
+
# Default: "keep_first"
|
|
487
|
+
return copy.deepcopy(ppr_first) if ppr_first is not None else None
|
|
488
|
+
|
|
489
|
+
|
|
490
|
+
def _process_paragraph_group(
|
|
491
|
+
group: list[tuple[int, ET.Element]],
|
|
492
|
+
compiled_pattern: re.Pattern[str],
|
|
493
|
+
replacement: str | Callable[[re.Match[str]], str],
|
|
494
|
+
options: FindReplaceOptions,
|
|
495
|
+
ns: str,
|
|
496
|
+
part_name: str,
|
|
497
|
+
remaining_budget: int | None,
|
|
498
|
+
discovery: bool = False,
|
|
499
|
+
) -> tuple[list[tuple[int, int, list[ET.Element]]], list[dict[str, Any]], int]:
|
|
500
|
+
"""Search and atomically replace patterns across a group of consecutive paragraphs.
|
|
501
|
+
|
|
502
|
+
The group's paragraph texts are searched as one ``"\\n"``-joined string, and only
|
|
503
|
+
the paragraphs a match touches (joined with every paragraph a cross-paragraph
|
|
504
|
+
match spans) are rebuilt; every other paragraph keeps its element untouched.
|
|
505
|
+
|
|
506
|
+
Returns:
|
|
507
|
+
(rebuilt_ranges, match_records, num_replacements_performed), where each
|
|
508
|
+
rebuilt range is ``(first_child_index, last_child_index, new_paragraphs)``
|
|
509
|
+
in document order.
|
|
510
|
+
"""
|
|
511
|
+
if not group:
|
|
512
|
+
return [], [], 0
|
|
513
|
+
|
|
514
|
+
decomposed = [_decompose_paragraph(p, ns) for _, p in group]
|
|
515
|
+
texts = ["".join(item.text for item in items) for _, items in decomposed]
|
|
516
|
+
matches = list(compiled_pattern.finditer("\n".join(texts)))
|
|
517
|
+
|
|
518
|
+
if remaining_budget is not None and remaining_budget >= 0:
|
|
519
|
+
matches = matches[:remaining_budget]
|
|
520
|
+
|
|
521
|
+
if not matches:
|
|
522
|
+
return [], [], 0
|
|
523
|
+
|
|
524
|
+
# starts[k] is paragraph k's first offset; its virtual break sits at
|
|
525
|
+
# starts[k + 1] - 1 and belongs to paragraph k.
|
|
526
|
+
starts: list[int] = []
|
|
527
|
+
offset = 0
|
|
528
|
+
for text in texts:
|
|
529
|
+
starts.append(offset)
|
|
530
|
+
offset += len(text) + 1
|
|
531
|
+
|
|
532
|
+
def paragraph_at(position: int) -> int:
|
|
533
|
+
return bisect.bisect_right(starts, position) - 1
|
|
534
|
+
|
|
535
|
+
if not discovery:
|
|
536
|
+
protected_ranges: list[tuple[int, int]] = []
|
|
537
|
+
for start, (_, items) in zip(starts, decomposed, strict=True):
|
|
538
|
+
for item in items:
|
|
539
|
+
end = start + len(item.text)
|
|
540
|
+
if item.protected:
|
|
541
|
+
protected_ranges.append((start, end))
|
|
542
|
+
start = end
|
|
543
|
+
for match in matches:
|
|
544
|
+
s, e = match.span()
|
|
545
|
+
if any(
|
|
546
|
+
s < end and e > start or s == e and start <= s < end
|
|
547
|
+
for start, end in protected_ranges
|
|
548
|
+
):
|
|
549
|
+
raise _FindReplaceValidationError("find_replace_protected_text")
|
|
550
|
+
|
|
551
|
+
match_records: list[dict[str, Any]] = []
|
|
552
|
+
# Each cluster: [first_paragraph, last_paragraph, [(start, end, replacement), ...]]
|
|
553
|
+
clusters: list[list[Any]] = []
|
|
554
|
+
for m in matches:
|
|
555
|
+
s, e = m.span()
|
|
556
|
+
try:
|
|
557
|
+
repl_str = replacement(m) if callable(replacement) else m.expand(replacement)
|
|
558
|
+
except (TypeError, ValueError, IndexError, re.error) as exc:
|
|
559
|
+
raise _FindReplaceValidationError("find_replace_replacement_invalid") from exc
|
|
560
|
+
if not isinstance(repl_str, str):
|
|
561
|
+
raise _FindReplaceValidationError("find_replace_replacement_invalid")
|
|
562
|
+
first, last = paragraph_at(s), paragraph_at(e)
|
|
563
|
+
touched_paras = list(range(first, paragraph_at(e - 1) + 1)) if e > s else []
|
|
564
|
+
match_records.append(
|
|
565
|
+
{
|
|
566
|
+
"pattern": compiled_pattern.pattern,
|
|
567
|
+
"matched_text": m.group(0),
|
|
568
|
+
"replacement_text": repl_str,
|
|
569
|
+
"part": part_name,
|
|
570
|
+
"paragraphs": touched_paras,
|
|
571
|
+
"span": [s, e],
|
|
572
|
+
}
|
|
573
|
+
)
|
|
574
|
+
if clusters and first <= clusters[-1][1]:
|
|
575
|
+
clusters[-1][1] = max(clusters[-1][1], last)
|
|
576
|
+
clusters[-1][2].append((s, e, repl_str))
|
|
577
|
+
else:
|
|
578
|
+
clusters.append([first, last, [(s, e, repl_str)]])
|
|
579
|
+
if discovery:
|
|
580
|
+
return [], match_records, len(matches)
|
|
581
|
+
|
|
582
|
+
rebuilt: list[tuple[int, int, list[ET.Element]]] = []
|
|
583
|
+
for first, last, spans in clusters:
|
|
584
|
+
base = starts[first]
|
|
585
|
+
new_paragraphs = _rebuild_paragraphs(
|
|
586
|
+
decomposed[first : last + 1],
|
|
587
|
+
[(s - base, e - base, repl_str) for s, e, repl_str in spans],
|
|
588
|
+
options,
|
|
589
|
+
ns,
|
|
590
|
+
[paragraph for _, paragraph in group[first : last + 1]],
|
|
591
|
+
)
|
|
592
|
+
rebuilt.append((group[first][0], group[last][0], new_paragraphs))
|
|
593
|
+
return rebuilt, match_records, len(matches)
|
|
594
|
+
|
|
595
|
+
|
|
596
|
+
def _rebuild_paragraphs(
|
|
597
|
+
decomposed: list[tuple[ET.Element | None, list[_ParagraphItem]]],
|
|
598
|
+
spans: list[tuple[int, int, str]],
|
|
599
|
+
options: FindReplaceOptions,
|
|
600
|
+
ns: str,
|
|
601
|
+
source_paragraphs: list[ET.Element],
|
|
602
|
+
) -> list[ET.Element]:
|
|
603
|
+
"""Rebuild consecutive paragraphs with ``spans`` replaced in their joined text.
|
|
604
|
+
|
|
605
|
+
Span offsets index the paragraphs' texts joined with one virtual ``"\\n"`` break.
|
|
606
|
+
"""
|
|
607
|
+
# Build character coordinate stream
|
|
608
|
+
char_coords: list[_CharCoord] = []
|
|
609
|
+
# Elements anchored at a character offset, in document order:
|
|
610
|
+
# (offset, element, in_run, rpr). Opaque paragraph children have ``in_run`` False;
|
|
611
|
+
# zero-width run children (page breaks) are re-emitted inside a run with ``rpr``.
|
|
612
|
+
opaque_anchors: list[
|
|
613
|
+
tuple[int, ET.Element | None, bool, ET.Element | None, tuple[ET.Element, ...]]
|
|
614
|
+
] = []
|
|
615
|
+
|
|
616
|
+
for p_idx, (_, items) in enumerate(decomposed):
|
|
617
|
+
for item in items:
|
|
618
|
+
if item.is_opaque:
|
|
619
|
+
opaque_anchors.append(
|
|
620
|
+
(len(char_coords), item.opaque_element, False, None, item.wrappers)
|
|
621
|
+
)
|
|
622
|
+
if item.protected:
|
|
623
|
+
char_coords.extend(
|
|
624
|
+
_CharCoord(ch, p_idx, item.rpr, wrappers=item.wrappers, protected=True)
|
|
625
|
+
for ch in item.text
|
|
626
|
+
)
|
|
627
|
+
continue
|
|
628
|
+
if item.is_opaque:
|
|
629
|
+
continue
|
|
630
|
+
for text, element in item.segments:
|
|
631
|
+
if element is not None and not text:
|
|
632
|
+
opaque_anchors.append(
|
|
633
|
+
(len(char_coords), element, True, item.rpr, item.wrappers)
|
|
634
|
+
)
|
|
635
|
+
for ch in text:
|
|
636
|
+
char_coords.append(
|
|
637
|
+
_CharCoord(
|
|
638
|
+
char=ch,
|
|
639
|
+
para_idx=p_idx,
|
|
640
|
+
rpr=item.rpr,
|
|
641
|
+
element=element,
|
|
642
|
+
wrappers=item.wrappers,
|
|
643
|
+
)
|
|
644
|
+
)
|
|
645
|
+
# Virtual paragraph break between consecutive paragraphs
|
|
646
|
+
if p_idx < len(decomposed) - 1:
|
|
647
|
+
char_coords.append(
|
|
648
|
+
_CharCoord(
|
|
649
|
+
char="\n",
|
|
650
|
+
para_idx=p_idx,
|
|
651
|
+
rpr=None,
|
|
652
|
+
is_para_break=True,
|
|
653
|
+
)
|
|
654
|
+
)
|
|
655
|
+
|
|
656
|
+
# Map each match to its replacement string and chosen inherited rPr
|
|
657
|
+
# Each entry: (start, end, repl_text, inherited_rpr, touched_paras)
|
|
658
|
+
replacements: list[tuple[int, int, str, ET.Element | None, list[int]]] = []
|
|
659
|
+
|
|
660
|
+
for s, e, repl_str in spans:
|
|
661
|
+
# Inherit rpr from the first character in the matched range that has rpr
|
|
662
|
+
inherited_rpr: ET.Element | None = None
|
|
663
|
+
touched_paras: list[int] = []
|
|
664
|
+
for i in range(s, e):
|
|
665
|
+
cc = char_coords[i]
|
|
666
|
+
if cc.para_idx not in touched_paras:
|
|
667
|
+
touched_paras.append(cc.para_idx)
|
|
668
|
+
if inherited_rpr is None and cc.rpr is not None:
|
|
669
|
+
inherited_rpr = copy.deepcopy(cc.rpr)
|
|
670
|
+
|
|
671
|
+
replacements.append((s, e, repl_str, inherited_rpr, touched_paras))
|
|
672
|
+
|
|
673
|
+
# Reconstruct paragraphs by streaming through characters and replacements
|
|
674
|
+
new_paragraphs: list[ET.Element] = []
|
|
675
|
+
|
|
676
|
+
current_para_children: list[ET.Element] = []
|
|
677
|
+
current_run_parts: list[str | ET.Element] = []
|
|
678
|
+
current_run_rpr: ET.Element | None = None
|
|
679
|
+
current_ppr: ET.Element | None = copy.deepcopy(decomposed[0][0])
|
|
680
|
+
current_p_idx = 0
|
|
681
|
+
current_wrappers: tuple[ET.Element, ...] = ()
|
|
682
|
+
current_shell_idx = 0
|
|
683
|
+
emitted_shells: set[int] = set()
|
|
684
|
+
wrapper_copies: dict[int, ET.Element] = {}
|
|
685
|
+
|
|
686
|
+
def append_child(element: ET.Element | None, wrappers: tuple[ET.Element, ...]) -> None:
|
|
687
|
+
parent = None
|
|
688
|
+
for wrapper in wrappers:
|
|
689
|
+
clone = wrapper_copies.get(id(wrapper))
|
|
690
|
+
if clone is None:
|
|
691
|
+
clone = ET.Element(wrapper.tag, dict(wrapper.attrib))
|
|
692
|
+
clone.text, clone.tail = wrapper.text, wrapper.tail
|
|
693
|
+
wrapper_copies[id(wrapper)] = clone
|
|
694
|
+
if parent is None:
|
|
695
|
+
current_para_children.append(clone)
|
|
696
|
+
else:
|
|
697
|
+
parent.append(clone)
|
|
698
|
+
parent = clone
|
|
699
|
+
if element is None:
|
|
700
|
+
return
|
|
701
|
+
if parent is None:
|
|
702
|
+
current_para_children.append(element)
|
|
703
|
+
else:
|
|
704
|
+
parent.append(element)
|
|
705
|
+
|
|
706
|
+
def flush_run() -> None:
|
|
707
|
+
nonlocal current_run_parts, current_run_rpr
|
|
708
|
+
if current_run_parts:
|
|
709
|
+
run_elem = _make_run(current_run_parts, current_run_rpr, ns)
|
|
710
|
+
append_child(run_elem, current_wrappers)
|
|
711
|
+
current_run_parts = []
|
|
712
|
+
current_run_rpr = None
|
|
713
|
+
|
|
714
|
+
def close_paragraph() -> None:
|
|
715
|
+
nonlocal current_para_children, current_ppr, wrapper_copies
|
|
716
|
+
flush_run()
|
|
717
|
+
# Retain paragraph identity and lexical namespace provenance. A split's
|
|
718
|
+
# additional paragraphs are new identities, not copies of the old anchor.
|
|
719
|
+
p = copy.copy(source_paragraphs[current_shell_idx])
|
|
720
|
+
del p[:]
|
|
721
|
+
if current_shell_idx in emitted_shells:
|
|
722
|
+
for name in ("paraId", "textId"):
|
|
723
|
+
p.attrib.pop(_q(name, "http://schemas.microsoft.com/office/word/2010/wordml"), None)
|
|
724
|
+
emitted_shells.add(current_shell_idx)
|
|
725
|
+
if current_ppr is not None:
|
|
726
|
+
p.append(current_ppr)
|
|
727
|
+
for child in current_para_children:
|
|
728
|
+
p.append(child)
|
|
729
|
+
new_paragraphs.append(p)
|
|
730
|
+
current_para_children = []
|
|
731
|
+
current_ppr = None
|
|
732
|
+
wrapper_copies = {}
|
|
733
|
+
|
|
734
|
+
signatures: dict[int, str] = {}
|
|
735
|
+
|
|
736
|
+
def starts_new_run(rpr: ET.Element | None) -> bool:
|
|
737
|
+
# Runs coalesce only across identical rPr; the source rPr elements outlive this
|
|
738
|
+
# call through ``decomposed``, so their ids are stable signature keys.
|
|
739
|
+
if not current_run_parts or rpr is current_run_rpr:
|
|
740
|
+
return False
|
|
741
|
+
signature = []
|
|
742
|
+
for element in (current_run_rpr, rpr):
|
|
743
|
+
if element is None:
|
|
744
|
+
signature.append("")
|
|
745
|
+
continue
|
|
746
|
+
cached = signatures.get(id(element))
|
|
747
|
+
if cached is None:
|
|
748
|
+
cached = signatures[id(element)] = _rpr_signature(element)
|
|
749
|
+
signature.append(cached)
|
|
750
|
+
return signature[0] != signature[1]
|
|
751
|
+
|
|
752
|
+
def append_to_run(
|
|
753
|
+
part: str | ET.Element, rpr: ET.Element | None, wrappers: tuple[ET.Element, ...] = ()
|
|
754
|
+
) -> None:
|
|
755
|
+
nonlocal current_run_rpr, current_wrappers
|
|
756
|
+
if wrappers != current_wrappers or starts_new_run(rpr):
|
|
757
|
+
flush_run()
|
|
758
|
+
current_run_rpr = rpr
|
|
759
|
+
current_wrappers = wrappers
|
|
760
|
+
current_run_parts.append(part)
|
|
761
|
+
|
|
762
|
+
def emit_untouched(cc: _CharCoord) -> None:
|
|
763
|
+
nonlocal current_p_idx, current_ppr, current_shell_idx
|
|
764
|
+
if cc.is_para_break:
|
|
765
|
+
close_paragraph()
|
|
766
|
+
current_p_idx += 1
|
|
767
|
+
current_shell_idx = cc.para_idx + 1
|
|
768
|
+
if current_p_idx < len(decomposed):
|
|
769
|
+
current_ppr = copy.deepcopy(decomposed[current_p_idx][0])
|
|
770
|
+
elif not cc.protected:
|
|
771
|
+
append_to_run(cc.char if cc.element is None else cc.element, cc.rpr, cc.wrappers)
|
|
772
|
+
|
|
773
|
+
cursor = 0
|
|
774
|
+
opaque_idx = 0
|
|
775
|
+
|
|
776
|
+
def check_opaque_before(pos: int) -> None:
|
|
777
|
+
nonlocal opaque_idx
|
|
778
|
+
while opaque_idx < len(opaque_anchors) and opaque_anchors[opaque_idx][0] <= pos:
|
|
779
|
+
_, element, in_run, rpr, wrappers = opaque_anchors[opaque_idx]
|
|
780
|
+
if in_run and element is not None:
|
|
781
|
+
append_to_run(element, rpr, wrappers)
|
|
782
|
+
else:
|
|
783
|
+
flush_run()
|
|
784
|
+
append_child(copy.deepcopy(element), wrappers)
|
|
785
|
+
opaque_idx += 1
|
|
786
|
+
|
|
787
|
+
for s, e, repl_str, repl_rpr, touched_paras in replacements:
|
|
788
|
+
# Emit untouched slice before this match
|
|
789
|
+
while cursor < s:
|
|
790
|
+
check_opaque_before(cursor)
|
|
791
|
+
emit_untouched(char_coords[cursor])
|
|
792
|
+
cursor += 1
|
|
793
|
+
|
|
794
|
+
check_opaque_before(s)
|
|
795
|
+
repl_wrappers = (
|
|
796
|
+
char_coords[s].wrappers
|
|
797
|
+
if s < len(char_coords)
|
|
798
|
+
else char_coords[s - 1].wrappers
|
|
799
|
+
if s
|
|
800
|
+
else ()
|
|
801
|
+
)
|
|
802
|
+
|
|
803
|
+
# Handle boundary paragraph properties if match crossed paragraphs
|
|
804
|
+
if len(touched_paras) > 1:
|
|
805
|
+
first_p_idx = touched_paras[0]
|
|
806
|
+
last_p_idx = touched_paras[-1]
|
|
807
|
+
ppr_first = decomposed[first_p_idx][0]
|
|
808
|
+
ppr_last = decomposed[last_p_idx][0]
|
|
809
|
+
current_ppr = _apply_ppr_policy(ppr_first, ppr_last, options.paragraph_merge_policy)
|
|
810
|
+
if options.paragraph_merge_policy == "keep_last":
|
|
811
|
+
current_shell_idx = last_p_idx
|
|
812
|
+
|
|
813
|
+
# Emit replacement
|
|
814
|
+
if "\n" in repl_str:
|
|
815
|
+
lines = repl_str.split("\n")
|
|
816
|
+
for line_idx, line in enumerate(lines):
|
|
817
|
+
if line_idx > 0:
|
|
818
|
+
close_paragraph()
|
|
819
|
+
p_idx = touched_paras[-1] if touched_paras else current_p_idx
|
|
820
|
+
current_ppr = copy.deepcopy(decomposed[p_idx][0])
|
|
821
|
+
current_shell_idx = p_idx
|
|
822
|
+
if line:
|
|
823
|
+
flush_run()
|
|
824
|
+
append_child(
|
|
825
|
+
_make_run(_replacement_parts(line, ns), repl_rpr, ns), repl_wrappers
|
|
826
|
+
)
|
|
827
|
+
else:
|
|
828
|
+
if repl_str:
|
|
829
|
+
flush_run()
|
|
830
|
+
append_child(
|
|
831
|
+
_make_run(_replacement_parts(repl_str, ns), repl_rpr, ns), repl_wrappers
|
|
832
|
+
)
|
|
833
|
+
|
|
834
|
+
# Advance cursor past matched region
|
|
835
|
+
cursor = e
|
|
836
|
+
|
|
837
|
+
# Emit trailing untouched characters
|
|
838
|
+
while cursor < len(char_coords):
|
|
839
|
+
check_opaque_before(cursor)
|
|
840
|
+
emit_untouched(char_coords[cursor])
|
|
841
|
+
cursor += 1
|
|
842
|
+
|
|
843
|
+
# Remaining opaque elements at the end
|
|
844
|
+
check_opaque_before(len(char_coords))
|
|
845
|
+
close_paragraph()
|
|
846
|
+
|
|
847
|
+
return new_paragraphs
|
|
848
|
+
|
|
849
|
+
|
|
850
|
+
def _find_paragraph_containers(root: ET.Element, ns: str) -> Iterator[ET.Element]:
|
|
851
|
+
"""Visit live paragraph containers in document order, after ancestor splices."""
|
|
852
|
+
p_tag = _q("p", ns)
|
|
853
|
+
stack = [iter((root,))]
|
|
854
|
+
while stack:
|
|
855
|
+
elem = next(stack[-1], None)
|
|
856
|
+
if elem is None:
|
|
857
|
+
stack.pop()
|
|
858
|
+
continue
|
|
859
|
+
if any(child.tag == p_tag for child in elem):
|
|
860
|
+
yield elem
|
|
861
|
+
# Defer child traversal until the caller has rebuilt this container, so text
|
|
862
|
+
# boxes refer to the published host's drawing rather than a detached clone.
|
|
863
|
+
stack.append(iter(elem))
|
|
864
|
+
|
|
865
|
+
|
|
866
|
+
def _process_story_root(
|
|
867
|
+
root: ET.Element,
|
|
868
|
+
compiled_pattern: re.Pattern[str],
|
|
869
|
+
replacement: str | Callable[[re.Match[str]], str],
|
|
870
|
+
options: FindReplaceOptions,
|
|
871
|
+
ns: str,
|
|
872
|
+
part_name: str,
|
|
873
|
+
max_replacements: int | None,
|
|
874
|
+
discovery: bool = False,
|
|
875
|
+
) -> tuple[list[dict[str, Any]], int]:
|
|
876
|
+
"""Execute find and replace across all paragraph containers in one story root."""
|
|
877
|
+
containers = _find_paragraph_containers(root, ns)
|
|
878
|
+
p_tag = _q("p", ns)
|
|
879
|
+
|
|
880
|
+
total_matches: list[dict[str, Any]] = []
|
|
881
|
+
replacements_done = 0
|
|
882
|
+
|
|
883
|
+
for container in containers:
|
|
884
|
+
children = list(container)
|
|
885
|
+
groups: list[list[tuple[int, ET.Element]]] = []
|
|
886
|
+
current_group: list[tuple[int, ET.Element]] = []
|
|
887
|
+
|
|
888
|
+
for idx, child in enumerate(children):
|
|
889
|
+
if child.tag == p_tag:
|
|
890
|
+
current_group.append((idx, child))
|
|
891
|
+
else:
|
|
892
|
+
if current_group:
|
|
893
|
+
groups.append(current_group)
|
|
894
|
+
current_group = []
|
|
895
|
+
if current_group:
|
|
896
|
+
groups.append(current_group)
|
|
897
|
+
|
|
898
|
+
# Process groups in reverse order to preserve container slice indices
|
|
899
|
+
for grp in reversed(groups):
|
|
900
|
+
rem_budget = (
|
|
901
|
+
max_replacements - replacements_done if max_replacements is not None else None
|
|
902
|
+
)
|
|
903
|
+
if rem_budget is not None and rem_budget <= 0:
|
|
904
|
+
break
|
|
905
|
+
|
|
906
|
+
rebuilt, records, num_done = _process_paragraph_group(
|
|
907
|
+
grp,
|
|
908
|
+
compiled_pattern,
|
|
909
|
+
replacement,
|
|
910
|
+
options,
|
|
911
|
+
ns,
|
|
912
|
+
part_name,
|
|
913
|
+
rem_budget,
|
|
914
|
+
discovery,
|
|
915
|
+
)
|
|
916
|
+
# Splice from the back so earlier child indices stay valid.
|
|
917
|
+
for first_idx, last_idx, new_paras in reversed(rebuilt):
|
|
918
|
+
container[first_idx : last_idx + 1] = new_paras
|
|
919
|
+
total_matches.extend(records)
|
|
920
|
+
replacements_done += num_done
|
|
921
|
+
|
|
922
|
+
return total_matches, replacements_done
|
|
923
|
+
|
|
924
|
+
|
|
925
|
+
def _compile_pattern(pattern: str, options: FindReplaceOptions) -> re.Pattern[str] | None:
|
|
926
|
+
"""Compile ``pattern`` under ``options``, or ``None`` when it is not a valid regex."""
|
|
927
|
+
flags = 0
|
|
928
|
+
if options.ignore_case:
|
|
929
|
+
flags |= re.IGNORECASE
|
|
930
|
+
if options.multiline:
|
|
931
|
+
flags |= re.MULTILINE
|
|
932
|
+
if options.dotall:
|
|
933
|
+
flags |= re.DOTALL
|
|
934
|
+
try:
|
|
935
|
+
return re.compile(pattern, flags)
|
|
936
|
+
except re.error:
|
|
937
|
+
return None
|
|
938
|
+
|
|
939
|
+
|
|
940
|
+
def _replace_in_story(
|
|
941
|
+
root: ET.Element, compiled_pattern: re.Pattern[str], request: FindReplaceRequest
|
|
942
|
+
) -> tuple[list[dict[str, Any]], int, bytes]:
|
|
943
|
+
"""Rewrite ``request.part``'s editable tree in place and serialize it.
|
|
944
|
+
|
|
945
|
+
``root`` must be parsed with preserved qualified names. Returns the match records,
|
|
946
|
+
the replacement count, and the rewritten part bytes; a call that replaces nothing
|
|
947
|
+
leaves ``root`` untouched and returns empty bytes, which callers refuse with
|
|
948
|
+
``find_replace_no_match`` rather than publish.
|
|
949
|
+
"""
|
|
950
|
+
matches, count = _process_story_root(
|
|
951
|
+
root,
|
|
952
|
+
compiled_pattern,
|
|
953
|
+
request.replacement,
|
|
954
|
+
request.options,
|
|
955
|
+
_word_namespace(root),
|
|
956
|
+
request.part,
|
|
957
|
+
request.options.max_replacements,
|
|
958
|
+
)
|
|
959
|
+
if not count:
|
|
960
|
+
return matches, 0, b""
|
|
961
|
+
return matches, count, serialize_xml_with_preserved_qnames(root)
|
|
962
|
+
|
|
963
|
+
|
|
964
|
+
# ---------------------------------------------------------------------------
|
|
965
|
+
# Package Writing & Publication
|
|
966
|
+
# ---------------------------------------------------------------------------
|
|
967
|
+
|
|
968
|
+
|
|
969
|
+
def _write_package(
|
|
970
|
+
source: Path,
|
|
971
|
+
output: Path,
|
|
972
|
+
replacements: Mapping[str, bytes],
|
|
973
|
+
) -> None:
|
|
974
|
+
"""Write rewritten package, preserving every untouched part and entry byte-for-byte."""
|
|
975
|
+
with (
|
|
976
|
+
zipfile.ZipFile(source) as src_zip,
|
|
977
|
+
zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as dst_zip,
|
|
978
|
+
):
|
|
979
|
+
seen: set[str] = set()
|
|
980
|
+
for info in src_zip.infolist():
|
|
981
|
+
if info.filename in seen:
|
|
982
|
+
continue
|
|
983
|
+
seen.add(info.filename)
|
|
984
|
+
if info.filename in replacements:
|
|
985
|
+
dst_zip.writestr(info, replacements[info.filename])
|
|
986
|
+
else:
|
|
987
|
+
dst_zip.writestr(info, src_zip.read(info.filename))
|
|
988
|
+
|
|
989
|
+
|
|
990
|
+
# ---------------------------------------------------------------------------
|
|
991
|
+
# Public Functions
|
|
992
|
+
# ---------------------------------------------------------------------------
|
|
993
|
+
|
|
994
|
+
|
|
995
|
+
def discover_matches(
|
|
996
|
+
source: str | Path,
|
|
997
|
+
pattern: str,
|
|
998
|
+
*,
|
|
999
|
+
part: str = _DOCUMENT,
|
|
1000
|
+
options: FindReplaceOptions | Mapping[str, Any] | None = None,
|
|
1001
|
+
) -> dict[str, Any]:
|
|
1002
|
+
"""Read regex matches, including inline wrappers, revisions and field instructions."""
|
|
1003
|
+
src_path = Path(source).resolve()
|
|
1004
|
+
if not src_path.is_file():
|
|
1005
|
+
return {"passed": False, "code": "find_replace_source_missing"}
|
|
1006
|
+
|
|
1007
|
+
digest = _sha256(src_path)
|
|
1008
|
+
|
|
1009
|
+
if isinstance(options, FindReplaceOptions):
|
|
1010
|
+
opts = options
|
|
1011
|
+
elif isinstance(options, Mapping):
|
|
1012
|
+
opts = FindReplaceOptions(**options)
|
|
1013
|
+
else:
|
|
1014
|
+
opts = FindReplaceOptions()
|
|
1015
|
+
|
|
1016
|
+
compiled_pattern = _compile_pattern(pattern, opts)
|
|
1017
|
+
if compiled_pattern is None:
|
|
1018
|
+
return {
|
|
1019
|
+
"passed": False,
|
|
1020
|
+
"code": "find_replace_pattern_invalid",
|
|
1021
|
+
"source_sha256": digest,
|
|
1022
|
+
}
|
|
1023
|
+
|
|
1024
|
+
try:
|
|
1025
|
+
graph = PackageGraph.from_file(src_path)
|
|
1026
|
+
except (
|
|
1027
|
+
PackageError,
|
|
1028
|
+
PackageSafetyError,
|
|
1029
|
+
PackageFormatError,
|
|
1030
|
+
OSError,
|
|
1031
|
+
zipfile.BadZipFile,
|
|
1032
|
+
):
|
|
1033
|
+
return {
|
|
1034
|
+
"passed": False,
|
|
1035
|
+
"code": "source_package_invalid",
|
|
1036
|
+
"source_sha256": digest,
|
|
1037
|
+
}
|
|
1038
|
+
|
|
1039
|
+
if not graph.has_part(part):
|
|
1040
|
+
return {
|
|
1041
|
+
"passed": False,
|
|
1042
|
+
"code": "find_replace_part_unsupported",
|
|
1043
|
+
"source_sha256": digest,
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
try:
|
|
1047
|
+
root = ET.fromstring(graph.read_part_bytes(part))
|
|
1048
|
+
except (ET.ParseError, KeyError):
|
|
1049
|
+
return {
|
|
1050
|
+
"passed": False,
|
|
1051
|
+
"code": "source_package_invalid",
|
|
1052
|
+
"source_sha256": digest,
|
|
1053
|
+
}
|
|
1054
|
+
|
|
1055
|
+
ns = _word_namespace(root)
|
|
1056
|
+
# Perform discovery on a deep clone without persisting
|
|
1057
|
+
clone_root = copy.deepcopy(root)
|
|
1058
|
+
matches, _ = _process_story_root(
|
|
1059
|
+
clone_root,
|
|
1060
|
+
compiled_pattern,
|
|
1061
|
+
"",
|
|
1062
|
+
opts,
|
|
1063
|
+
ns,
|
|
1064
|
+
part,
|
|
1065
|
+
opts.max_replacements,
|
|
1066
|
+
discovery=True,
|
|
1067
|
+
)
|
|
1068
|
+
|
|
1069
|
+
return {
|
|
1070
|
+
"passed": True,
|
|
1071
|
+
"source_sha256": digest,
|
|
1072
|
+
"pattern": pattern,
|
|
1073
|
+
"part": part,
|
|
1074
|
+
"match_count": len(matches),
|
|
1075
|
+
"matches": matches,
|
|
1076
|
+
}
|
|
1077
|
+
|
|
1078
|
+
|
|
1079
|
+
def find_replace(request: FindReplaceRequest, *, verify: str = "full") -> FindReplaceReport:
|
|
1080
|
+
"""Execute atomic regex find and replace across runs and consecutive paragraphs.
|
|
1081
|
+
|
|
1082
|
+
Preserve hyperlink, SDT, customXml, smartTag and simple-field result wrappers.
|
|
1083
|
+
Matches touching revision text or field instructions refuse with
|
|
1084
|
+
``find_replace_protected_text``. Invalid replacement values or group references
|
|
1085
|
+
refuse with ``find_replace_replacement_invalid``; neither refusal publishes output.
|
|
1086
|
+
|
|
1087
|
+
A pattern that replaces nothing refuses with ``find_replace_no_match`` and publishes
|
|
1088
|
+
nothing, matching ``Document.find_replace``.
|
|
1089
|
+
|
|
1090
|
+
Both verification modes require every staged part other than ``request.part``
|
|
1091
|
+
(relationships included) to hash identically to the validated source.
|
|
1092
|
+
``verify="full"`` (the default) additionally inspects the whole staged package;
|
|
1093
|
+
``verify="changed-parts"`` re-parses only ``request.part`` under the package
|
|
1094
|
+
limits, relying on the source inspection for the byte-identical parts.
|
|
1095
|
+
"""
|
|
1096
|
+
if not isinstance(request, FindReplaceRequest):
|
|
1097
|
+
raise TypeError("find_replace_request_invalid")
|
|
1098
|
+
_require_verify_mode(verify)
|
|
1099
|
+
|
|
1100
|
+
source = request.source.resolve()
|
|
1101
|
+
destination = request.destination.resolve()
|
|
1102
|
+
|
|
1103
|
+
if not source.is_file():
|
|
1104
|
+
return _refusal(request.source_sha256, "find_replace_source_missing", destination)
|
|
1105
|
+
|
|
1106
|
+
current_hash = _sha256(source)
|
|
1107
|
+
if request.source_sha256 and current_hash != request.source_sha256:
|
|
1108
|
+
return _refusal(request.source_sha256, "source_hash_changed", destination)
|
|
1109
|
+
|
|
1110
|
+
if destination.exists() or destination.is_symlink():
|
|
1111
|
+
return _refusal(current_hash, "destination_exists", destination)
|
|
1112
|
+
|
|
1113
|
+
if destination == source or not destination.parent.is_dir():
|
|
1114
|
+
return _refusal(current_hash, "destination_invalid", destination)
|
|
1115
|
+
|
|
1116
|
+
compiled_pattern = _compile_pattern(request.pattern, request.options)
|
|
1117
|
+
if compiled_pattern is None:
|
|
1118
|
+
return _refusal(current_hash, "find_replace_pattern_invalid", destination)
|
|
1119
|
+
|
|
1120
|
+
# Open package graph and inspect
|
|
1121
|
+
try:
|
|
1122
|
+
graph = PackageGraph.from_file(source)
|
|
1123
|
+
except (
|
|
1124
|
+
PackageError,
|
|
1125
|
+
PackageSafetyError,
|
|
1126
|
+
PackageFormatError,
|
|
1127
|
+
OSError,
|
|
1128
|
+
zipfile.BadZipFile,
|
|
1129
|
+
):
|
|
1130
|
+
return _refusal(current_hash, "source_package_invalid", destination)
|
|
1131
|
+
|
|
1132
|
+
baseline = _inspect_docx(source)
|
|
1133
|
+
if not baseline.valid:
|
|
1134
|
+
return _refusal(current_hash, "source_package_invalid", destination)
|
|
1135
|
+
|
|
1136
|
+
if not graph.has_part(request.part):
|
|
1137
|
+
return _refusal(current_hash, "find_replace_part_unsupported", destination)
|
|
1138
|
+
|
|
1139
|
+
try:
|
|
1140
|
+
part_bytes = graph.read_part_bytes(request.part)
|
|
1141
|
+
root = parse_xml_with_preserved_qnames(part_bytes)
|
|
1142
|
+
except (ET.ParseError, KeyError):
|
|
1143
|
+
return _refusal(current_hash, "source_package_invalid", destination)
|
|
1144
|
+
|
|
1145
|
+
try:
|
|
1146
|
+
matches, count, new_part_bytes = _replace_in_story(root, compiled_pattern, request)
|
|
1147
|
+
except _FindReplaceValidationError as exc:
|
|
1148
|
+
return _refusal(current_hash, str(exc), destination)
|
|
1149
|
+
if not count:
|
|
1150
|
+
return _refusal(current_hash, "find_replace_no_match", destination)
|
|
1151
|
+
replacements = {request.part: new_part_bytes}
|
|
1152
|
+
|
|
1153
|
+
# Atomic stage and publish
|
|
1154
|
+
staged: Path | None = None
|
|
1155
|
+
try:
|
|
1156
|
+
with tempfile.NamedTemporaryFile(
|
|
1157
|
+
dir=destination.parent,
|
|
1158
|
+
prefix=f".{destination.name}.",
|
|
1159
|
+
suffix=".tmp",
|
|
1160
|
+
delete=False,
|
|
1161
|
+
) as tmp:
|
|
1162
|
+
staged = Path(tmp.name)
|
|
1163
|
+
|
|
1164
|
+
_write_package(source, staged, replacements)
|
|
1165
|
+
|
|
1166
|
+
# Staged verification: the whole package, or (changed-parts) only the edited
|
|
1167
|
+
# part. Either way every other part must be byte-identical to the validated
|
|
1168
|
+
# source, relationships and content types included.
|
|
1169
|
+
if baseline.file_sha256 != current_hash:
|
|
1170
|
+
staged_valid = False
|
|
1171
|
+
elif verify == "full":
|
|
1172
|
+
candidate = _inspect_docx(staged, reuse=baseline)
|
|
1173
|
+
staged_valid = candidate.valid and _unchanged_parts_identical(
|
|
1174
|
+
baseline.part_sha256,
|
|
1175
|
+
candidate.part_sha256,
|
|
1176
|
+
candidate.part_sha256.__getitem__,
|
|
1177
|
+
replacements,
|
|
1178
|
+
)
|
|
1179
|
+
else:
|
|
1180
|
+
staged_valid = _verify_changed_parts(baseline, staged, replacements) is not None
|
|
1181
|
+
if not staged_valid:
|
|
1182
|
+
return _refusal(current_hash, "find_replace_staged_verification_failed", destination)
|
|
1183
|
+
|
|
1184
|
+
# Source concurrent change verification
|
|
1185
|
+
if _sha256(source) != current_hash:
|
|
1186
|
+
return _refusal(current_hash, "source_hash_changed", destination)
|
|
1187
|
+
|
|
1188
|
+
# No-clobber publish: a destination created after the pre-check is preserved.
|
|
1189
|
+
linked = _link_no_clobber(
|
|
1190
|
+
staged,
|
|
1191
|
+
destination,
|
|
1192
|
+
exists_code="destination_exists",
|
|
1193
|
+
unavailable_code="find_replace_publication_unavailable",
|
|
1194
|
+
)
|
|
1195
|
+
if linked is not None:
|
|
1196
|
+
return _refusal(current_hash, linked, destination)
|
|
1197
|
+
|
|
1198
|
+
return FindReplaceReport(
|
|
1199
|
+
status="published",
|
|
1200
|
+
code=None,
|
|
1201
|
+
source_sha256=current_hash,
|
|
1202
|
+
destination=str(destination),
|
|
1203
|
+
match_count=len(matches),
|
|
1204
|
+
replacement_count=count,
|
|
1205
|
+
matches=matches,
|
|
1206
|
+
unselected_parts_preserved=True,
|
|
1207
|
+
)
|
|
1208
|
+
finally:
|
|
1209
|
+
if staged is not None:
|
|
1210
|
+
staged.unlink(missing_ok=True)
|