comments: add Run.mark_comment_range()

scanny · scanny · commit e3a321d26195 · 2025-06-16T14:24:39.000-07:00
diff --git a/src/docx/oxml/text/run.py b/src/docx/oxml/text/run.py
@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Callable, Iterator, List
+from typing import TYPE_CHECKING, Callable, Iterator, List, cast
 
 from docx.oxml.drawing import CT_Drawing
 from docx.oxml.ns import qn
+from docx.oxml.parser import OxmlElement
 from docx.oxml.simpletypes import ST_BrClear, ST_BrType
 from docx.oxml.text.font import CT_RPr
 from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, ZeroOrMore, ZeroOrOne
@@ -87,6 +88,19 @@ def iter_items() -> Iterator[str | CT_Drawing | CT_LastRenderedPageBreak]:
 
         return list(iter_items())
 
+    def insert_comment_range_end_and_reference_below(self, comment_id: int) -> None:
+        """Insert a `w:commentRangeEnd` and `w:commentReference` element after this run.
+
+        The `w:commentRangeEnd` element is the immediate sibling of this `w:r` and is followed by
+        a `w:r` containing the `w:commentReference` element.
+        """
+        self.addnext(self._new_comment_reference_run(comment_id))
+        self.addnext(OxmlElement("w:commentRangeEnd", attrs={qn("w:id"): str(comment_id)}))
+
+    def insert_comment_range_start_above(self, comment_id: int) -> None:
+        """Insert a `w:commentRangeStart` element with `comment_id` before this run."""
+        self.addprevious(OxmlElement("w:commentRangeStart", attrs={qn("w:id"): str(comment_id)}))
+
     @property
     def lastRenderedPageBreaks(self) -> List[CT_LastRenderedPageBreak]:
         """All `w:lastRenderedPageBreaks` descendants of this run."""
@@ -132,6 +146,23 @@ def _insert_rPr(self, rPr: CT_RPr) -> CT_RPr:
         self.insert(0, rPr)
         return rPr
 
+    def _new_comment_reference_run(self, comment_id: int) -> CT_R:
+        """Return a new `w:r` element with `w:commentReference` referencing `comment_id`.
+
+        Should look like this:
+
+            <w:r>
+              <w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
+              <w:commentReference w:id="0"/>
+            </w:r>
+
+        """
+        r = cast(CT_R, OxmlElement("w:r"))
+        rPr = r.get_or_add_rPr()
+        rPr.style = "CommentReference"
+        r.append(OxmlElement("w:commentReference", attrs={qn("w:id"): str(comment_id)}))
+        return r
+
 
 # ------------------------------------------------------------------------------------
 # Run inner-content elements
diff --git a/src/docx/text/run.py b/src/docx/text/run.py
@@ -178,7 +178,12 @@ def mark_comment_range(self, last_run: Run, comment_id: int) -> None:
 
         `comment_id` identfies the comment that references this range.
         """
-        raise NotImplementedError
+        # -- insert `w:commentRangeStart` with `comment_id` before this (first) run --
+        self._r.insert_comment_range_start_above(comment_id)
+
+        # -- insert `w:commentRangeEnd` and `w:commentReference` run with `comment_id` after
+        # -- `last_run`
+        last_run._r.insert_comment_range_end_and_reference_below(comment_id)
 
     @property
     def style(self) -> CharacterStyle:
diff --git a/tests/text/test_run.py b/tests/text/test_run.py
@@ -11,6 +11,7 @@
 from docx import types as t
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_BREAK, WD_UNDERLINE
+from docx.oxml.text.paragraph import CT_P
 from docx.oxml.text.run import CT_R
 from docx.parts.document import DocumentPart
 from docx.shape import InlineShape
@@ -122,6 +123,18 @@ def it_can_iterate_its_inner_content_items(
         actual = [type(item).__name__ for item in inner_content]
         assert actual == expected, f"expected: {expected}, got: {actual}"
 
+    def it_can_mark_a_comment_reference_range(self, paragraph_: Mock):
+        p = cast(CT_P, element('w:p/w:r/w:t"referenced text"'))
+        run = last_run = Run(p.r_lst[0], paragraph_)
+
+        run.mark_comment_range(last_run, comment_id=42)
+
+        assert p.xml == xml(
+            'w:p/(w:commentRangeStart{w:id=42},w:r/w:t"referenced text"'
+            ",w:commentRangeEnd{w:id=42}"
+            ",w:r/(w:rPr/w:rStyle{w:val=CommentReference},w:commentReference{w:id=42}))"
+        )
+
     def it_knows_its_character_style(
         self, part_prop_: Mock, document_part_: Mock, paragraph_: Mock
     ):
