← 返回首页
Add revision management capability + tests + docs by amithkk · Pull Request #1534 · python-openxml/python-docx · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Saved searches

Use saved searches to filter your results more quickly

Appearance settings
Resetting focus

Add revision management capability + tests + docs#1534

Open
amithkk wants to merge 5 commits into
python-openxml:masterfrom
amithkk:feat/revision-management
Open

Add revision management capability + tests + docs#1534
amithkk wants to merge 5 commits into
python-openxml:masterfrom
amithkk:feat/revision-management

Conversation

Copy link
Copy Markdown

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.

Copy link
Copy Markdown

jfthuong commented Jan 9, 2026
edited
Loading

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 )

Copy link
Copy Markdown

Hi @jfthuong and @amithkk, following up on the discussion here about reading the final text: I've opened #1538 which implements native support for w:ins in paragraph.text (resolving to the 'Accepted' view) and registers w:delText for provenance tools. It might be a useful complement to the writing capabilities here.

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
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.

3 participants

Footer

© 2026 GitHub, Inc.