Skip to content

comments

comments

Custom element classes related to document comments.

CT_Comments

Bases: BaseOxmlElement

w:comments element, the root element for the comments part.

Simply contains a collection of w:comment elements, each representing a single comment. Each contained comment is identified by a unique w:id attribute, used to reference the comment from the document text. The offset of the comment in this collection is arbitrary; it is essentially a set implemented as a list.

add_comment 

add_comment() -> CT_Comment

Return newly added w:comment child of this w:comments.

The returned w:comment element is the minimum valid value, having a w:id value unique within the existing comments and the required w:author attribute present but set to the empty string. It's content is limited to a single run containing the necessary annotation reference but no text. Content is added by adding runs to this first paragraph and by adding additional paragraphs as needed.

Source code in src/docx/oxml/comments.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def add_comment(self) -> CT_Comment:
    """Return newly added `w:comment` child of this `w:comments`.

    The returned `w:comment` element is the minimum valid value, having a `w:id` value unique
    within the existing comments and the required `w:author` attribute present but set to the
    empty string. It's content is limited to a single run containing the necessary annotation
    reference but no text. Content is added by adding runs to this first paragraph and by
    adding additional paragraphs as needed.
    """
    next_id = self._next_available_comment_id()
    comment = cast(
        CT_Comment,
        parse_xml(
            f'<w:comment {nsdecls("w")} w:id="{next_id}" w:author="">'
            f"  <w:p>"
            f"    <w:pPr>"
            f'      <w:pStyle w:val="CommentText"/>'
            f"    </w:pPr>"
            f"    <w:r>"
            f"      <w:rPr>"
            f'        <w:rStyle w:val="CommentReference"/>'
            f"      </w:rPr>"
            f"      <w:annotationRef/>"
            f"    </w:r>"
            f"  </w:p>"
            f"</w:comment>"
        ),
    )
    self.append(comment)
    return comment

get_comment_by_id 

get_comment_by_id(comment_id: int) -> CT_Comment | None

Return the w:comment element identified by comment_id, or None if not found.

Source code in src/docx/oxml/comments.py 
64
65
66
67
def get_comment_by_id(self, comment_id: int) -> CT_Comment | None:
    """Return the `w:comment` element identified by `comment_id`, or |None| if not found."""
    comment_elms = self.xpath(f"(./w:comment[@w:id='{comment_id}'])[1]")
    return comment_elms[0] if comment_elms else None

CT_Comment

Bases: BaseOxmlElement

w:comment element, representing a single comment.

A comment is a so-called "story" and can contain paragraphs and tables much like a table-cell. While probably most often used for a single sentence or phrase, a comment can contain rich content, including multiple rich-text paragraphs, hyperlinks, images, and tables.

inner_content_elements property 

inner_content_elements: list[CT_P | CT_Tbl]

Generate all w:p and w:tbl elements in this comment.

Content inside a w:sdt (content control) wrapper is included.