Implement support for revisions and comments.

Author: FireMasterK

HISTORY.rst

@@ -3,6 +3,19 @@
 Release History
 ---------------
 
+master branch:
+++++++++++++++++++
+
+- Add support for tracked insertions and deletions (revisions)
+- Add `Paragraph.accepted_text`, `Paragraph.deleted_text`, and tracked-change helpers
+- Change `Paragraph.text` to include deleted text and exclude inserted text
+- Add paragraph/run comment convenience methods and comment resolution timestamp support
+- Add `_Cell.add_comment()` convenience for comments anchored to cell content
+- Add `Paragraph.add_comment_range()` for substring comments on accepted-view text
+- Add `TrackedChange.add_comment()` for comments on tracked insertions and deletions
+- Restrict comment resolution to top-level comments; replies are not independently resolvable
+
+
 1.2.0 (2025-06-16)
 ++++++++++++++++++
 

docs/index.rst

@@ -82,6 +82,7 @@ User Guide
    user/styles-understanding
    user/styles-using
    user/comments
+   user/revisions
    user/shapes
 
 

docs/user/comments.rst

@@ -68,10 +68,11 @@ empty string if not configured. *date* is also optional, but always set by Word
 UTC date and time the comment was added, with seconds resolution (no milliseconds or
 microseconds).
 
-**Additional Features.** Later versions of Word allow a comment to be *resolved*. A
-comment in this state will appear grayed-out in the Word UI. Later versions of Word also
-allow a comment to be *replied to*, forming a *comment thread*. Neither of these
-features is supported by the initial implementation of comments in *python-docx*.
+**Additional Features.** Later versions of Word allow a top-level comment to be
+*resolved*. A comment in this state will appear grayed-out in the Word UI. Later
+versions of Word also allow a comment to be *replied to*, forming a *comment thread*.
+*python-docx* supports both replies and resolved-state metadata, but only for the
+top-level comment in a thread.
 
 **Applicability.** Note that comments cannot be added to a header or footer and cannot
 be nested inside a comment itself. In general the *python-docx* API will not allow these
@@ -109,6 +110,48 @@ A simple example is adding a comment to a paragraph::
 
 The API documentation for :meth:`.Document.add_comment` provides further details.
 
+For convenience, a comment can also be added directly from a paragraph, run, or
+table cell::
+
+    >>> paragraph = document.add_paragraph("Hello, world!")
+    >>> comment = paragraph.add_comment("Please reword this.", author="Steve Canny")
+    >>> run = paragraph.runs[0]
+    >>> comment = run.add_comment("Comment on just this run.", author="Steve Canny")
+    >>> table = document.add_table(rows=1, cols=1)
+    >>> cell = table.cell(0, 0)
+    >>> cell.text = "Cell text"
+    >>> comment = cell.add_comment("Comment on this cell.", author="Steve Canny")
+
+Tracked changes also provide a convenience API. A comment can be anchored directly to
+an insertion or deletion::
+
+    >>> paragraph = document.add_paragraph("Hello")
+    >>> insertion = paragraph.add_tracked_insertion(" world", author="Editor")
+    >>> comment = insertion.add_comment("Please justify this insertion.", author="Reviewer")
+
+When added from a cell, the comment is anchored from the first run in the first
+paragraph of the cell to the last run in the last paragraph of the cell. This matches
+Word's XML model, where a so-called "cell comment" is really a comment range anchored
+inside the cell's paragraph content rather than on the cell element itself.
+
+For run-level tracked changes, Word stores the comment as an ordinary comment range
+that brackets the ``<w:ins>`` or ``<w:del>`` wrapper itself. For block-level tracked
+changes such as inserted or deleted paragraphs and tables, the comment is anchored to
+the first and last paragraph content inside the tracked block because comment markers
+still have to live on paragraph/run boundaries.
+
+When you need to anchor a comment to only part of a paragraph's text, use
+``Paragraph.add_comment_range(start, end, ...)`` with offsets measured against
+``paragraph.accepted_text``::
+
+    >>> paragraph = document.add_paragraph("South")
+    >>> comment = paragraph.add_comment_range(1, 3, "Comment on just 'ou'.")
+
+The method will split runs as needed so the comment range lands on proper run
+boundaries. In this first pass, range comments are limited to plain paragraph runs;
+selections that include deleted text, hyperlinks, or other non-run content raise
+``ValueError`` rather than guessing.
+
 
 Accessing and using the Comments collection
 -------------------------------------------
