feat: native support for tracked changes (w:ins in paragraph.text, w:delText in run.text)

Author: AI Assistant

src/docx/oxml/__init__.py

@@ -76,6 +76,7 @@
 register_element_cls("w:ptab", CT_PTab)
 register_element_cls("w:r", CT_R)
 register_element_cls("w:t", CT_Text)
+register_element_cls("w:delText", CT_Text)
 
 # ---------------------------------------------------------------------------
 # header/footer-related mappings

src/docx/oxml/text/paragraph.py

@@ -57,7 +57,7 @@ def clear_content(self):
     @property
     def inner_content_elements(self) -> List[CT_R | CT_Hyperlink]:
         """Run and hyperlink children of the `w:p` element, in document order."""
-        return self.xpath("./w:r | ./w:hyperlink")
+        return self.xpath("./w:r | ./w:hyperlink | ./w:ins/w:r")
 
     @property
     def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
@@ -99,7 +99,7 @@ def text(self):  # pyright: ignore[reportIncompatibleMethodOverride]
         Inner-content child elements like `w:r` and `w:hyperlink` are translated to
         their text equivalent.
         """
-        return "".join(e.text for e in self.xpath("w:r | w:hyperlink"))
+        return "".join(e.text for e in self.xpath("w:r | w:hyperlink | w:ins/w:r"))
 
     def _insert_pPr(self, pPr: CT_PPr) -> CT_PPr:
         self.insert(0, pPr)

src/docx/oxml/text/run.py

@@ -35,6 +35,7 @@ class CT_R(BaseOxmlElement):
     cr = ZeroOrMore("w:cr")
     drawing = ZeroOrMore("w:drawing")
     t = ZeroOrMore("w:t")
+    delText = ZeroOrMore("w:delText")
     tab = ZeroOrMore("w:tab")
 
     def add_t(self, text: str) -> CT_Text:
@@ -75,6 +76,7 @@ def iter_items() -> Iterator[str | CT_Drawing | CT_LastRenderedPageBreak]:
                 " | w:noBreakHyphen"
                 " | w:ptab"
                 " | w:t"
+                " | w:delText"
                 " | w:tab"
             ):
                 if isinstance(e, (CT_Drawing, CT_LastRenderedPageBreak)):
@@ -134,7 +136,7 @@ def text(self) -> str:
         equivalent.
         """
         return "".join(
-            str(e) for e in self.xpath("w:br | w:cr | w:noBreakHyphen | w:ptab | w:t | w:tab")
+            str(e) for e in self.xpath("w:br | w:cr | w:noBreakHyphen | w:ptab | w:t | w:delText | w:tab")
         )
 
     @text.setter

tests/test_tracked_changes_fix.py

@@ -0,0 +1,52 @@
+from docx.oxml import parse_xml
+from docx.text.paragraph import Paragraph
+from docx.text.run import Run
+
+class DescribeTrackedChanges:
+    def it_includes_insertions_in_paragraph_text(self):
+        """
+        paragraph.text includes text within <w:ins> tags.
+        """
+        xml = (
+            '<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml">'
+            '  <w:r><w:t>Start </w:t></w:r>'
+            '  <w:ins w:id="1" w:author="Me" w:date="2023-01-01T00:00:00Z">'
+            '    <w:r><w:t>Inserted</w:t></w:r>'
+            '  </w:ins>'
+            '  <w:r><w:t> End</w:t></w:r>'
+            '</w:p>'
+        )
+        p = Paragraph(parse_xml(xml), None)
+        # Expected: "Start Inserted End"
+        # Before Fix: "Start  End"
+        assert p.text == "Start Inserted End"
+
+    def it_excludes_deletions_in_paragraph_text(self):
+        """
+        paragraph.text still excludes text within <w:del> tags (standard behavior).
+        """
+        xml = (
+            '<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
+            '  <w:r><w:t>Start </w:t></w:r>'
+            '  <w:del w:id="2" w:author="Me" w:date="2023-01-01T00:00:00Z">'
+            '    <w:r><w:delText>Deleted</w:delText></w:r>'
+        '  </w:del>'
+        '  <w:r><w:t>End</w:t></w:r>'
+        '</w:p>'
+        )
+        p = Paragraph(parse_xml(xml), None)
+        assert p.text == "Start End"
+
+    def it_includes_deletion_text_in_run(self):
+        """
+        run.text includes <w:delText> content (e.g. for provenance extraction).
+        """
+        xml = (
+            '<w:r xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
+            '  <w:delText>Deleted Content</w:delText>'
+            '</w:r>'
+        )
+        r = Run(parse_xml(xml), None)
+        # Expected: "Deleted Content"
+        # Before Fix: ""
+        assert r.text == "Deleted Content"