comments: add Document.add_comment()

Author: scanny

src/docx/document.py

@@ -5,17 +5,18 @@
 
 from __future__ import annotations
 
-from typing import IO, TYPE_CHECKING, Iterator, List
+from typing import IO, TYPE_CHECKING, Iterator, List, Sequence
 
 from docx.blkcntnr import BlockItemContainer
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
 from docx.section import Section, Sections
 from docx.shared import ElementProxy, Emu, Inches, Length
+from docx.text.run import Run
 
 if TYPE_CHECKING:
     import docx.types as t
-    from docx.comments import Comments
+    from docx.comments import Comment, Comments
     from docx.oxml.document import CT_Body, CT_Document
     from docx.parts.document import DocumentPart
     from docx.settings import Settings
@@ -37,6 +38,51 @@ def __init__(self, element: CT_Document, part: DocumentPart):
         self._part = part
         self.__body = None
 
+    def add_comment(
+        self, runs: Run | Sequence[Run], text: str, author: str = "", initials: str | None = ""
+    ) -> Comment:
+        """Add a comment to the document, anchored to the specified runs.
+
+        `runs` can be a single `Run` object or a non-empty sequence of `Run` objects. Only the
+        first and last run of a sequence are used, it's just more convenient to pass a whole
+        sequence when that's what you have handy, like `paragraph.runs` for example. When `runs`
+        contains a single `Run` object, that run serves as both the first and last run.
+
+        A comment can be anchored only on an even run boundary, meaning the text the comment
+        "references" must be a non-zero integer number of consecutive runs. The runs need not be
+        _contiguous_ per se, like the first can be in one paragraph and the last in the next
+        paragraph, but all runs between the first and the last will be included in the reference.
+
+        The comment reference range is delimited by placing a `w:commentRangeStart` element before
+        the first run and a `w:commentRangeEnd` element after the last run. This is why only the
+        first and last run are required and why a single run can serve as both first and last.
+        Word works out which text to highlight in the UI based on these range markers.
+
+        `text` allows the contents of a simple comment to be provided in the call, providing for
+        the common case where a comment is a single phrase or sentence without special formatting
+        such as bold or italics. More complex comments can be added using the returned `Comment`
+        object in much the same way as a `Document` or (table) `Cell` object, using methods like
+        `.add_paragraph()`, .add_run()`, etc.
+
+        The `author` and `initials` parameters allow that metadata to be set for the comment.
+        `author` is a required attribute on a comment and is the empty string by default.
+        `initials` is optional on a comment and may be omitted by passing |None|, but Word adds an
+        `initials` attribute by default and we follow that convention by using the empty string
+        when no `initials` argument is provided.
+        """
+        # -- normalize `runs` to a sequence of runs --
+        runs = [runs] if isinstance(runs, Run) else runs
+        first_run = runs[0]
+        last_run = runs[-1]
+
+        # -- Note that comments can only appear in the document part --
+        comment = self.comments.add_comment(text=text, author=author, initials=initials)
+
+        # -- let the first run orchestrate placement of the comment range start and end --
+        first_run.mark_comment_range(last_run, comment.comment_id)
+
+        return comment
+
     def add_heading(self, text: str = "", level: int = 1):
         """Return a heading paragraph newly added to the end of the document.
 

src/docx/oxml/shared.py

@@ -46,8 +46,7 @@ class CT_String(BaseOxmlElement):
 
     @classmethod
     def new(cls, nsptagname: str, val: str):
-        """Return a new ``CT_String`` element with tagname `nsptagname` and ``val``
-        attribute set to `val`."""
+        """A new `CT_String`` element with tagname `nsptagname` and `val` attribute set to `val`."""
         elm = cast(CT_String, OxmlElement(nsptagname))
         elm.val = val
         return elm

src/docx/oxml/xmlchemy.py

@@ -423,8 +423,7 @@ def _new_method_name(self):
 
 
 class Choice(_BaseChildElement):
-    """Defines a child element belonging to a group, only one of which may appear as a
-    child."""
+    """Defines a child element belonging to a group, only one of which may appear as a child."""
 
     @property
     def nsptagname(self):

src/docx/text/run.py

@@ -173,6 +173,13 @@ def iter_inner_content(self) -> Iterator[str | Drawing | RenderedPageBreak]:
             elif isinstance(item, CT_Drawing):  # pyright: ignore[reportUnnecessaryIsInstance]
                 yield Drawing(item, self)
 
+    def mark_comment_range(self, last_run: Run, comment_id: int) -> None:
+        """Mark the range of runs from this run to `last_run` (inclusive) as belonging to a comment.
+
+        `comment_id` identfies the comment that references this range.
+        """
+        raise NotImplementedError
+
     @property
     def style(self) -> CharacterStyle:
         """Read/write.

tests/test_document.py

@@ -9,7 +9,7 @@
 
 import pytest
 
-from docx.comments import Comments
+from docx.comments import Comment, Comments
 from docx.document import Document, _Body
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
@@ -39,6 +39,26 @@
 class DescribeDocument:
     """Unit-test suite for `docx.document.Document`."""
 
+    def it_can_add_a_comment(
+        self,
+        document_part_: Mock,
+        comments_prop_: Mock,
+        comments_: Mock,
+        comment_: Mock,
+        run_mark_comment_range_: Mock,
+    ):
+        comment_.comment_id = 42
+        comments_.add_comment.return_value = comment_
+        comments_prop_.return_value = comments_
+        document = Document(cast(CT_Document, element("w:document/w:body/w:p/w:r")), document_part_)
+        run = document.paragraphs[0].runs[0]
+
+        comment = document.add_comment(run, "Comment text.")
+
+        comments_.add_comment.assert_called_once_with("Comment text.", "", "")
+        run_mark_comment_range_.assert_called_once_with(run, run, 42)
+        assert comment is comment_
+
     @pytest.mark.parametrize(
         ("level", "style"), [(0, "Title"), (1, "Heading 1"), (2, "Heading 2"), (9, "Heading 9")]
     )
@@ -288,10 +308,18 @@ def _block_width_prop_(self, request: FixtureRequest):
     def body_prop_(self, request: FixtureRequest):
         return property_mock(request, Document, "_body")
 
+    @pytest.fixture
+    def comment_(self, request: FixtureRequest):
+        return instance_mock(request, Comment)
+
     @pytest.fixture
     def comments_(self, request: FixtureRequest):
         return instance_mock(request, Comments)
 
+    @pytest.fixture
+    def comments_prop_(self, request: FixtureRequest):
+        return property_mock(request, Document, "comments")
+
     @pytest.fixture
     def core_properties_(self, request: FixtureRequest):
         return instance_mock(request, CoreProperties)
@@ -325,6 +353,10 @@ def picture_(self, request: FixtureRequest):
     def run_(self, request: FixtureRequest):
         return instance_mock(request, Run)
 
+    @pytest.fixture
+    def run_mark_comment_range_(self, request: FixtureRequest):
+        return method_mock(request, Run, "mark_comment_range")
+
     @pytest.fixture
     def Section_(self, request: FixtureRequest):
         return class_mock(request, "docx.document.Section")