@@ -166,3 +209,28 @@ The author and initials metadata can be updated as desired::
     'John Smith'
     >>> comment.initials
     'JS'
+
+
+Resolving and reopening comments
+--------------------------------
+
+A top-level comment can be marked resolved or reopened using either the ``resolved``
+property or the convenience methods ``resolve()`` and ``reopen()``::
+
+    >>> comment.resolved
+    False
+    >>> comment.resolve()
+    >>> comment.resolved
+    True
+    >>> comment.resolved_at is not None
+    True
+    >>> comment.reopen()
+    >>> comment.resolved
+    False
+
+The ``resolved_at`` value records the UTC timestamp associated with the resolved-state
+metadata when that information is available in the document.
+
+Reply comments do not support independent resolved-state operations. This matches Word's
+review UI, which treats resolution as a property of the thread root rather than each
+individual reply.

docs/user/revisions.rst

@@ -0,0 +1,112 @@
+Working with Revisions
+======================
+
+Word's *track changes* feature stores inserted and deleted content in revision wrappers
+such as ``<w:ins>`` and ``<w:del>``. *python-docx* exposes those content revisions so
+they can be read, created, accepted, rejected, and used in tracked find-and-replace
+operations.
+
+
+Reading paragraph text with revisions
+-------------------------------------
+
+Paragraph text now has two primary views:
+
+- ``Paragraph.text`` returns the paragraph's original reading view: normal text plus
+  deleted text, excluding inserted text.
+- ``Paragraph.accepted_text`` returns the visible/accepted view: normal text plus
+  inserted text, excluding deleted text.
+
+Deleted-only content is also available directly via ``Paragraph.deleted_text``::
+
+    >>> from docx import Document
+    >>> document = Document()
+    >>> paragraph = document.add_paragraph("Alpha")
+    >>> paragraph.add_tracked_insertion("Beta", author="Editor")
+    >>> paragraph.add_tracked_deletion(1, 4, author="Editor")
+
+    >>> paragraph.text
+    'Alpha'
+    >>> paragraph.accepted_text
+    'AaBeta'
+    >>> paragraph.deleted_text
+    'lph'
+
+
+Inspecting tracked changes
+--------------------------
+
+Tracked insertions and deletions can be accessed from a paragraph using:
+
+- ``paragraph.has_track_changes``
+- ``paragraph.insertions``
+- ``paragraph.deletions``
+- ``paragraph.track_changes``
+
+Each tracked change provides metadata such as author, date, revision id, and text::
+
+    >>> change = paragraph.track_changes[0]
+    >>> change.author
+    'Editor'
+    >>> change.text
+    'Beta'
+
+
+Adding tracked changes
+----------------------
+
+Tracked insertions and deletions can be created directly on ``Paragraph`` and ``Run``
+objects::
+
+    >>> paragraph = document.add_paragraph("Alpha")
+    >>> paragraph.add_tracked_insertion("Beta", author="Editor")
+    >>> paragraph.add_tracked_deletion(1, 4, author="Editor")
+
+Run-level deletion and replacement are also available::
+
+    >>> run = paragraph.runs[0]
+    >>> run.delete_tracked(author="Editor")
+
+
+Accepting and rejecting changes
+-------------------------------
+
+Individual changes can be accepted or rejected using the tracked-change proxy object::
+
+    >>> change = paragraph.track_changes[0]
+    >>> change.accept()
+
+Document-wide operations are also available::
+
+    >>> document.accept_all()
+    >>> document.reject_all()
+
+
+Tracked find-and-replace
+------------------------
+
+Tracked replacement operates on the accepted/visible text view so that inserted text is
+searchable and deleted text is ignored::
+
+    >>> document.find_and_replace_tracked("Acme", "NewCo", author="Editor")
+
+
+Interaction with comments
+-------------------------
+
+Comment markers do not contribute text to either ``Paragraph.text`` or
+``Paragraph.accepted_text``. A paragraph can contain both comments and tracked changes;
+text extraction remains based on document text and revision wrappers, not on comment
+anchor markers.
+
+Tracked changes can also be commented directly using the tracked-change proxy::
+
+    >>> paragraph = document.add_paragraph("Hello")
+    >>> insertion = paragraph.add_tracked_insertion(" world", author="Editor")
+    >>> comment = insertion.add_comment("Why was this added?", author="Reviewer")
+
+For run-level revisions, the comment range brackets the ``<w:ins>`` or ``<w:del>``
+element externally, matching Word-authored documents. For block-level revisions, such
+as inserted paragraphs or deleted tables, the comment is anchored to the first and last
+paragraph content inside the tracked block so the markers still land on valid run
+boundaries.

