Skip to content

Check Fidelity on Your Workbook

A faster save is useful only if the workbook still contains the package parts and relationships your workflow depends on. Before replacing openpyxl, run the same no-edit load/save through both libraries and compare the resulting OOXML packages.

Open the public round-trip fidelity harness

What the harness checks

The harness compares the workbook package before and after each engine saves it. It reports:

  • package parts that disappeared;
  • relationships that disappeared or point to missing targets;
  • content-type changes;
  • malformed XML;
  • feature-specific semantic drift for workbook globals, charts, pivots, slicers, timelines, conditional formatting, and other tracked families; and
  • the preservation settings and warnings emitted by each engine.

The grader is engine-neutral and uses only the Python standard library to inspect the ZIP and XML packages.

Run it on representative files

Clone the public repository, install the versions you want to compare, then point the runner at a directory of workbooks:

git clone https://github.com/SynthGL/wolfxl-community.git
cd wolfxl-community
python3 -m venv .venv-fidelity
. .venv-fidelity/bin/activate
python -m pip install wolfxl openpyxl Pillow

python fidelity-harness/roundtrip.py /path/to/workbooks \
  --engine openpyxl \
  --engine wolfxl-modify \
  --json results.json \
  --markdown results.md

The runner accepts .xlsx, .xlsm, .xltx, .xltm, and .xlsb files. It works on temporary copies and does not modify the input directory.

Use --fail-on-change when any detected package difference should fail CI. The public README also documents how to add another engine adapter and reproduce the generated comparison corpus.

Read the result at the workbook level

Inspect each changed workbook instead of relying only on aggregate counts:

  • faithful means the comparator found no package-level or tracked semantic difference for that no-edit save.
  • changed means at least one typed issue was detected. Read the exact part, relationship, and semantic-drift entries in the JSON report.
  • unsupported means the engine refused to open the workbook. It is not counted as data loss.
  • A retained part can still be unusable if the relationship that made it reachable disappeared.

Evidence boundary

A clean no-edit result does not prove that every later mutation preserves the same features. Run separate mutation tests for the edits your application performs, then open the output in the applications that matter to your users.

Generated fixtures are useful for reproducibility, but they do not replace representative production workbooks. Remove customer data or use an approved private reproduction before sharing a failing file.