diffx

Python bindings for diffx - semantic diff for structured data (JSON, YAML, TOML, XML, INI, CSV). Powered by Rust via PyO3 for blazing fast performance.

Installation

pip install diffx

Supported Platforms

Usage

Basic Diff

import diffx

old = {"name": "Alice", "age": 30}
new = {"name": "Alice", "age": 31, "city": "Tokyo"}

results = diffx.diff(old, new)

for change in results:
    print(f"{change['type']}: {change['path']}")
    # Modified: age
    # Added: city

With Options

results = diffx.diff(data1, data2,
    epsilon=0.001,                      # Tolerance for float comparison
    array_id_key='id',                  # Match array elements by ID
    ignore_keys_regex='timestamp|updatedAt',  # Ignore keys matching regex
    path_filter='user',                 # Only show diffs in paths containing "user"
    ignore_case=True,                   # Ignore case differences
    ignore_whitespace=True,             # Ignore whitespace differences
)

Parsers

Parse various formats to Python objects:

import diffx

json_obj = diffx.parse_json('{"name": "Alice"}')
yaml_obj = diffx.parse_yaml('name: Alice\nage: 30')
toml_obj = diffx.parse_toml('name = "Alice"')
csv_list = diffx.parse_csv('name,age\nAlice,30')
ini_obj = diffx.parse_ini('[user]\nname = Alice')
xml_obj = diffx.parse_xml('<user><name>Alice</name></user>')

Format Output

import diffx

results = diffx.diff(old, new)
print(diffx.format_output(results, 'json'))   # JSON format
print(diffx.format_output(results, 'yaml'))   # YAML format
print(diffx.format_output(results, 'diffx'))  # diffx format

File Comparison

import diffx

# Compare files (auto-detects format from extension)
results = diffx.diff_files('old.json', 'new.json')
results = diffx.diff_files('config1.yaml', 'config2.yaml', epsilon=0.1)

# Compare strings
json1 = '{"name": "Alice", "age": 30}'
json2 = '{"name": "Alice", "age": 31}'
results = diffx.diff_strings(json1, json2, 'json')

API Reference

diff(old, new, **kwargs)

Compare two values and return differences.

Options (kwargs):

Returns: List of diff results:

# For Added/Removed:
{"type": "Added", "path": "key", "value": ...}
{"type": "Removed", "path": "key", "value": ...}

# For Modified/TypeChanged:
{"type": "Modified", "path": "key", "old_value": ..., "new_value": ...}
{"type": "TypeChanged", "path": "key", "old_value": ..., "new_value": ...}

Parsers

• parse_json(content: str) -> Any
• parse_yaml(content: str) -> Any
• parse_toml(content: str) -> dict
• parse_csv(content: str) -> list[dict]
• parse_ini(content: str) -> dict
• parse_xml(content: str) -> dict

Utility Functions

• format_output(results: list, format: str) -> str - Format diff results as string
• diff_files(file1: str, file2: str, **kwargs) -> list - Compare two files
• diff_strings(str1: str, str2: str, format: str, **kwargs) -> list - Compare two strings

Exception

• DiffError - Raised when diff operations fail

Development

# Setup
uv sync --all-extras

# Build
uv run maturin develop

# Test
uv run pytest -v

# Format & Lint
cargo fmt --check
cargo clippy

License

MIT