comments: add DocumentPart.comments

Provide a way to get a `Comments` object from the `DocumentPart`.

Author: scanny

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

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

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)