xfail: acceptance test for Document.comments

scanny · scanny · commit 5cb32d7787a7 · 2025-06-16T14:24:39.000-07:00
diff --git a/features/doc-comments.feature b/features/doc-comments.feature
@@ -0,0 +1,40 @@
+Feature: Document.comments
+  In order to operate on comments added to a document
+  As a developer using python-docx
+  I need access to the comments collection for the document
+  And I need methods allowing access to the comments in the collection
+
+
+  @wip
+  Scenario Outline: Access document comments
+    Given a document having <a-or-no> comments part
+     Then document.comments is a Comments object
+
+    Examples: having a comments part or not
+      | a-or-no |
+      | a       |
+      | no      |
+
+
+  @wip
+  Scenario Outline: Comments.__len__()
+    Given a Comments object with <count> comments
+     Then len(comments) == <count>
+
+    Examples: len(comments) values
+      | count |
+      | 0    |
+      | 4    |
+
+
+  @wip
+  Scenario: Comments.__iter__()
+    Given a Comments object with 4 comments
+     Then iterating comments yields 4 Comment objects
+
+
+  @wip
+  Scenario: Comments.get()
+    Given a Comments object with 4 comments
+     When I call comments.get(2)
+     Then the result is a Comment object with id 2
diff --git a/features/steps/comments.py b/features/steps/comments.py
@@ -0,0 +1,69 @@
+"""Step implementations for document comments-related features."""
+
+from behave import given, then, when
+from behave.runner import Context
+
+from docx import Document
+from docx.comments import Comment, Comments
+
+from helpers import test_docx
+
+# given ====================================================
+
+
+@given("a Comments object with {count} comments")
+def given_a_comments_object_with_count_comments(context: Context, count: str):
+    testfile_name = {"0": "doc-default", "4": "comments-rich-para"}[count]
+    context.comments = Document(test_docx(testfile_name)).comments
+
+
+@given("a document having a comments part")
+def given_a_document_having_a_comments_part(context: Context):
+    context.document = Document(test_docx("comments-rich-para"))
+
+
+@given("a document having no comments part")
+def given_a_document_having_no_comments_part(context: Context):
+    context.document = Document(test_docx("doc-default"))
+
+
+# when =====================================================
+
+
+@when("I call comments.get(2)")
+def when_I_call_comments_get_2(context: Context):
+    context.comment = context.comments.get(2)
+
+
+# then =====================================================
+
+
+@then("document.comments is a Comments object")
+def then_document_comments_is_a_Comments_object(context: Context):
+    document = context.document
+    assert type(document.comments) is Comments
+
+
+@then("iterating comments yields {count} Comment objects")
+def then_iterating_comments_yields_count_comments(context: Context, count: str):
+    comment_iter = iter(context.comments)
+
+    comment = next(comment_iter)
+    assert type(comment) is Comment, f"expected a Comment object, got {type(comment)}"
+
+    remaining = list(comment_iter)
+    assert len(remaining) == int(count) - 1, "iterating comments did not yield the expected count"
+
+
+@then("len(comments) == {count}")
+def then_len_comments_eq_count(context: Context, count: str):
+    actual = len(context.comments)
+    expected = int(count)
+    assert actual == expected, f"expected len(comments) of {expected}, got {actual}"
+
+
+@then("the result is a Comment object with id 2")
+def then_the_result_is_a_comment_object_with_id_2(context: Context):
+    comment = context.comment
+    assert type(comment) is Comment, f"expected a Comment object, got {type(comment)}"
+    assert comment.comment_id == 2, f"expected comment_id `2`, got '{comment.comment_id}'"
diff --git a/features/steps/test_files/comments-rich-para.docx b/features/steps/test_files/comments-rich-para.docx
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -0,0 +1,24 @@
+"""Collection providing access to comments added to this document."""
+
+from __future__ import annotations
+
+from docx.blkcntnr import BlockItemContainer
+
+
+class Comments:
+    """Collection containing the comments added to this document."""
+
+
+class Comment(BlockItemContainer):
+    """Proxy for a single comment in the document.
+
+    Provides methods to access comment metadata such as author, initials, and date.
+
+    A comment is also a block-item container, similar to a table cell, so it can contain both
+    paragraphs and tables and its paragraphs can contain rich text, hyperlinks and images,
+    although the common case is that a comment contains a single paragraph of plain text like a
+    sentence or phrase.
+
+    Note that certain content like tables may not be displayed in the Word comment sidebar due to
+    space limitations. Such "over-sized" content can still be viewed in the review pane.
+    """
