comments: add Comment.paragraphs

scanny · scanny · commit 19175adf57d9 · 2025-06-16T14:24:39.000-07:00
Actual implementation is primarily inherited from `BlockItemContainer`,
but support for those operations must be present in `CT_Comment` and
it's worth testing explicitly.
diff --git a/features/cmt-props.feature b/features/cmt-props.feature
@@ -24,7 +24,6 @@ Feature: Get comment properties
      Then comment.timestamp is the date and time the comment was authored
 
 
-  @wip
   Scenario: Comment.paragraphs[0].text
     Given a Comment object
      When I assign para_text = comment.paragraphs[0].text
diff --git a/src/docx/oxml/comments.py b/src/docx/oxml/comments.py
@@ -3,10 +3,15 @@
 from __future__ import annotations
 
 import datetime as dt
+from typing import TYPE_CHECKING, Callable
 
 from docx.oxml.simpletypes import ST_DateTime, ST_DecimalNumber, ST_String
 from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, RequiredAttribute, ZeroOrMore
 
+if TYPE_CHECKING:
+    from docx.oxml.table import CT_Tbl
+    from docx.oxml.text.paragraph import CT_P
+
 
 class CT_Comments(BaseOxmlElement):
     """`w:comments` element, the root element for the comments part.
@@ -36,6 +41,7 @@ class CT_Comment(BaseOxmlElement):
     content, including multiple rich-text paragraphs, hyperlinks, images, and tables.
     """
 
+    # -- attributes on `w:comment` --
     id: int = RequiredAttribute("w:id", ST_DecimalNumber)  # pyright: ignore[reportAssignmentType]
     author: str = RequiredAttribute("w:author", ST_String)  # pyright: ignore[reportAssignmentType]
     initials: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
@@ -44,3 +50,20 @@ class CT_Comment(BaseOxmlElement):
     date: dt.datetime | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "w:date", ST_DateTime
     )
+
+    # -- children --
+
+    p = ZeroOrMore("w:p", successors=())
+    tbl = ZeroOrMore("w:tbl", successors=())
+
+    # -- type-declarations for methods added by metaclass --
+
+    add_p: Callable[[], CT_P]
+    p_lst: list[CT_P]
+    tbl_lst: list[CT_Tbl]
+    _insert_tbl: Callable[[CT_Tbl], CT_Tbl]
+
+    @property
+    def inner_content_elements(self) -> list[CT_P | CT_Tbl]:
+        """Generate all `w:p` and `w:tbl` elements in this comment."""
+        return self.xpath("./w:p | ./w:tbl")
diff --git a/tests/test_comments.py b/tests/test_comments.py
@@ -123,6 +123,18 @@ def it_knows_the_date_and_time_it_was_authored(self, comments_part_: Mock):
 
         assert comment.timestamp == dt.datetime(2023, 10, 1, 12, 34, 56, tzinfo=dt.timezone.utc)
 
+    def it_provides_access_to_the_paragraphs_it_contains(self, comments_part_: Mock):
+        comment_elm = cast(
+            CT_Comment,
+            element('w:comment{w:id=42}/(w:p/w:r/w:t"First para",w:p/w:r/w:t"Second para")'),
+        )
+        comment = Comment(comment_elm, comments_part_)
+
+        paragraphs = comment.paragraphs
+
+        assert len(paragraphs) == 2
+        assert [para.text for para in paragraphs] == ["First para", "Second para"]
+
     # -- fixtures --------------------------------------------------------------------------------
 
     @pytest.fixture
