Add a comment to the document, anchored to the specified runs. `runs` can be a single `Run` object or a non-empty sequence of `Run` objects. Only the first and last run of a sequence are used, it's just more convenient to pass a whole sequence when that's what you have handy
(
self,
runs: Run | Sequence[Run],
text: str | None = "",
author: str = "",
initials: str | None = "",
)
| 39 | self.__body = None |
| 40 | |
| 41 | def add_comment( |
| 42 | self, |
| 43 | runs: Run | Sequence[Run], |
| 44 | text: str | None = "", |
| 45 | author: str = "", |
| 46 | initials: str | None = "", |
| 47 | ) -> Comment: |
| 48 | """Add a comment to the document, anchored to the specified runs. |
| 49 | |
| 50 | `runs` can be a single `Run` object or a non-empty sequence of `Run` objects. Only the |
| 51 | first and last run of a sequence are used, it's just more convenient to pass a whole |
| 52 | sequence when that's what you have handy, like `paragraph.runs` for example. When `runs` |
| 53 | contains a single `Run` object, that run serves as both the first and last run. |
| 54 | |
| 55 | A comment can be anchored only on an even run boundary, meaning the text the comment |
| 56 | "references" must be a non-zero integer number of consecutive runs. The runs need not be |
| 57 | _contiguous_ per se, like the first can be in one paragraph and the last in the next |
| 58 | paragraph, but all runs between the first and the last will be included in the reference. |
| 59 | |
| 60 | The comment reference range is delimited by placing a `w:commentRangeStart` element before |
| 61 | the first run and a `w:commentRangeEnd` element after the last run. This is why only the |
| 62 | first and last run are required and why a single run can serve as both first and last. |
| 63 | Word works out which text to highlight in the UI based on these range markers. |
| 64 | |
| 65 | `text` allows the contents of a simple comment to be provided in the call, providing for |
| 66 | the common case where a comment is a single phrase or sentence without special formatting |
| 67 | such as bold or italics. More complex comments can be added using the returned `Comment` |
| 68 | object in much the same way as a `Document` or (table) `Cell` object, using methods like |
| 69 | `.add_paragraph()`, .add_run()`, etc. |
| 70 | |
| 71 | The `author` and `initials` parameters allow that metadata to be set for the comment. |
| 72 | `author` is a required attribute on a comment and is the empty string by default. |
| 73 | `initials` is optional on a comment and may be omitted by passing |None|, but Word adds an |
| 74 | `initials` attribute by default and we follow that convention by using the empty string |
| 75 | when no `initials` argument is provided. |
| 76 | """ |
| 77 | # -- normalize `runs` to a sequence of runs -- |
| 78 | runs = [runs] if isinstance(runs, Run) else runs |
| 79 | first_run = runs[0] |
| 80 | last_run = runs[-1] |
| 81 | |
| 82 | # -- Note that comments can only appear in the document part -- |
| 83 | comment = self.comments.add_comment(text=text, author=author, initials=initials) |
| 84 | |
| 85 | # -- let the first run orchestrate placement of the comment range start and end -- |
| 86 | first_run.mark_comment_range(last_run, comment.comment_id) |
| 87 | |
| 88 | return comment |
| 89 | |
| 90 | def add_heading(self, text: str = "", level: int = 1): |
| 91 | """Return a heading paragraph newly added to the end of the document. |