Comment-related objects

Comments objects

class docx.comments.Comments

Collection containing the comments added to this document.

add_comment(text: str = '', author: str = '', initials: str | None = '') → Comment

Add a new comment to the document and return it.

The comment is added to the end of the comments collection and is assigned a unique comment-id.

If text is provided, it is added to the comment. This option provides for the common case where a comment contains a modest passage of plain text. Multiple paragraphs can be added using the text argument by separating their text with newlines (”\n”). Between newlines, text is interpreted as it is in Document.add_paragraph(text=…).

The default is to place a single empty paragraph in the comment, which is the same behavior as the Word UI when you add a comment. New runs can be added to the first paragraph in the empty comment with comments.paragraphs[0].add_run() to adding more complex text with emphasis or images. Additional paragraphs can be added using .add_paragraph().

author is a required attribute, set to the empty string by default.

initials is an optional attribute, set to the empty string by default. Passing None for the initials parameter causes that attribute to be omitted from the XML.

get(comment_id: int) → Comment | None

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

Comment objects

class docx.comments.Comment

Proxy for a single comment in the document.

Provides methods to access comment metadata such as author, initials, and date.

A comment is also a block-item container, similar to a table cell, so it can contain both paragraphs and tables and its paragraphs can contain rich text, hyperlinks and images, although the common case is that a comment contains a single paragraph of plain text like a sentence or phrase.

Note that certain content like tables may not be displayed in the Word comment sidebar due to space limitations. Such “over-sized” content can still be viewed in the review pane.

add_paragraph(text: str = '', style: str | ParagraphStyle | None = None) → Paragraph

Return paragraph newly added to the end of the content in this container.

The paragraph has text in a single run if present, and is given paragraph style style. When style is None or ommitted, the “CommentText” paragraph style is applied, which is the default style for comments.

add_table(rows: int, cols: int, width: Length) → Table

Return table of width having rows rows and cols columns.

The table is appended appended at the end of the content in this container.

width is evenly distributed between the table columns.

property author: str

Read/write. The recorded author of this comment.

This field is required but can be set to the empty string.

property comment_id: int

The unique identifier of this comment.

property initials: str | None

Read/write. The recorded initials of the comment author.

This attribute is optional in the XML, returns None if not set. Assigning None removes any existing initials from the XML.

iter_inner_content() → Iterator[Paragraph | Table]

Generate each Paragraph or Table in this container in document order.

property paragraphs

A list containing the paragraphs in this container, in document order.

Read-only.

property tables

A list containing the tables in this container, in document order.

Read-only.

property text: str

The text content of this comment as a string.

Only content in paragraphs is included and of course all emphasis and styling is stripped.

Paragraph boundaries are indicated with a newline (”\n”)

property timestamp: datetime | None

The date and time this comment was authored.

This attribute is optional in the XML, returns None if not set.