# pyright: reportPrivateUsage=false """Unit test suite for the `docx.comments` module.""" from __future__ import annotations import datetime as dt from typing import cast import pytest from docx.comments import Comment, Comments from docx.opc.constants import CONTENT_TYPE as CT from docx.opc.packuri import PackURI from docx.oxml.comments import CT_Comment, CT_Comments from docx.oxml.ns import qn 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` objects.""" @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 def it_is_iterable_over_the_comments_it_contains(self, package_: Mock): comments_elm = cast(CT_Comments, element("w:comments/(w:comment,w:comment)")) comments = Comments( comments_elm, CommentsPart( PackURI("/word/comments.xml"), CT.WML_COMMENTS, comments_elm, package_, ), ) comment_iter = iter(comments) comment1 = next(comment_iter) assert type(comment1) is Comment, "expected a `Comment` object" comment2 = next(comment_iter) assert type(comment2) is Comment, "expected a `Comment` object" with pytest.raises(StopIteration): next(comment_iter) def it_can_get_a_comment_by_id(self, package_: Mock): comments_elm = cast( CT_Comments, element("w:comments/(w:comment{w:id=1},w:comment{w:id=2},w:comment{w:id=3})"), ) comments = Comments( comments_elm, CommentsPart( PackURI("/word/comments.xml"), CT.WML_COMMENTS, comments_elm, package_, ), ) comment = comments.get(2) assert type(comment) is Comment, "expected a `Comment` object" assert comment._comment_elm is comments_elm.comment_lst[1] def but_it_returns_None_when_no_comment_with_that_id_exists(self, package_: Mock): comments_elm = cast( CT_Comments, element("w:comments/(w:comment{w:id=1},w:comment{w:id=2},w:comment{w:id=3})"), ) comments = Comments( comments_elm, CommentsPart( PackURI("/word/comments.xml"), CT.WML_COMMENTS, comments_elm, package_, ), ) comment = comments.get(4) assert comment is None, "expected None when no comment with that id exists" def it_can_add_a_new_comment(self, package_: Mock): comments_elm = cast(CT_Comments, element("w:comments")) comments_part = CommentsPart( PackURI("/word/comments.xml"), CT.WML_COMMENTS, comments_elm, package_, ) now_before = dt.datetime.now(dt.timezone.utc).replace(microsecond=0) comments = Comments(comments_elm, comments_part) comment = comments.add_comment() now_after = dt.datetime.now(dt.timezone.utc).replace(microsecond=0) # -- a comment is unconditionally added, and returned for any further adjustment -- assert isinstance(comment, Comment) # -- it is "linked" to the comments part so it can add images and hyperlinks, etc. -- assert comment.part is comments_part # -- comment numbering starts at 0, and is incremented for each new comment -- assert comment.comment_id == 0 # -- author is a required attribut, but is the empty string by default -- assert comment.author == "" # -- initials is an optional attribute, but defaults to the empty string, same as Word -- assert comment.initials == "" # -- timestamp is also optional, but defaults to now-UTC -- assert comment.timestamp is not None assert now_before <= comment.timestamp <= now_after # -- by default, a new comment contains a single empty paragraph -- assert [p.text for p in comment.paragraphs] == [""] # -- that paragraph has the "CommentText" style, same as Word applies -- comment_elm = comment._comment_elm assert len(comment_elm.p_lst) == 1 p = comment_elm.p_lst[0] assert p.style == "CommentText" # -- and that paragraph contains a single run with the necessary annotation reference -- assert len(p.r_lst) == 1 r = comment_elm.p_lst[0].r_lst[0] assert r.style == "CommentReference" assert r[-1].tag == qn("w:annotationRef") def and_it_can_add_text_to_the_comment_when_adding_it(self, comments: Comments, package_: Mock): comment = comments.add_comment(text="para 1\n\npara 2") assert len(comment.paragraphs) == 3 assert [p.text for p in comment.paragraphs] == ["para 1", "", "para 2"] assert all(p._p.style == "CommentText" for p in comment.paragraphs) def and_it_sets_the_author_and_their_initials_when_adding_a_comment_when_provided( self, comments: Comments, package_: Mock ): comment = comments.add_comment(author="Steve Canny", initials="SJC") assert comment.author == "Steve Canny" assert comment.initials == "SJC" # -- fixtures -------------------------------------------------------------------------------- @pytest.fixture def comments(self, package_: Mock) -> Comments: comments_elm = cast(CT_Comments, element("w:comments")) comments_part = CommentsPart( PackURI("/word/comments.xml"), CT.WML_COMMENTS, comments_elm, package_, ) return Comments(comments_elm, comments_part) @pytest.fixture def package_(self, request: FixtureRequest): return instance_mock(request, Package) class DescribeComment: """Unit-test suite for `docx.comments.Comment`.""" def it_knows_its_comment_id(self, comments_part_: Mock): comment_elm = cast(CT_Comment, element("w:comment{w:id=42}")) comment = Comment(comment_elm, comments_part_) assert comment.comment_id == 42 def it_knows_its_author(self, comments_part_: Mock): comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:author=Steve Canny}")) comment = Comment(comment_elm, comments_part_) assert comment.author == "Steve Canny" def it_knows_the_initials_of_its_author(self, comments_part_: Mock): comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:initials=SJC}")) comment = Comment(comment_elm, comments_part_) assert comment.initials == "SJC" def it_knows_the_date_and_time_it_was_authored(self, comments_part_: Mock): comment_elm = cast( CT_Comment, element("w:comment{w:id=42,w:date=2023-10-01T12:34:56Z}"), ) comment = Comment(comment_elm, comments_part_) assert comment.timestamp == dt.datetime(2023, 10, 1, 12, 34, 56, tzinfo=dt.timezone.utc) @pytest.mark.parametrize( ("cxml", "expected_value"), [ ("w:comment{w:id=42}", ""), ('w:comment{w:id=42}/w:p/w:r/w:t"Comment text."', "Comment text."), ( 'w:comment{w:id=42}/(w:p/w:r/w:t"First para",w:p/w:r/w:t"Second para")', "First para\nSecond para", ), ( 'w:comment{w:id=42}/(w:p/w:r/w:t"First para",w:p,w:p/w:r/w:t"Second para")', "First para\n\nSecond para", ), ], ) def it_can_summarize_its_content_as_text( self, cxml: str, expected_value: str, comments_part_: Mock ): assert Comment(cast(CT_Comment, element(cxml)), comments_part_).text == expected_value def it_provides_access_to_the_paragraphs_it_contains(self, comments_part_: Mock): comment_elm = cast( CT_Comment, element('w:comment{w:id=42}/(w:p/w:r/w:t"First para",w:p/w:r/w:t"Second para")'), ) comment = Comment(comment_elm, comments_part_) paragraphs = comment.paragraphs assert len(paragraphs) == 2 assert [para.text for para in paragraphs] == ["First para", "Second para"] def it_can_update_the_comment_author(self, comments_part_: Mock): comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:author=Old Author}")) comment = Comment(comment_elm, comments_part_) comment.author = "New Author" assert comment.author == "New Author" @pytest.mark.parametrize( "initials", [ # -- valid initials -- "XYZ", # -- empty string is valid "", # -- None is valid, removes existing initials None, ], ) def it_can_update_the_comment_initials(self, initials: str | None, comments_part_: Mock): comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:initials=ABC}")) comment = Comment(comment_elm, comments_part_) comment.initials = initials assert comment.initials == initials # -- fixtures -------------------------------------------------------------------------------- @pytest.fixture def comments_part_(self, request: FixtureRequest): return instance_mock(request, CommentsPart)