comments: add Comment.comment_id

scanny · scanny · commit 0eeaa2f0760b · 2025-06-16T14:24:39.000-07:00
diff --git a/features/doc-comments.feature b/features/doc-comments.feature
@@ -30,7 +30,6 @@ Feature: Document.comments
      Then iterating comments yields 4 Comment objects
 
 
-  @wip
   Scenario: Comments.get()
     Given a Comments object with 4 comments
      When I call comments.get(2)
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -52,3 +52,8 @@ class Comment(BlockItemContainer):
     def __init__(self, comment_elm: CT_Comment, comments_part: CommentsPart):
         super().__init__(comment_elm, comments_part)
         self._comment_elm = comment_elm
+
+    @property
+    def comment_id(self) -> int:
+        """The unique identifier of this comment."""
+        return self._comment_elm.id
diff --git a/src/docx/oxml/comments.py b/src/docx/oxml/comments.py
@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from docx.oxml.xmlchemy import BaseOxmlElement, ZeroOrMore
+from docx.oxml.simpletypes import ST_DecimalNumber
+from docx.oxml.xmlchemy import BaseOxmlElement, RequiredAttribute, ZeroOrMore
 
 
 class CT_Comments(BaseOxmlElement):
@@ -32,3 +33,5 @@ class CT_Comment(BaseOxmlElement):
     While probably most often used for a single sentence or phrase, a comment can contain rich
     content, including multiple rich-text paragraphs, hyperlinks, images, and tables.
     """
+
+    id: int = RequiredAttribute("w:id", ST_DecimalNumber)  # pyright: ignore[reportAssignmentType]
diff --git a/tests/test_comments.py b/tests/test_comments.py
@@ -11,7 +11,7 @@
 from docx.comments import Comment, Comments
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.packuri import PackURI
-from docx.oxml.comments import CT_Comments
+from docx.oxml.comments import CT_Comment, CT_Comments
 from docx.package import Package
 from docx.parts.comments import CommentsPart
 
@@ -90,3 +90,19 @@ def it_can_get_a_comment_by_id(self, package_: Mock):
     @pytest.fixture
     def package_(self, request: FixtureRequest):
         return instance_mock(request, Package)
+
+
+class DescribeComment:
+    """Unit-test suite for `docx.comments.Comment`."""
+
+    def it_knows_its_comment_id(self, comments_part_: Mock):
+        comment_elm = cast(CT_Comment, element("w:comment{w:id=42}"))
+        comment = Comment(comment_elm, comments_part_)
+
+        assert comment.comment_id == 42
+
+    # -- fixtures --------------------------------------------------------------------------------
+
+    @pytest.fixture
+    def comments_part_(self, request: FixtureRequest):
+        return instance_mock(request, CommentsPart)
