comments: add Comment.initials

scanny · scanny · commit cab50c5e65da · 2025-06-16T14:24:39.000-07:00
diff --git a/features/cmt-props.feature b/features/cmt-props.feature
@@ -14,7 +14,6 @@ Feature: Get comment properties
      Then comment.author is the author of the comment
 
 
-  @wip
   Scenario: Comment.initials
     Given a Comment object
      Then comment.initials is the initials of the comment author
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -62,3 +62,12 @@ def author(self) -> str:
     def comment_id(self) -> int:
         """The unique identifier of this comment."""
         return self._comment_elm.id
+
+    @property
+    def initials(self) -> str | None:
+        """Read/write. The recorded initials of the comment author.
+
+        This attribute is optional in the XML, returns |None| if not set. Assigning |None| removes
+        any existing initials from the XML.
+        """
+        return self._comment_elm.initials
diff --git a/src/docx/oxml/comments.py b/src/docx/oxml/comments.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from docx.oxml.simpletypes import ST_DecimalNumber, ST_String
-from docx.oxml.xmlchemy import BaseOxmlElement, RequiredAttribute, ZeroOrMore
+from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, RequiredAttribute, ZeroOrMore
 
 
 class CT_Comments(BaseOxmlElement):
@@ -36,3 +36,6 @@ class CT_Comment(BaseOxmlElement):
 
     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]
+        "w:initials", ST_String
+    )
diff --git a/tests/test_comments.py b/tests/test_comments.py
@@ -107,6 +107,12 @@ def it_knows_its_author(self, comments_part_: Mock):
 
         assert comment.author == "Steve Canny"
 
+    def it_knows_the_initials_of_its_author(self, comments_part_: Mock):
+        comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:initials=SJC}"))
+        comment = Comment(comment_elm, comments_part_)
+
+        assert comment.initials == "SJC"
+
     # -- fixtures --------------------------------------------------------------------------------
 
     @pytest.fixture
