json-diff-lite 0.4.0
A minimal, zero-dependency library for comparing JSON objects with human-readable output
Requires Python: >=3.10
Keywords: compare, debugging, diff, json

# json-diff-lite

A minimal, zero-dependency Python library for comparing JSON objects with human-readable output.

## Why?

Existing JSON diff libraries have their drawbacks:

| Library | Issue |
|---------|-------|
| **deepdiff** | Powerful but heavy, complex output |
| **jsondiff** | Unintuitive API, hard to interpret results |
| **dictdiffer** | Output as technical tuples, not human-friendly |
| **difflib** | Operates on strings, not structured JSON |

**json-diff-lite** is designed to be:
- Zero dependencies
- Minimal API
- Human-readable output
- Perfect for logs, debugging, and CI

## Installation

```bash
pip install json-diff-lite
```

## Usage

```python
from json_diff_lite import diff

old = {
    "name": "Ana",
    "age": 30,
    "address": {"street": "Rua A", "number": 100}
}

new = {
    "name": "Ana Maria",
    "age": 31,
    "address": {"street": "Rua B", "number": 100}
}

changes = diff(old, new)
for change in changes:
    print(change)
```

Output:
```
~ address.street: 'Rua A' -> 'Rua B'
~ age: 30 -> 31
~ name: 'Ana' -> 'Ana Maria'
```

### Output format

- `+` key: value — Added
- `- `key: value — Removed
- `~` key: old -> new — Modified

### Smart list matching

By default, lists are compared by index. Use `list_key` to match items by a field:

```python
old = {"users": [{"id": 1, "name": "Ana"}, {"id": 2, "name": "Bob"}]}
new = {"users": [{"id": 2, "name": "Bob"}, {"id": 1, "name": "Ana Maria"}]}

# Without list_key (compares by index - shows many false changes)
diff(old, new)

# With list_key (matches by id field)
changes = diff(old, new, list_key="id")
for change in changes:
    print(change)
```

Output:
```
~ users[id=1].name: 'Ana' -> 'Ana Maria'
```

You can also provide multiple keys as fallback:

```python
diff(old, new, list_key=["id", "name", "key"])
```

### Supported types

- Dicts (recursive)
- Lists (index-based or key-based comparison)
- Primitives: `str`, `int`, `float`, `bool`, `None`

## CLI

Compare JSON files directly from the command line:

```bash
json-diff-lite file1.json file2.json
```

Options:
- `-q, --quiet` — Exit with code 1 if differences found, no output
- `--no-color` — Disable colored output
- `-v, --version` — Show version

Colors are automatically enabled when outputting to a terminal:
- Green for additions (`+`)
- Red for removals (`-`)
- Yellow for modifications (`~`)

Exit codes:
- `0` — No differences (or version shown)
- `1` — Differences found
- `2` — Error (file not found, invalid JSON)

## Limitations

Current version (v0.4.0) does **not** support:

- Custom objects
- Unordered comparison tolerance

These features may be added in future releases.

## Development

```bash
# Clone the repository
git clone https://github.com/nilerbarcelos/json-diff-lite.git
cd json-diff-lite

# Install dev dependencies
pip install hatch

# Run tests
hatch run test:run
```

## Roadmap

### v0.1.0 — MVP
- Basic diff for dict/list/primitives
- Human-readable output
- Tests

### v0.2.0 — CLI
- Command-line interface
- Quiet mode for CI

### v0.3.0 — Colored output
- ANSI colors (auto-detected)
- `--no-color` flag

### v0.4.0 — Smart list diffing (current)
- Match list items by key field (`list_key` parameter)
- Support for multiple fallback keys

## License

MIT