Skip to content

Conversation

@amithkk
Copy link

@amithkk amithkk commented Jan 7, 2026

This PR adds comprehensive support for creating and managing tracked changes (revisions) in Word documents, enabling programmatic document editing with full revision history visible in Microsoft Word.

Tests have been added for new functionality, and existing tests have been run to ensure that backwards compatibility is maintained.

Why?

Users need to make programmatic changes to Word documents while preserving some sort of an audit trail. Solves #930 and #340

Features

  • Paragraph.add_run_tracked() - Add text as a tracked insertion
  • Run.delete_tracked() - Mark existing text as a tracked deletion
  • Paragraph.replace_tracked() - Replace specific text with revision tracking
  • Document.find_and_replace_tracked() - Bulk find-and-replace across entire document
  • document.settings.track_revisions - Enable/disable track changes mode
  • TrackedInsertion and TrackedDeletion proxy classes with accept() and reject() methods
  • Author and date metadata on all tracked changes
  • Optional comment attachment to replacements

Example Usage

from docx import Document

doc = Document('contract.docx')
doc.settings.track_revisions = True

count = doc.find_and_replace_tracked(
    "ACME Corp",
    "NewCo Inc",
    author="Legal Bot",
    comment="Company name updated per merger"
)

doc.save('contract_revised.docx')

This is just barebones, and this capability can be extended by later additions to possibly build out a context manager (eg. with document.track_all_changes() as doc:) to make it function similar to how "Track Changes" works in word. However there are a fair number of edge cases you'd have to deal with in that situation.

Some of this work draws on the exhaustive code written in OpenXmlPowerTools WmlComparer and the underlying .NET library.

@jfthuong
Copy link

jfthuong commented Jan 9, 2026

Nice job.

Would you consider adding a property for the Paragraph object to get the final text? (similar to the different solutions proposed on #340 )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants