comments: add DocumentPart._comments_part

Also involves adding `CommentsPart.default`. Because the comments part
is optional, we need a mechanism to add a default (empty) comments part
when one is not present. This is what `CommentsPart.default()` is for.

Author: scanny

src/docx/oxml/comments.py

@@ -0,0 +1,15 @@
+"""Custom element classes related to document comments."""
+
+from __future__ import annotations
+
+from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+class CT_Comments(BaseOxmlElement):
+    """`w:comments` element, the root element for the comments part.
+
+    Simply contains a collection of `w:comment` elements, each representing a single comment. Each
+    contained comment is identified by a unique `w:id` attribute, used to reference the comment
+    from the document text. The offset of the comment in this collection is arbitrary; it is
+    essentially a _set_ implemented as a list.
+    """

src/docx/parts/comments.py

@@ -2,7 +2,17 @@
 
 from __future__ import annotations
 
+import os
+from typing import cast
+
+from typing_extensions import Self
+
 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.oxml.parser import parse_xml
+from docx.package import Package
 from docx.parts.story import StoryPart
 
 
@@ -13,3 +23,19 @@ class CommentsPart(StoryPart):
     def comments(self) -> Comments:
         """A |Comments| proxy object for the `w:comments` root element of this part."""
         raise NotImplementedError
+
+    @classmethod
+    def default(cls, package: Package) -> Self:
+        """A newly created comments part, containing a default empty `w:comments` element."""
+        partname = PackURI("/word/comments.xml")
+        content_type = CT.WML_COMMENTS
+        element = cast("CT_Comments", parse_xml(cls._default_comments_xml()))
+        return cls(partname, content_type, element, package)
+
+    @classmethod
+    def _default_comments_xml(cls) -> bytes:
+        """A byte-string containing XML for a default comments part."""
+        path = os.path.join(os.path.split(__file__)[0], "..", "templates", "default-comments.xml")
+        with open(path, "rb") as f:
+            xml_bytes = f.read()
+        return xml_bytes

src/docx/parts/document.py

@@ -131,7 +131,13 @@ def _comments_part(self) -> CommentsPart:
 
         Creates a default comments part if one is not present.
         """
-        raise NotImplementedError
+        try:
+            return cast(CommentsPart, self.part_related_by(RT.COMMENTS))
+        except KeyError:
+            assert self.package is not None
+            comments_part = CommentsPart.default(self.package)
+            self.relate_to(comments_part, RT.COMMENTS)
+            return comments_part
 
     @property
     def _settings_part(self) -> SettingsPart:

src/docx/templates/default-comments.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:comments
+  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+  xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+  mc:Ignorable="w14 w15 w16se w16cid wp14"/>

tests/parts/test_comments.py

@@ -0,0 +1,25 @@
+"""Unit test suite for the docx.parts.hdrftr module."""
+
+from __future__ import annotations
+
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.package import Package
+from docx.parts.comments import CommentsPart
+
+
+class DescribeCommentsPart:
+    """Unit test suite for `docx.parts.comments.CommentsPart` objects."""
+
+    def it_constructs_a_default_comments_part_to_help(self):
+        package = Package()
+
+        comments_part = CommentsPart.default(package)
+
+        assert isinstance(comments_part, CommentsPart)
+        assert comments_part.partname == "/word/comments.xml"
+        assert comments_part.content_type == CT.WML_COMMENTS
+        assert comments_part.package is package
+        assert comments_part.element.tag == (
+            "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}comments"
+        )
+        assert len(comments_part.element) == 0

tests/parts/test_document.py

@@ -227,6 +227,39 @@ def it_can_get_the_id_of_a_style(
         styles_.get_style_id.assert_called_once_with(style_, WD_STYLE_TYPE.CHARACTER)
         assert style_id == "BodyCharacter"
 
+    def it_provides_access_to_its_comments_part_to_help(
+        self, package_: Mock, part_related_by_: Mock, comments_part_: Mock
+    ):
+        part_related_by_.return_value = comments_part_
+        document_part = DocumentPart(
+            PackURI("/word/document.xml"), CT.WML_DOCUMENT, element("w:document"), package_
+        )
+
+        comments_part = document_part._comments_part
+
+        part_related_by_.assert_called_once_with(document_part, RT.COMMENTS)
+        assert comments_part is comments_part_
+
+    def and_it_creates_a_default_comments_part_if_not_present(
+        self,
+        package_: Mock,
+        part_related_by_: Mock,
+        CommentsPart_: Mock,
+        comments_part_: Mock,
+        relate_to_: Mock,
+    ):
+        part_related_by_.side_effect = KeyError
+        CommentsPart_.default.return_value = comments_part_
+        document_part = DocumentPart(
+            PackURI("/word/document.xml"), CT.WML_DOCUMENT, element("w:document"), package_
+        )
+
+        comments_part = document_part._comments_part
+
+        CommentsPart_.default.assert_called_once_with(package_)
+        relate_to_.assert_called_once_with(document_part, comments_part_, RT.COMMENTS)
+        assert comments_part is comments_part_
+
     def it_provides_access_to_its_settings_part_to_help(
         self, part_related_by_: Mock, settings_part_: Mock, package_: Mock
     ):