comments: add Comments.__iter__()

scanny · scanny · commit 88ff3cab593b · 2025-06-16T14:24:39.000-07:00
diff --git a/features/doc-comments.feature b/features/doc-comments.feature
@@ -25,7 +25,6 @@ Feature: Document.comments
       | 4    |
 
 
-  @wip
   Scenario: Comments.__iter__()
     Given a Comments object with 4 comments
      Then iterating comments yields 4 Comment objects
diff --git a/src/docx/blkcntnr.py b/src/docx/blkcntnr.py
@@ -19,14 +19,15 @@
 
 if TYPE_CHECKING:
     import docx.types as t
+    from docx.oxml.comments import CT_Comment
     from docx.oxml.document import CT_Body
     from docx.oxml.section import CT_HdrFtr
     from docx.oxml.table import CT_Tc
     from docx.shared import Length
     from docx.styles.style import ParagraphStyle
     from docx.table import Table
 
-BlockItemElement: TypeAlias = "CT_Body | CT_HdrFtr | CT_Tc"
+BlockItemElement: TypeAlias = "CT_Body | CT_Comment | CT_HdrFtr | CT_Tc"
 
 
 class BlockItemContainer(StoryChild):
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Iterator
 
 from docx.blkcntnr import BlockItemContainer
 
 if TYPE_CHECKING:
-    from docx.oxml.comments import CT_Comments
+    from docx.oxml.comments import CT_Comment, CT_Comments
     from docx.parts.comments import CommentsPart
 
 
@@ -18,6 +18,13 @@ def __init__(self, comments_elm: CT_Comments, comments_part: CommentsPart):
         self._comments_elm = comments_elm
         self._comments_part = comments_part
 
+    def __iter__(self) -> Iterator[Comment]:
+        """Iterator over the comments in this collection."""
+        return (
+            Comment(comment_elm, self._comments_part)
+            for comment_elm in self._comments_elm.comment_lst
+        )
+
     def __len__(self) -> int:
         """The number of comments in this collection."""
         return len(self._comments_elm.comment_lst)
@@ -36,3 +43,7 @@ class Comment(BlockItemContainer):
     Note that certain content like tables may not be displayed in the Word comment sidebar due to
     space limitations. Such "over-sized" content can still be viewed in the review pane.
     """
+
+    def __init__(self, comment_elm: CT_Comment, comments_part: CommentsPart):
+        super().__init__(comment_elm, comments_part)
+        self._comment_elm = comment_elm
diff --git a/tests/test_comments.py b/tests/test_comments.py
@@ -6,7 +6,7 @@
 
 import pytest
 
-from docx.comments import Comments
+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
@@ -42,6 +42,27 @@ def it_knows_how_many_comments_it_contains(self, cxml: str, count: int, package_
 
         assert len(comments) == count
 
+    def it_is_iterable_over_the_comments_it_contains(self, package_: Mock):
+        comments_elm = cast(CT_Comments, element("w:comments/(w:comment,w:comment)"))
+        comments = Comments(
+            comments_elm,
+            CommentsPart(
+                PackURI("/word/comments.xml"),
+                CT.WML_COMMENTS,
+                comments_elm,
+                package_,
+            ),
+        )
+
+        comment_iter = iter(comments)
+
+        comment1 = next(comment_iter)
+        assert type(comment1) is Comment, "expected a `Comment` object"
+        comment2 = next(comment_iter)
+        assert type(comment2) is Comment, "expected a `Comment` object"
+        with pytest.raises(StopIteration):
+            next(comment_iter)
+
     # -- fixtures --------------------------------------------------------------------------------
 
     @pytest.fixture
