wolfdocx 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. wolfdocx/__init__.py +25 -0
  2. wolfdocx/_cache_root.py +24 -0
  3. wolfdocx/_comment_threads.py +278 -0
  4. wolfdocx/_inspection_cache.py +374 -0
  5. wolfdocx/_version.py +3 -0
  6. wolfdocx/admission.py +163 -0
  7. wolfdocx/assembly.py +463 -0
  8. wolfdocx/authoring.py +2773 -0
  9. wolfdocx/canonical.py +267 -0
  10. wolfdocx/content.py +963 -0
  11. wolfdocx/document.py +215 -0
  12. wolfdocx/errors.py +169 -0
  13. wolfdocx/find_replace.py +1210 -0
  14. wolfdocx/formatting.py +3160 -0
  15. wolfdocx/inspect.py +3999 -0
  16. wolfdocx/model.py +1038 -0
  17. wolfdocx/numbering_authoring.py +1422 -0
  18. wolfdocx/output.py +13 -0
  19. wolfdocx/package.py +2313 -0
  20. wolfdocx/package_profile.py +128 -0
  21. wolfdocx/page_setup.py +2483 -0
  22. wolfdocx/paragraph_authoring.py +1842 -0
  23. wolfdocx/properties.py +2728 -0
  24. wolfdocx/protection.py +1909 -0
  25. wolfdocx/regions.py +1993 -0
  26. wolfdocx/render_warnings.py +106 -0
  27. wolfdocx/reporting.py +943 -0
  28. wolfdocx/review.py +2862 -0
  29. wolfdocx/run_text.py +117 -0
  30. wolfdocx/section_break.py +1810 -0
  31. wolfdocx/session_ops/__init__.py +45 -0
  32. wolfdocx/session_ops/_bridge.py +151 -0
  33. wolfdocx/session_ops/lists.py +104 -0
  34. wolfdocx/session_ops/paragraphs.py +39 -0
  35. wolfdocx/session_ops/rich_objects.py +2598 -0
  36. wolfdocx/session_ops/run_edits.py +70 -0
  37. wolfdocx/session_ops/runs.py +313 -0
  38. wolfdocx/session_ops/sections.py +109 -0
  39. wolfdocx/session_ops/styling.py +99 -0
  40. wolfdocx/session_ops/tables.py +247 -0
  41. wolfdocx/styles_authoring.py +2822 -0
  42. wolfdocx/table_cell_properties.py +1458 -0
  43. wolfdocx/table_column.py +1501 -0
  44. wolfdocx/table_delete.py +942 -0
  45. wolfdocx/table_insert.py +1114 -0
  46. wolfdocx/table_merge.py +1863 -0
  47. wolfdocx/table_properties.py +2429 -0
  48. wolfdocx/table_row_properties.py +1095 -0
  49. wolfdocx/table_structure.py +1044 -0
  50. wolfdocx/text_effects.py +1438 -0
  51. wolfdocx-0.1.0.dist-info/METADATA +127 -0
  52. wolfdocx-0.1.0.dist-info/RECORD +54 -0
  53. wolfdocx-0.1.0.dist-info/WHEEL +4 -0
  54. wolfdocx-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -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)