Open-source DOCX comparison tool to generate native Word tracked changes (redlines) in Python without MS Word dependencies
Repo JSv4/Python-Redlines, read from GitHub 13 min ago. JSv4 has not joined Take My Repo.
Python-Redlines 2.0.0 bundles Docxodus v14.1.0 and fixes incompatible wrapper/engine installations. This is a major release to make the change in generated redlines an explicit upgrade boundary. Python call signatures and supported comparison settings remain compatible with 1.0.0; comparison markup, revision granularity and counts can change.
pip install --upgrade 'python-redlines[docxodus]==2.0.0'Every extra now pins its engine companion to exactly the wrapper's release version. Update separately pinned companion packages and lockfiles to 2.0.0 too. All three packages release together: python-redlines, python-redlines-docxodus, and python-redlines-ooxmlpowertools.
Review representative documents and refresh any output snapshots or revision-count expectations before updating production. A single-character CJK edit now marks only the changed character. Edits within unchanged content-control and custom-XML wrappers can be marked inside the wrapper rather than replacing the whole wrapper. The project's fixture still reports 10 revisions, but other documents can produce different output.
See the 2.0.0 migration guide. Upgrades from 0.3.0 must also follow the existing 1.0.0 migration steps: the removed engine, detail_threshold and simplify_move_markup settings remain unsupported. XmlPowerToolsEngine remains available and deprecated.
EngineExecutionError, a subprocess.CalledProcessError subclass whose message includes captured stderr and stdout. Existing exception handlers and the returncode, cmd, stdout/output, and stderr attributes remain compatible.1b05750689afc432d24a5e9fd9849a01899a9994. See the upstream release history for the full engine changes.Validation: all nine Linux/macOS/Windows × Python 3.9/3.11/3.12 test jobs, builds for all six engine-wheel targets, core wheel/sdist checks, and Action self-tests passed. Codex reviews found no actionable defects in the engine update, dependency fix, or release preparation.
Python-Redlines 1.0.0 fully drops WmlComparer in favour of DocxDiff, the now-mature structure-aware engine from upstream Docxodus.
For its entire life this library ran Microsoft's WmlComparer — first the original Open-XML-PowerTools code, then Docxodus's modernized fork of it. DocxDiff arrived in 0.3.0 as an opt-in second algorithm and asked for feedback. That feedback came back good, upstream made it the default in Docxodus v8.0.0, and Docxodus v11.0.0 deleted WmlComparer outright rather than carry a frozen second engine.
This release tracks that: the submodule moves v7.0.0 → v12.1.0, and DocxodusEngine now runs DocxDiff and nothing else.
There is no flag to bring the old engine back. It does not exist in the binary.
DocxDiff models the document as an intermediate representation rather than a stream of runs, so it attributes a change to the exact paragraph, cell, row or section it touched — tracking table cell and row properties, section properties, and header and footer content that a run-stream diff reports coarsely or not at all.
If you call run_redline with no keyword arguments: no. Your code is unchanged. Your output will change, because the algorithm changed.
If you pass comparison settings: yes. Three arguments are removed and now raise ValueError.
| Argument | Why it is gone |
|---|---|
engine |
Selected between wmlcomparer and docxdiff. There is nothing left to select. |
detail_threshold |
Tuned WmlComparer's LCS granularity. DocxDiff's granularity is structural, with no equivalent knob. |
simplify_move_markup |
Worked around WmlComparer's move markup. DocxDiff renders moves natively. |
engine.run_redline("Reviewer", original, modified, engine="docxdiff") # ValueError engine.run_redline("Reviewer", original, modified, detail_threshold=0.3) # ValueError engine.run_redline("Reviewer", original, modified, simplify_move_markup=True) # ValueError
If you were passing engine="docxdiff", delete the argument — you now get it by default.
They raise rather than being ignored deliberately. Two of them are still accepted by the underlying CLI, which warns and does nothing. Silently dropping engine="wmlcomparer" would have handed you DocxDiff output while you believed you had selected something else — a wrong answer, not a breaking change.
The check is on the keyword being present, whatever its value: simplify_move_markup=False raises too.
A misspelled setting used to vanish in silence, which is indistinguishable from a setting that did nothing. detial_threshold=0.5 now raises ValueError and lists what is supported.
On this project's fixtures the count went from 9 (wmlcomparer) and 11 (docxdiff in 0.3.0) to 10. Note that it is not the old docxdiff number either: upstream v11 and v12 changed region arrangement, surplus table cells and section defaults. If your tests assert revision counts, re-measure them.
Docxodus v11 dropped PreserveInputRevisions from DocxCompare.Compare's front door to match Word's own Compare behaviour. Revision-bearing inputs therefore produce different output than in 0.3.0. This project's fixtures carry no input revisions and cannot warn you about this — if you redline already-redlined documents, diff a representative one before upgrading.
The comparison: input mapped onto the deleted selector. Setting it now fails the run instead of quietly comparing with something other than what was asked for. Remove it.
XmlPowerToolsEngine is deprecatedTo be precise about what "fully dropped" means here: the Docxodus engine no longer carries WmlComparer. XmlPowerToolsEngine, which wraps the original archived Open-XML-PowerTools WmlComparer, still ships and still works — it exists so anyone who needs that algorithm's exact output has somewhere to stand. It now emits a DeprecationWarning and will be removed in a future major release. python-redlines[all] still installs it, so existing pins do not change meaning.
run_redline accepts bytes or file paths. It registered both inputs for temp-file cleanup unconditionally — so when you passed paths, the cleanup pass deleted your source documents:
engine.run_redline("Author", "original.docx", "modified.docx") # deleted both files
Only byte inputs were safe, which is why the GitHub Action never hit it. Only files the library itself creates are cleaned up now. If you avoided the path API because it ate your files, it works.
ResourceWarning on every call (#30)The output scratch file was created as NamedTemporaryFile(delete=False).name, which drops the only reference to the file object. Its finalizer emitted ResourceWarning: Implicitly cleaning up ... once per call on CPython 3.13+, and under -W error surfaced as an unraisable exception attributed to whatever test happened to be running when the garbage collector reached it. Now uses mkstemp. Thanks to @mauritium for a report that pinpointed the line and explained the debugging cost.
engine=, detail_threshold=, simplify_move_markup=.comparison: input.XmlPowerToolsEngine when you can.pip install --upgrade python-redlines[docxodus]
Need the old algorithm while you migrate? Pin python-redlines==0.3.0.
Full details in Upgrading to 1.0.0.
Upgrades the vendored Docxodus engine from v5.4.2 to v7.0.0 and exposes its new comparison-engine selector.
DocxodusEngine now accepts an engine= keyword argument. wmlcomparer remains the default, so existing code is unaffected.
from python_redlines import DocxodusEngine engine = DocxodusEngine() engine.run_redline("Reviewer", original, modified) # wmlcomparer (default) engine.run_redline("Reviewer", original, modified, engine="docxdiff") # new IR engine
docxdiff is Docxodus's structure-aware IR diff engine. It produces finer-grained markup and will report a different revision count than wmlcomparer for the same pair of documents — different algorithms, both correct.
docxdiff does not supportdocxdiff does not implement detail_threshold, simplify_move_markup, or detect_format_changes. The underlying CLI accepts and silently ignores them, so passing any of the three alongside engine="docxdiff" now raises ValueError instead of quietly producing untuned output.
It does honour detect_moves, case_insensitive, conflate_spaces, move_similarity_threshold, move_minimum_word_count, and date_time.
Move markup differs between the two: docxdiff renders moves natively and rejects simplify_move_markup, so the Word-compatibility mitigation documented for wmlcomparer is unavailable there. If you need moves lowered to plain del/ins, use engine="wmlcomparer" with simplify_move_markup=True.
Docxodus v7.0.0 targets net10.0. A .NET 8 SDK can no longer build the Docxodus engine. The Open-XML-PowerTools engine still targets net8.0, and the .NET 10 SDK builds both, so only one SDK is needed.
apt install dotnet-sdk-10.0
# or: curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0This affects contributors only. Installing from PyPI ships prebuilt binaries; end users never compile anything and need no .NET SDK.
pip install python-redlines[docxodus] # Docxodus engine (wmlcomparer + docxdiff) pip install python-redlines[ooxmlpowertools] # Open-XML-PowerTools engine pip install python-redlines[all]
Full changelog: v0.2.1...v0.3.0
Patch release with documentation and typing fixes.
docs/quickstart.md rewritten to lead with the recommended DocxodusEngine (was previously the legacy engine), with a new section demonstrating Docxodus-only comparison kwargs and a callout that XmlPowerToolsEngine silently ignores them. (#23)run_redline argument type widened from Union[bytes, Path] to Union[str, bytes, Path] to match documented usage — passing plain str paths now matches the annotation. No runtime behavior change. (#23)pip install --upgrade python-redlines[docxodus]
First release of the three-package layout.
pip install python-redlines[docxodus] # default engine (recommended) pip install python-redlines[ooxmlpowertools] # legacy engine pip install python-redlines[all] # both engines
Prebuilt wheels for Linux, macOS, and Windows (x64 and arm64). No .NET SDK required to install or use.
python-redlines (pure-Python core), python-redlines-docxodus (default engine binary), python-redlines-ooxmlpowertools (legacy engine binary). Engines are optional extras.DocxodusEngine.run_redline() accepts kwargs for detect_moves, simplify_move_markup, detail_threshold, case_insensitive, move_similarity_threshold, move_minimum_word_count, detect_format_changes, conflate_spaces, and date_time.EngineNotInstalledError with the exact pip install command.XmlPowerToolsEngine remains available unchanged for existing users. Both engines share the same run_redline(author, original_bytes, modified_bytes) API.
Full Changelog: v0.0.4...v0.0.5