Skip to content

Commit 761f4cc

Browse files
committed
comments: add Comment.author, .initials setters
- allow setting on construction - allow update with property setters
1 parent 8ac9fc4 commit 761f4cc

File tree

4 files changed

+48
-4
lines changed

4 files changed

+48
-4
lines changed

features/cmt-mutations.feature

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,12 @@ Feature: Comment mutations
4747
Then run.iter_inner_content() yields a single Picture drawing
4848

4949

50-
@wip
5150
Scenario: update Comment.author
5251
Given a Comment object
5352
When I assign "Jane Smith" to comment.author
5453
Then comment.author == "Jane Smith"
5554

5655

57-
@wip
5856
Scenario: update Comment.initials
5957
Given a Comment object
6058
When I assign "JS" to comment.initials

src/docx/comments.py

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,16 @@ def add_paragraph(self, text: str = "", style: str | ParagraphStyle | None = Non
116116

117117
@property
118118
def author(self) -> str:
119-
"""The recorded author of this comment."""
119+
"""Read/write. The recorded author of this comment.
120+
121+
This field is required but can be set to the empty string.
122+
"""
120123
return self._comment_elm.author
121124

125+
@author.setter
126+
def author(self, value: str):
127+
self._comment_elm.author = value
128+
122129
@property
123130
def comment_id(self) -> int:
124131
"""The unique identifier of this comment."""
@@ -133,6 +140,10 @@ def initials(self) -> str | None:
133140
"""
134141
return self._comment_elm.initials
135142

143+
@initials.setter
144+
def initials(self, value: str | None):
145+
self._comment_elm.initials = value
146+
136147
@property
137148
def timestamp(self) -> dt.datetime | None:
138149
"""The date and time this comment was authored.

src/docx/shared.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -328,7 +328,7 @@ def __init__(self, parent: t.ProvidesXmlPart):
328328
self._parent = parent
329329

330330
@property
331-
def part(self):
331+
def part(self) -> XmlPart:
332332
"""The package part containing this object."""
333333
return self._parent.part
334334

tests/test_comments.py

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,14 @@ def and_it_can_add_text_to_the_comment_when_adding_it(self, comments: Comments,
153153
assert [p.text for p in comment.paragraphs] == ["para 1", "", "para 2"]
154154
assert all(p._p.style == "CommentText" for p in comment.paragraphs)
155155

156+
def and_it_sets_the_author_and_their_initials_when_adding_a_comment_when_provided(
157+
self, comments: Comments, package_: Mock
158+
):
159+
comment = comments.add_comment(author="Steve Canny", initials="SJC")
160+
161+
assert comment.author == "Steve Canny"
162+
assert comment.initials == "SJC"
163+
156164
# -- fixtures --------------------------------------------------------------------------------
157165

158166
@pytest.fixture
@@ -213,6 +221,33 @@ def it_provides_access_to_the_paragraphs_it_contains(self, comments_part_: Mock)
213221
assert len(paragraphs) == 2
214222
assert [para.text for para in paragraphs] == ["First para", "Second para"]
215223

224+
def it_can_update_the_comment_author(self, comments_part_: Mock):
225+
comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:author=Old Author}"))
226+
comment = Comment(comment_elm, comments_part_)
227+
228+
comment.author = "New Author"
229+
230+
assert comment.author == "New Author"
231+
232+
@pytest.mark.parametrize(
233+
"initials",
234+
[
235+
# -- valid initials --
236+
"XYZ",
237+
# -- empty string is valid
238+
"",
239+
# -- None is valid, removes existing initials
240+
None,
241+
],
242+
)
243+
def it_can_update_the_comment_initials(self, initials: str | None, comments_part_: Mock):
244+
comment_elm = cast(CT_Comment, element("w:comment{w:id=42,w:initials=ABC}"))
245+
comment = Comment(comment_elm, comments_part_)
246+
247+
comment.initials = initials
248+
249+
assert comment.initials == initials
250+
216251
# -- fixtures --------------------------------------------------------------------------------
217252

218253
@pytest.fixture

0 commit comments

Comments
 (0)