comments: add Comments.__len__()

Author: scanny

features/doc-comments.feature

@@ -15,7 +15,6 @@ Feature: Document.comments
       | no      |
 
 
-  @wip
   Scenario Outline: Comments.__len__()
     Given a Comments object with <count> comments
      Then len(comments) == <count>

src/docx/comments.py

@@ -18,6 +18,10 @@ def __init__(self, comments_elm: CT_Comments, comments_part: CommentsPart):
         self._comments_elm = comments_elm
         self._comments_part = comments_part
 
+    def __len__(self) -> int:
+        """The number of comments in this collection."""
+        return len(self._comments_elm.comment_lst)
+
 
 class Comment(BlockItemContainer):
     """Proxy for a single comment in the document.

src/docx/oxml/__init__.py

@@ -1,3 +1,5 @@
+# ruff: noqa: E402, I001
+
 """Initializes oxml sub-package.
 
 This including registering custom element classes corresponding to Open XML elements.
@@ -84,16 +86,21 @@
 # ---------------------------------------------------------------------------
 # other custom element class mappings
 
-from .coreprops import CT_CoreProperties  # noqa
+from .comments import CT_Comments, CT_Comment
+
+register_element_cls("w:comments", CT_Comments)
+register_element_cls("w:comment", CT_Comment)
+
+from .coreprops import CT_CoreProperties
 
 register_element_cls("cp:coreProperties", CT_CoreProperties)
 
-from .document import CT_Body, CT_Document  # noqa
+from .document import CT_Body, CT_Document
 
 register_element_cls("w:body", CT_Body)
 register_element_cls("w:document", CT_Document)
 
-from .numbering import CT_Num, CT_Numbering, CT_NumLvl, CT_NumPr  # noqa
+from .numbering import CT_Num, CT_Numbering, CT_NumLvl, CT_NumPr
 
 register_element_cls("w:abstractNumId", CT_DecimalNumber)
 register_element_cls("w:ilvl", CT_DecimalNumber)
@@ -104,7 +111,7 @@
 register_element_cls("w:numbering", CT_Numbering)
 register_element_cls("w:startOverride", CT_DecimalNumber)
 
-from .section import (  # noqa
+from .section import (
     CT_HdrFtr,
     CT_HdrFtrRef,
     CT_PageMar,
@@ -122,11 +129,11 @@
 register_element_cls("w:sectPr", CT_SectPr)
 register_element_cls("w:type", CT_SectType)
 
-from .settings import CT_Settings  # noqa
+from .settings import CT_Settings
 
 register_element_cls("w:settings", CT_Settings)
 
-from .styles import CT_LatentStyles, CT_LsdException, CT_Style, CT_Styles  # noqa
+from .styles import CT_LatentStyles, CT_LsdException, CT_Style, CT_Styles
 
 register_element_cls("w:basedOn", CT_String)
 register_element_cls("w:latentStyles", CT_LatentStyles)
@@ -141,7 +148,7 @@
 register_element_cls("w:uiPriority", CT_DecimalNumber)
 register_element_cls("w:unhideWhenUsed", CT_OnOff)
 
-from .table import (  # noqa
+from .table import (
     CT_Height,
     CT_Row,
     CT_Tbl,
@@ -178,7 +185,7 @@
 register_element_cls("w:vAlign", CT_VerticalJc)
 register_element_cls("w:vMerge", CT_VMerge)
 
-from .text.font import (  # noqa
+from .text.font import (
     CT_Color,
     CT_Fonts,
     CT_Highlight,
@@ -217,11 +224,11 @@
 register_element_cls("w:vertAlign", CT_VerticalAlignRun)
 register_element_cls("w:webHidden", CT_OnOff)
 
-from .text.paragraph import CT_P  # noqa
+from .text.paragraph import CT_P
 
 register_element_cls("w:p", CT_P)
 
-from .text.parfmt import (  # noqa
+from .text.parfmt import (
     CT_Ind,
     CT_Jc,
     CT_PPr,

src/docx/oxml/comments.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from docx.oxml.xmlchemy import BaseOxmlElement
+from docx.oxml.xmlchemy import BaseOxmlElement, ZeroOrMore
 
 
 class CT_Comments(BaseOxmlElement):
@@ -13,3 +13,17 @@ class CT_Comments(BaseOxmlElement):
     from the document text. The offset of the comment in this collection is arbitrary; it is
     essentially a _set_ implemented as a list.
     """
+
+    # -- type-declarations to fill in the gaps for metaclass-added methods --
+    comment_lst: list[CT_Comment]
+
+    comment = ZeroOrMore("w:comment")
+
+
+class CT_Comment(BaseOxmlElement):
+    """`w:comment` element, representing a single comment.
+
+    A comment is a so-called "story" and can contain paragraphs and tables much like a table-cell.
+    While probably most often used for a single sentence or phrase, a comment can contain rich
+    content, including multiple rich-text paragraphs, hyperlinks, images, and tables.
+    """

tests/test_comments.py

@@ -0,0 +1,49 @@
+"""Unit test suite for the docx.comments module."""
+
+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, instance_mock
+
+
+class DescribeComments:
+    """Unit-test suite for `docx.comments.Comments`."""
+
+    @pytest.mark.parametrize(
+        ("cxml", "count"),
+        [
+            ("w:comments", 0),
+            ("w:comments/w:comment", 1),
+            ("w:comments/(w:comment,w:comment,w:comment)", 3),
+        ],
+    )
+    def it_knows_how_many_comments_it_contains(self, cxml: str, count: int, package_: Mock):
+        comments_elm = cast(CT_Comments, element(cxml))
+        comments = Comments(
+            comments_elm,
+            CommentsPart(
+                PackURI("/word/comments.xml"),
+                CT.WML_COMMENTS,
+                comments_elm,
+                package_,
+            ),
+        )
+
+        assert len(comments) == count
+
+    # -- fixtures --------------------------------------------------------------------------------
+
+    @pytest.fixture
+    def package_(self, request: FixtureRequest):
+        return instance_mock(request, Package)