comments: add Comments.get()

scanny · scanny · commit e2aec420ba2d · 2025-06-16T14:24:39.000-07:00
To get a comment by id, None when not found.
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -29,6 +29,11 @@ def __len__(self) -> int:
         """The number of comments in this collection."""
         return len(self._comments_elm.comment_lst)
 
+    def get(self, comment_id: int) -> Comment | None:
+        """Return the comment identified by `comment_id`, or |None| if not found."""
+        comment_elm = self._comments_elm.get_comment_by_id(comment_id)
+        return Comment(comment_elm, self._comments_part) if comment_elm is not None else None
+
 
 class Comment(BlockItemContainer):
     """Proxy for a single comment in the document.
diff --git a/src/docx/oxml/comments.py b/src/docx/oxml/comments.py
@@ -19,6 +19,11 @@ class CT_Comments(BaseOxmlElement):
 
     comment = ZeroOrMore("w:comment")
 
+    def get_comment_by_id(self, comment_id: int) -> CT_Comment | None:
+        """Return the `w:comment` element identified by `comment_id`, or |None| if not found."""
+        comment_elms = self.xpath(f"(./w:comment[@w:id='{comment_id}'])[1]")
+        return comment_elms[0] if comment_elms else None
+
 
 class CT_Comment(BaseOxmlElement):
     """`w:comment` element, representing a single comment.
diff --git a/tests/test_comments.py b/tests/test_comments.py
@@ -1,3 +1,5 @@
+# pyright: reportPrivateUsage=false
+
 """Unit test suite for the docx.comments module."""
 
 from __future__ import annotations
@@ -63,6 +65,26 @@ def it_is_iterable_over_the_comments_it_contains(self, package_: Mock):
         with pytest.raises(StopIteration):
             next(comment_iter)
 
+    def it_can_get_a_comment_by_id(self, package_: Mock):
+        comments_elm = cast(
+            CT_Comments,
+            element("w:comments/(w:comment{w:id=1},w:comment{w:id=2},w:comment{w:id=3})"),
+        )
+        comments = Comments(
+            comments_elm,
+            CommentsPart(
+                PackURI("/word/comments.xml"),
+                CT.WML_COMMENTS,
+                comments_elm,
+                package_,
+            ),
+        )
+
+        comment = comments.get(2)
+
+        assert type(comment) is Comment, "expected a `Comment` object"
+        assert comment._comment_elm is comments_elm.comment_lst[1]
+
     # -- fixtures --------------------------------------------------------------------------------
 
     @pytest.fixture
