comments: add CommentsPart.comments

scanny · scanny · commit 9c8a2e91fa74 · 2025-06-16T14:24:39.000-07:00
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -2,12 +2,22 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from docx.blkcntnr import BlockItemContainer
 
+if TYPE_CHECKING:
+    from docx.oxml.comments import CT_Comments
+    from docx.parts.comments import CommentsPart
+
 
 class Comments:
     """Collection containing the comments added to this document."""
 
+    def __init__(self, comments_elm: CT_Comments, comments_part: CommentsPart):
+        self._comments_elm = comments_elm
+        self._comments_part = comments_part
+
 
 class Comment(BlockItemContainer):
     """Proxy for a single comment in the document.
diff --git a/src/docx/parts/comments.py b/src/docx/parts/comments.py
@@ -19,10 +19,16 @@
 class CommentsPart(StoryPart):
     """Container part for comments added to the document."""
 
+    def __init__(
+        self, partname: PackURI, content_type: str, element: CT_Comments, package: Package
+    ):
+        super().__init__(partname, content_type, element, package)
+        self._comments = element
+
     @property
     def comments(self) -> Comments:
         """A |Comments| proxy object for the `w:comments` root element of this part."""
-        raise NotImplementedError
+        return Comments(self._comments, self)
 
     @classmethod
     def default(cls, package: Package) -> Self:
diff --git a/tests/parts/test_comments.py b/tests/parts/test_comments.py
@@ -2,14 +2,38 @@
 
 from __future__ import annotations
 
+from typing import cast
+
+import pytest
+
+from docx.comments import 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.package import Package
 from docx.parts.comments import CommentsPart
 
+from ..unitutil.cxml import element
+from ..unitutil.mock import FixtureRequest, Mock, class_mock, instance_mock
+
 
 class DescribeCommentsPart:
     """Unit test suite for `docx.parts.comments.CommentsPart` objects."""
 
+    def it_provides_access_to_its_comments_collection(
+        self, Comments_: Mock, comments_: Mock, package_: Mock
+    ):
+        Comments_.return_value = comments_
+        comments_elm = cast(CT_Comments, element("w:comments"))
+        comments_part = CommentsPart(
+            PackURI("/word/comments.xml"), CT.WML_COMMENTS, comments_elm, package_
+        )
+
+        comments = comments_part.comments
+
+        Comments_.assert_called_once_with(comments_part.element, comments_part)
+        assert comments is comments_
+
     def it_constructs_a_default_comments_part_to_help(self):
         package = Package()
 
@@ -23,3 +47,17 @@ def it_constructs_a_default_comments_part_to_help(self):
             "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}comments"
         )
         assert len(comments_part.element) == 0
+
+    # -- fixtures --------------------------------------------------------------------------------
+
+    @pytest.fixture
+    def Comments_(self, request: FixtureRequest) -> Mock:
+        return class_mock(request, "docx.parts.comments.Comments")
+
+    @pytest.fixture
+    def comments_(self, request: FixtureRequest) -> Mock:
+        return instance_mock(request, Comments)
+
+    @pytest.fixture
+    def package_(self, request: FixtureRequest) -> Mock:
+        return instance_mock(request, Package)
