A Python tool to perform deep comparisons of complex data structures (dictionaries, lists, sets) and identify differences. Inspired by the npm package deep-diff.
- 🔍 Deep Comparison: Compare nested dictionaries, lists, and sets
- 📊 Detailed Diff Output: Get structured difference records with paths to changed elements
- 🎯 Exception Paths: Exclude specific paths from comparison
- 🏷️ Type-Safe: Full type hints for better IDE support
- ✨ Modern Python: Requires Python 3.8+
pip install deep-diffFor development:
pip install -e ".[dev]"from deep_diff import diff
result = diff(
{'a': 1, 'c': 1},
{'b': 1, 'c': 1}
)
print(result)
# Output:
# [{'kind': 'D', 'path': ['a'], 'lhs': 1},
# {'kind': 'N', 'path': ['b'], 'rhs': 1}]from deep_diff import diff
result = diff(
{'a': 1, 'c': 1},
{'b': 1, 'c': 1},
exceptions=[['a'], ['b']]
)
print(result) # None - all differences are excludedEach difference record contains:
| Field | Type | Description |
|---|---|---|
kind |
str | Type of change: 'N' (new), 'D' (deleted), 'E' (edited), 'A' (array change) |
path |
list | Path to the changed property (e.g., ['user', 'name']) |
lhs |
any | Left-hand side value (undefined if kind == 'N') |
rhs |
any | Right-hand side value (undefined if kind == 'D') |
index |
int | Array index (only when kind == 'A') |
item |
dict | Nested change record (only when kind == 'A') |
'N'- New property/element added'D'- Property/element deleted'E'- Property/element edited/modified'A'- Change within an array element at specific index
from deep_diff import diff
# Modified value
diff({'a': 1}, {'a': 2})
# [{'kind': 'E', 'path': ['a'], 'lhs': 1, 'rhs': 2}]
# Nested structure
diff(
{'user': {'name': 'Alice', 'age': 30}},
{'user': {'name': 'Alice', 'age': 31}}
)
# [{'kind': 'E', 'path': ['user', 'age'], 'lhs': 30, 'rhs': 31}]from deep_diff import diff
# Modified element
diff([1, 2, 3], [1, 5, 3])
# [{'kind': 'E', 'path': [1], 'lhs': 2, 'rhs': 5}]
# Added element
diff([1, 2], [1, 2, 3])
# [{'kind': 'A', 'path': [], 'index': 2, 'item': {'kind': 'N', 'rhs': 3}}]from deep_diff import diff
# Added elements
diff({1, 2}, {1, 2, 3})
# [{'kind': 'N', 'path': [], 'rhs': {3}}]
# Removed elements
diff({1, 2, 3}, {2, 3})
# [{'kind': 'D', 'path': [], 'lhs': {1}}]from deep_diff import diff
result = diff(
{
'name': 'my object',
'details': {'with': ['elements']}
},
{
'name': 'updated object',
'details': {'with': ['more', 'elements']}
}
)
# Returns detailed differences for each levelCompare two items and return their differences.
Parameters:
item1(any): The first item to compareitem2(any): The second item to compareexceptions(list, optional): List of paths to exclude from comparison. Each path is a list of keys/indices.
Returns:
Noneif items are equal- List of difference records if differences exist
Example:
from deep_diff import diff
# Equal items
diff([1, 2, 3], [1, 2, 3]) # Returns None
# Different items
diff([1, 2, 3], [1, 2, 4])
# [{'kind': 'E', 'path': [2], 'lhs': 3, 'rhs': 4}]
# With exceptions
diff(
{'a': 1, 'b': 2},
{'a': 10, 'b': 20},
exceptions=[['a']]
)
# [{'kind': 'E', 'path': ['b'], 'lhs': 2, 'rhs': 20}]# Clone the repository
git clone https://github.com/ider-zh/diff.git
cd diff
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install with development dependencies
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage report
pytest --cov=deep_diff
# Run specific test file
pytest tests/test_deep_diff.py::TestDictDifferences# Format code with black
black deep_diff tests
# Lint with ruff
ruff check deep_diff tests
# Type checking with mypy
mypy deep_diffBSD 3-Clause License - see LICENSE file for details
ider - GitHub
Email: [email protected]
Contributions are welcome! Please feel free to submit a Pull Request.
- Complete modernization of the codebase
- Added full type hints
- Migrated to pyproject.toml
- Moved to pytest for testing
- Added comprehensive test suite
- Improved documentation
- Added GitHub Actions CI/CD
- Better code quality with ruff and black