comments: add Document.comments

scanny · scanny · commit 451747a944fe · 2025-06-16T14:24:39.000-07:00
Provides access to the comments collection from the document object.
diff --git a/docs/conf.py b/docs/conf.py
@@ -83,6 +83,8 @@
 
 .. |CharacterStyle| replace:: :class:`.CharacterStyle`
 
+.. |Comments| replace:: :class:`.Comments`
+
 .. |Cm| replace:: :class:`.Cm`
 
 .. |ColorFormat| replace:: :class:`.ColorFormat`
diff --git a/src/docx/document.py b/src/docx/document.py
@@ -15,6 +15,7 @@
 
 if TYPE_CHECKING:
     import docx.types as t
+    from docx.comments import Comments
     from docx.oxml.document import CT_Body, CT_Document
     from docx.parts.document import DocumentPart
     from docx.settings import Settings
@@ -106,6 +107,11 @@ def add_table(self, rows: int, cols: int, style: str | _TableStyle | None = None
         table.style = style
         return table
 
+    @property
+    def comments(self) -> Comments:
+        """A |Comments| object providing access to comments added to the document."""
+        return self._part.comments
+
     @property
     def core_properties(self):
         """A |CoreProperties| object providing Dublin Core properties of document."""
diff --git a/src/docx/parts/document.py b/src/docx/parts/document.py
@@ -15,6 +15,7 @@
 from docx.shared import lazyproperty
 
 if TYPE_CHECKING:
+    from docx.comments import Comments
     from docx.enum.style import WD_STYLE_TYPE
     from docx.opc.coreprops import CoreProperties
     from docx.settings import Settings
@@ -42,6 +43,11 @@ def add_header_part(self):
         rId = self.relate_to(header_part, RT.HEADER)
         return header_part, rId
 
+    @property
+    def comments(self) -> Comments:
+        """|Comments| object providing access to the comments added to this document."""
+        raise NotImplementedError
+
     @property
     def core_properties(self) -> CoreProperties:
         """A |CoreProperties| object providing read/write access to the core properties
diff --git a/tests/test_document.py b/tests/test_document.py
@@ -9,6 +9,7 @@
 
 import pytest
 
+from docx.comments import Comments
 from docx.document import Document, _Body
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
@@ -164,6 +165,12 @@ def it_can_save_the_document_to_a_file(self, document_part_: Mock):
 
         document_part_.save.assert_called_once_with("foobar.docx")
 
+    def it_provides_access_to_the_comments(self, document_part_: Mock, comments_: Mock):
+        document_part_.comments = comments_
+        document = Document(cast(CT_Document, element("w:document")), document_part_)
+
+        assert document.comments is comments_
+
     def it_provides_access_to_its_core_properties(
         self, document_part_: Mock, core_properties_: Mock
     ):
@@ -281,6 +288,10 @@ def _block_width_prop_(self, request: FixtureRequest):
     def body_prop_(self, request: FixtureRequest):
         return property_mock(request, Document, "_body")
 
+    @pytest.fixture
+    def comments_(self, request: FixtureRequest):
+        return instance_mock(request, Comments)
+
     @pytest.fixture
     def core_properties_(self, request: FixtureRequest):
         return instance_mock(request, CoreProperties)
