Skip to content

v1.0.0 — WmlComparer is gone: DocxDiff is the engine

Choose a tag to compare

@JSv4 JSv4 released this 06 Sep 13:05
· 8 commits to main since this release
b368d3d

WmlComparer is gone. DocxDiff is the engine.

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.


Do I have to change anything?

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.

Breaking changes

Removed keyword arguments

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.

Unknown settings now raise

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.

Revision counts moved — re-baseline your assertions

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.

Documents that already carry tracked changes

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.

GitHub Action

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 deprecated

To 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.


Bug fixes

Passing file paths no longer deletes your documents

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.


Upgrading

  1. Remove engine=, detail_threshold=, simplify_move_markup=.
  2. Re-baseline any revision-count assertions.
  3. Diff a representative document if you redline revision-bearing inputs.
  4. Remove the Action's comparison: input.
  5. Move off 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.