Collection containing the comments added to this document.
| 15 | |
| 16 | |
| 17 | class Comments: |
| 18 | """Collection containing the comments added to this document.""" |
| 19 | |
| 20 | def __init__(self, comments_elm: CT_Comments, comments_part: CommentsPart): |
| 21 | self._comments_elm = comments_elm |
| 22 | self._comments_part = comments_part |
| 23 | |
| 24 | def __iter__(self) -> Iterator[Comment]: |
| 25 | """Iterator over the comments in this collection.""" |
| 26 | return ( |
| 27 | Comment(comment_elm, self._comments_part) |
| 28 | for comment_elm in self._comments_elm.comment_lst |
| 29 | ) |
| 30 | |
| 31 | def __len__(self) -> int: |
| 32 | """The number of comments in this collection.""" |
| 33 | return len(self._comments_elm.comment_lst) |
| 34 | |
| 35 | def add_comment(self, text: str = "", author: str = "", initials: str | None = "") -> Comment: |
| 36 | """Add a new comment to the document and return it. |
| 37 | |
| 38 | The comment is added to the end of the comments collection and is assigned a unique |
| 39 | comment-id. |
| 40 | |
| 41 | If `text` is provided, it is added to the comment. This option provides for the common |
| 42 | case where a comment contains a modest passage of plain text. Multiple paragraphs can be |
| 43 | added using the `text` argument by separating their text with newlines (`"\\\\n"`). |
| 44 | Between newlines, text is interpreted as it is in `Document.add_paragraph(text=...)`. |
| 45 | |
| 46 | The default is to place a single empty paragraph in the comment, which is the same |
| 47 | behavior as the Word UI when you add a comment. New runs can be added to the first |
| 48 | paragraph in the empty comment with `comments.paragraphs[0].add_run()` to adding more |
| 49 | complex text with emphasis or images. Additional paragraphs can be added using |
| 50 | `.add_paragraph()`. |
| 51 | |
| 52 | `author` is a required attribute, set to the empty string by default. |
| 53 | |
| 54 | `initials` is an optional attribute, set to the empty string by default. Passing |None| |
| 55 | for the `initials` parameter causes that attribute to be omitted from the XML. |
| 56 | """ |
| 57 | comment_elm = self._comments_elm.add_comment() |
| 58 | comment_elm.author = author |
| 59 | comment_elm.initials = initials |
| 60 | comment_elm.date = dt.datetime.now(dt.timezone.utc) |
| 61 | comment = Comment(comment_elm, self._comments_part) |
| 62 | |
| 63 | if text == "": |
| 64 | return comment |
| 65 | |
| 66 | para_text_iter = iter(text.split("\n")) |
| 67 | |
| 68 | first_para_text = next(para_text_iter) |
| 69 | first_para = comment.paragraphs[0] |
| 70 | first_para.add_run(first_para_text) |
| 71 | |
| 72 | for s in para_text_iter: |
| 73 | comment.add_paragraph(text=s) |
| 74 |
no outgoing calls
searching dependent graphs…