comments: add DocumentPart.comments

scanny · scanny · commit 8f184cc41811 · 2025-06-16T14:24:39.000-07:00
Provide a way to get a `Comments` object from the `DocumentPart`.
diff --git a/src/docx/parts/comments.py b/src/docx/parts/comments.py
@@ -0,0 +1,15 @@
+"""Contains comments added to the document."""
+
+from __future__ import annotations
+
+from docx.comments import Comments
+from docx.parts.story import StoryPart
+
+
+class CommentsPart(StoryPart):
+    """Container part for comments added to the document."""
+
+    @property
+    def comments(self) -> Comments:
+        """A |Comments| proxy object for the `w:comments` root element of this part."""
+        raise NotImplementedError
diff --git a/src/docx/parts/document.py b/src/docx/parts/document.py
@@ -6,6 +6,7 @@
 
 from docx.document import Document
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.parts.comments import CommentsPart
 from docx.parts.hdrftr import FooterPart, HeaderPart
 from docx.parts.numbering import NumberingPart
 from docx.parts.settings import SettingsPart
@@ -46,7 +47,7 @@ def add_header_part(self):
     @property
     def comments(self) -> Comments:
         """|Comments| object providing access to the comments added to this document."""
-        raise NotImplementedError
+        return self._comments_part.comments
 
     @property
     def core_properties(self) -> CoreProperties:
@@ -124,6 +125,14 @@ def styles(self):
         document."""
         return self._styles_part.styles
 
+    @property
+    def _comments_part(self) -> CommentsPart:
+        """A |CommentsPart| object providing access to the comments added to this document.
+
+        Creates a default comments part if one is not present.
+        """
+        raise NotImplementedError
+
     @property
     def _settings_part(self) -> SettingsPart:
         """A |SettingsPart| object providing access to the document-level settings for
diff --git a/tests/parts/test_document.py b/tests/parts/test_document.py
@@ -4,12 +4,14 @@
 
 import pytest
 
+from docx.comments import Comments
 from docx.enum.style import WD_STYLE_TYPE
 from docx.opc.constants import CONTENT_TYPE as CT
 from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.coreprops import CoreProperties
 from docx.opc.packuri import PackURI
 from docx.package import Package
+from docx.parts.comments import CommentsPart
 from docx.parts.document import DocumentPart
 from docx.parts.hdrftr import FooterPart, HeaderPart
 from docx.parts.numbering import NumberingPart
@@ -109,6 +111,17 @@ def it_can_save_the_package_to_a_file(self, package_: Mock):
 
         package_.save.assert_called_once_with("foobar.docx")
 
+    def it_provides_access_to_the_comments_added_to_the_document(
+        self, _comments_part_prop_: Mock, comments_part_: Mock, comments_: Mock, package_: Mock
+    ):
+        comments_part_.comments = comments_
+        _comments_part_prop_.return_value = comments_part_
+        document_part = DocumentPart(
+            PackURI("/word/document.xml"), CT.WML_DOCUMENT, element("w:document"), package_
+        )
+
+        assert document_part.comments is comments_
+
     def it_provides_access_to_the_document_settings(
         self, _settings_part_prop_: Mock, settings_part_: Mock, settings_: Mock, package_: Mock
     ):
@@ -282,6 +295,22 @@ def and_it_creates_a_default_styles_part_if_not_present(
 
     # -- fixtures --------------------------------------------------------------------------------
 
+    @pytest.fixture
+    def comments_(self, request: FixtureRequest) -> Mock:
+        return instance_mock(request, Comments)
+
+    @pytest.fixture
+    def CommentsPart_(self, request: FixtureRequest) -> Mock:
+        return class_mock(request, "docx.parts.document.CommentsPart")
+
+    @pytest.fixture
+    def comments_part_(self, request: FixtureRequest) -> Mock:
+        return instance_mock(request, CommentsPart)
+
+    @pytest.fixture
+    def _comments_part_prop_(self, request: FixtureRequest) -> Mock:
+        return property_mock(request, DocumentPart, "_comments_part")
+
     @pytest.fixture
     def core_properties_(self, request: FixtureRequest):
         return instance_mock(request, CoreProperties)
