Add a comment spanning from one element to another. Args: start: DOM element for the starting point end: DOM element for the ending point text: Comment content Returns: The comment ID that was created Example:
(self, start, end, text: str)
| 711 | return self._editors[xml_path] |
| 712 | |
| 713 | def add_comment(self, start, end, text: str) -> int: |
| 714 | """ |
| 715 | Add a comment spanning from one element to another. |
| 716 | |
| 717 | Args: |
| 718 | start: DOM element for the starting point |
| 719 | end: DOM element for the ending point |
| 720 | text: Comment content |
| 721 | |
| 722 | Returns: |
| 723 | The comment ID that was created |
| 724 | |
| 725 | Example: |
| 726 | start_node = cm.get_document_node(tag="w:del", id="1") |
| 727 | end_node = cm.get_document_node(tag="w:ins", id="2") |
| 728 | cm.add_comment(start=start_node, end=end_node, text="Explanation") |
| 729 | """ |
| 730 | comment_id = self.next_comment_id |
| 731 | para_id = _generate_hex_id() |
| 732 | durable_id = _generate_hex_id() |
| 733 | timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") |
| 734 | |
| 735 | # Add comment ranges to document.xml immediately |
| 736 | self._document.insert_before(start, self._comment_range_start_xml(comment_id)) |
| 737 | |
| 738 | # If end node is a paragraph, append comment markup inside it |
| 739 | # Otherwise insert after it (for run-level anchors) |
| 740 | if end.tagName == "w:p": |
| 741 | self._document.append_to(end, self._comment_range_end_xml(comment_id)) |
| 742 | else: |
| 743 | self._document.insert_after(end, self._comment_range_end_xml(comment_id)) |
| 744 | |
| 745 | # Add to comments.xml immediately |
| 746 | self._add_to_comments_xml( |
| 747 | comment_id, para_id, text, self.author, self.initials, timestamp |
| 748 | ) |
| 749 | |
| 750 | # Add to commentsExtended.xml immediately |
| 751 | self._add_to_comments_extended_xml(para_id, parent_para_id=None) |
| 752 | |
| 753 | # Add to commentsIds.xml immediately |
| 754 | self._add_to_comments_ids_xml(para_id, durable_id) |
| 755 | |
| 756 | # Add to commentsExtensible.xml immediately |
| 757 | self._add_to_comments_extensible_xml(durable_id) |
| 758 | |
| 759 | # Update existing_comments so replies work |
| 760 | self.existing_comments[comment_id] = {"para_id": para_id} |
| 761 | |
| 762 | self.next_comment_id += 1 |
| 763 | return comment_id |
| 764 | |
| 765 | def reply_to_comment( |
| 766 | self, |
nothing calls this directly
no test coverage detected