src/docx/blkcntnr.py

@@ -84,7 +84,11 @@ def paragraphs(self):
 
         Read-only.
         """
-        return [Paragraph(p, self) for p in self._element.p_lst]
+        return [
+            Paragraph(element, self)
+            for element in self._element.inner_content_elements
+            if isinstance(element, CT_P)
+        ]
 
     @property
     def tables(self):
@@ -94,7 +98,11 @@ def tables(self):
         """
         from docx.table import Table
 
-        return [Table(tbl, self) for tbl in self._element.tbl_lst]
+        return [
+            Table(element, self)
+            for element in self._element.inner_content_elements
+            if isinstance(element, CT_Tbl)
+        ]
 
     def _add_paragraph(self):
         """Return paragraph newly added to the end of the content in this container."""

src/docx/comments.py

@@ -8,7 +8,7 @@
 from docx.blkcntnr import BlockItemContainer
 
 if TYPE_CHECKING:
-    from docx.oxml.comments import CT_Comment, CT_CommentEx, CT_Comments
+    from docx.oxml.comments import CT_Comment, CT_CommentEx, CT_CommentExtensible, CT_Comments
     from docx.parts.comments import CommentsPart
     from docx.styles.style import ParagraphStyle
     from docx.text.paragraph import Paragraph
@@ -214,18 +214,41 @@ def replies(self) -> list[Comment]:
 
     @property
     def resolved(self) -> bool:
-        """True when this comment is marked resolved/done."""
+        """True when this top-level comment is marked resolved/done."""
+        if self.parent_para_id is not None:
+            return False
         return bool(self._comment_ex_elm.done) if self._comment_ex_elm is not None else False
 
     @resolved.setter
     def resolved(self, value: bool):
+        self._validate_resolution_supported()
         comment_ex = (
             self._comment_ex_elm
             if self._comment_ex_elm is not None
             else self._comments_part.ensure_comment_ex(self._comment_elm)
         )
         comment_ex.done = value
         self._comment_ex_elm = comment_ex
+        if value:
+            self._comments_part.ensure_comment_extensible(
+                self._comment_elm, dt.datetime.now(dt.timezone.utc)
+            )
+
+    def resolve(self) -> None:
+        """Mark this comment resolved and stamp a resolution timestamp."""
+        self.resolved = True
+
+    def reopen(self) -> None:
+        """Mark this comment unresolved."""
+        self.resolved = False
+
+    @property
+    def resolved_at(self) -> dt.datetime | None:
+        """Timestamp associated with resolution metadata, when available."""
+        if self.parent_para_id is not None:
+            return None
+        comment_extensible = self._comment_extensible_elm
+        return comment_extensible.dateUtc if comment_extensible is not None else None
 
     @property
     def initials(self) -> str | None:
@@ -257,3 +280,11 @@ def timestamp(self) -> dt.datetime | None:
         This attribute is optional in the XML, returns |None| if not set.
         """
         return self._comment_elm.date
+
+    def _validate_resolution_supported(self) -> None:
+        if self.parent_para_id is not None:
+            raise ValueError("reply comments do not support resolved state")
+
+    @property
+    def _comment_extensible_elm(self) -> CT_CommentExtensible | None:
+        return self._comments_part.comment_extensible_for(self._comment_elm)