Add find and replace functionality for tracked changes in headers and footers

Author: FireMasterK

src/docx/document.py

@@ -222,19 +222,32 @@ def reject_all(self) -> None:
             change.reject()
 
     def find_and_replace_tracked(
-        self, search_text: str, replace_text: str, author: str = ""
+        self,
+        search_text: str,
+        replace_text: str,
+        author: str = "",
+        *,
+        include_headers_footers: bool = False,
     ) -> int:
-        """Find and replace in accepted-view text using tracked revisions."""
+        """Find and replace in accepted-view text using tracked revisions.
+
+        Replacement always operates on `Paragraph.accepted_text`, meaning inserted
+        text is searchable and deleted text is ignored.
+
+        When `include_headers_footers` is |True|, existing header and footer story
+        parts are included in the traversal. Linked header/footer definitions are not
+        materialized merely to support this search; only already-defined parts are
+        traversed.
+        """
         total_count = 0
-        for paragraph in self.paragraphs:
+        for paragraph in _iter_paragraphs_in_container(self._body):
             total_count += paragraph.replace_tracked(search_text, replace_text, author=author)
-        for table in self.tables:
-            for row in table.rows:
-                for cell in row.cells:
-                    for paragraph in cell.paragraphs:
-                        total_count += paragraph.replace_tracked(
-                            search_text, replace_text, author=author
-                        )
+        if include_headers_footers:
+            for header_footer in _iter_defined_header_footer_containers(self):
+                for paragraph in _iter_paragraphs_in_container(header_footer):
+                    total_count += paragraph.replace_tracked(
+                        search_text, replace_text, author=author
+                    )
         return total_count
 
     @property
@@ -318,3 +331,43 @@ def clear_content(self) -> _Body:
         """
         self._body.clear_content()
         return self
+
+
+def _iter_paragraphs_in_container(container: BlockItemContainer) -> Iterator[Paragraph]:
+    """Generate paragraphs in `container`, recursing into nested tables."""
+    yield from container.paragraphs
+
+    for table in container.tables:
+        yield from _iter_paragraphs_in_table(table)
+
+
+def _iter_paragraphs_in_table(table: Table) -> Iterator[Paragraph]:
+    """Generate paragraphs in `table`, recursing into nested tables in cells."""
+    for row in table.rows:
+        for cell in row.cells:
+            yield from _iter_paragraphs_in_container(cell)
+
+
+def _iter_defined_header_footer_containers(document: Document) -> Iterator[BlockItemContainer]:
+    """Generate each existing header/footer container once, without creating parts."""
+    seen_partnames: set[str] = set()
+
+    for section in document.sections:
+        for header_footer in (
+            section.header,
+            section.first_page_header,
+            section.even_page_header,
+            section.footer,
+            section.first_page_footer,
+            section.even_page_footer,
+        ):
+            if not header_footer._has_definition:  # pyright: ignore[reportPrivateUsage]
+                continue
+
+            definition = header_footer._definition  # pyright: ignore[reportPrivateUsage]
+            partname = str(definition.partname)
+            if partname in seen_partnames:
+                continue
+
+            seen_partnames.add(partname)
+            yield header_footer

tests/test_revisions.py

@@ -97,6 +97,65 @@ def it_can_find_and_replace_with_tracking(self):
         assert paragraph.accepted_text == "AlXYa"
         assert len(document.track_changes) == 2
 
+    def it_can_find_and_replace_with_tracking_in_nested_tables(self):
+        document = Document()
+        outer_table = document.add_table(rows=1, cols=1)
+        inner_table = outer_table.cell(0, 0).add_table(rows=1, cols=1)
+        paragraph = inner_table.cell(0, 0).paragraphs[0]
+        paragraph.text = "Alpha"
+
+        count = document.find_and_replace_tracked("ph", "XY", author="TestAuthor")
+
+        assert count == 1
+        assert paragraph.text == "Alpha"
+        assert paragraph.accepted_text == "AlXYa"
+
+    def it_does_not_search_headers_or_footers_unless_requested(self):
+        document = Document()
+        paragraph = document.sections[0].header.paragraphs[0]
+        paragraph.text = "Alpha"
+
+        count = document.find_and_replace_tracked("ph", "XY", author="TestAuthor")
+
+        assert count == 0
+        assert paragraph.text == "Alpha"
+        assert paragraph.accepted_text == "Alpha"
+
+    def it_can_optionally_find_and_replace_with_tracking_in_headers_and_footers(self):
+        document = Document()
+        header_paragraph = document.sections[0].header.paragraphs[0]
+        footer_paragraph = document.sections[0].footer.paragraphs[0]
+        header_paragraph.text = "Alpha"
+        footer_paragraph.text = "Graph"
+
+        count = document.find_and_replace_tracked(
+            "ph",
+            "XY",
+            author="TestAuthor",
+            include_headers_footers=True,
+        )
+
+        assert count == 2
+        assert header_paragraph.text == "Alpha"
+        assert header_paragraph.accepted_text == "AlXYa"
+        assert footer_paragraph.text == "Graph"
+        assert footer_paragraph.accepted_text == "GraXY"
+
+    def it_does_not_create_header_or_footer_parts_when_optionally_searching_them(self):
+        document = Document()
+        section = document.sections[0]
+        sectPr_xml_before = section._sectPr.xml  # pyright: ignore[reportPrivateUsage]
+
+        count = document.find_and_replace_tracked(
+            "ph",
+            "XY",
+            author="TestAuthor",
+            include_headers_footers=True,
+        )
+
+        assert count == 0
+        assert section._sectPr.xml == sectPr_xml_before  # pyright: ignore[reportPrivateUsage]
+
     def it_finds_matches_inside_existing_insertions(self):
         document = Document()
         paragraph = document.add_paragraph("Hello ")