diffmonkey 1.0.0

Type-aware, key-based structural diffing of tabular datasets with human- and machine-readable reports.

diffmonkey

Type-aware, key-based structural diffing of tabular datasets — answer "what changed between last month's export and this month's?" in one call, with human- and machine-readable reports.

diffmonkey matches rows by a key column (or composite key), compares the remaining columns with type awareness (numbers by value, dates by calendar date, booleans by truth, strings whitespace-normalised, nulls unified), and buckets the result into added / removed / changed / unchanged with summary statistics. It is built on the rexbytes ecosystem — typemonkey for type inference and number parsing, datemonkey for date parsing, cleanmonkey for whitespace and invisible-character normalisation — so it does not re-derive those wheels.

In scope: structural comparison, change detection, change reporting. Out of scope: merge/reconciliation, text diffing, schema migration, version control.

Install

pip install diffmonkey            # CSV/TSV/pipe input built in
pip install "diffmonkey[excel]"   # add .xlsx reading (openpyxl)

Requires Python 3.11+.

Quick start

from diffmonkey import compare

old = [{"id": "1", "name": "Widget", "price": "1,234"},
       {"id": "2", "name": "Gadget", "price": "50"}]
new = [{"id": "1", "name": "Widget", "price": "1234"},   # price reformatted, not changed
       {"id": "3", "name": "Gizmo",  "price": "9"}]       # id 2 removed, id 3 added

result = compare(old, new, key="id")

print(result.summary.one_line())
# 1 added, 1 removed, 0 changed (of 2 current), 0 unchanged

print(result.to_markdown())   # human report
result.to_dict()              # machine-readable
result.write_csv("changes.csv")

"1,234" vs "1234" is not reported as a change — type-aware numeric comparison sees one number. The same applies to "01/02/2025" vs "2025-01-02" (dates, with a locale hint), " foo " vs "foo" (whitespace), and None/""/"NA" (nulls).

CLI

diffmonkey compare old.csv new.csv --key id
diffmonkey compare old.csv new.csv --key region,sku --ignore updated_at --format markdown
diffmonkey compare old.xlsx new.xlsx --key id --format json -o diff.json

Exit code is 0 when the datasets are identical and 1 when they differ — handy in CI and scripts.

Key options

Option	Purpose
key	Identity column, or list for a composite key
columns / ignore	Restrict / exclude columns from comparison
column_map={"old":"new"}	Handle renamed columns (avoids false add+remove)
rel_tol / abs_tol	Floating-point tolerance for numeric columns
locale="us" / "eu"	Disambiguate slash dates and number separators
null_equivalent	Treat all null spellings as one value (default on)
type_aware / date_aware	Toggle type/date-aware comparison
include_unchanged	Retain unchanged rows in the result
on_duplicate / on_missing_key	Policies for messy keys

Output formats

• result.to_dict() — JSON-serialisable structure
• result.to_markdown() — report for PRs, chat, email
• result.to_html() — standalone HTML diff report
• result.to_csv() / result.write_csv(path) — one row per field change

Using with AI assistants

See SKILL.md for LLM-oriented usage (decision tree, worked examples, anti-patterns). See LIMITATIONS.md for the deliberate design tradeoffs (date/locale ambiguity, null vocabulary, duplicate handling) so behaviour that looks surprising is not mistaken for a bug.

License

MIT — see LICENSE.