0
# Deep Difference Analysis
1

2
Comprehensive comparison of Python objects with detailed change reporting and extensive customization options. DeepDiff goes beyond basic equality checks to provide precise analysis of what changed between two objects, including nested structures, lists, dictionaries, and custom objects.
3

4
## Capabilities
5

6
### Object Comparison
7

8
Creates detailed difference reports between any two Python objects with customizable comparison behavior and output formatting.
9

10
```python { .api }
11
class DeepDiff:
12
    def __init__(
13
        self,
14
        t1: Any,
15
        t2: Any,
16
        cache_purge_level: int = 1,
17
        cache_size: int = 0,
18
        cache_tuning_sample_size: int = 0,
19
        custom_operators: Optional[List[Any]] = None,
20
        cutoff_distance_for_pairs: float = 0.6,
21
        cutoff_intersection_for_pairs: float = 0.6,
22
        default_timezone: Union[datetime.timezone, "BaseTzInfo"] = datetime.timezone.utc,
23
        encodings: Optional[List[str]] = None,
24
        exclude_obj_callback: Optional[Callable] = None,
25
        exclude_obj_callback_strict: Optional[Callable] = None,
26
        exclude_paths: Union[str, List[str], Set[str], FrozenSet[str], None] = None,
27
        exclude_regex_paths: Union[str, List[str], Pattern[str], List[Pattern[str]], None] = None,
28
        exclude_types: Optional[List[type]] = None,
29
        get_deep_distance: bool = False,
30
        group_by: Union[str, Tuple[str, str], None] = None,
31
        group_by_sort_key: Union[str, Callable, None] = None,
32
        hasher: Optional[Callable] = None,
33
        hashes: Optional[Dict[Any, Any]] = None,
34
        ignore_encoding_errors: bool = False,
35
        ignore_nan_inequality: bool = False,
36
        ignore_numeric_type_changes: bool = False,
37
        ignore_order: bool = False,
38
        ignore_order_func: Optional[Callable] = None,
39
        ignore_private_variables: bool = True,
40
        ignore_string_case: bool = False,
41
        ignore_string_type_changes: bool = False,
42
        ignore_type_in_groups: Optional[List[Tuple[Any, ...]]] = None,
43
        ignore_type_subclasses: bool = False,
44
        ignore_uuid_types: bool = False,
45
        include_obj_callback: Optional[Callable] = None,
46
        include_obj_callback_strict: Optional[Callable] = None,
47
        include_paths: Union[str, List[str], None] = None,
48
        iterable_compare_func: Optional[Callable] = None,
49
        log_frequency_in_sec: int = 0,
50
        log_scale_similarity_threshold: float = 0.1,
51
        log_stacktrace: bool = False,
52
        math_epsilon: Optional[float] = None,
53
        max_diffs: Optional[int] = None,
54
        max_passes: int = 10000000,
55
        number_format_notation: Literal["f", "e"] = "f",
56
        number_to_string_func: Optional[Callable] = None,
57
        progress_logger: Callable[[str], None] = logger.info,
58
        report_repetition: bool = False,
59
        significant_digits: Optional[int] = None,
60
        threshold_to_diff_deeper: float = 0.33,
61
        truncate_datetime: Optional[str] = None,
62
        use_enum_value: bool = False,
63
        use_log_scale: bool = False,
64
        verbose_level: int = 1,
65
        view: str = 'text',
66
        zip_ordered_iterables: bool = False,
67
        **kwargs
68
    ):
69
    """
70
    Deep difference of dictionaries, iterables, strings and other objects.
71
    
72
    Parameters:
73
    - t1, t2: Objects to compare
74
    - cache_purge_level: Level of cache purging (0-2)
75
    - cache_size: Size of LRU cache for comparison operations
76
    - cache_tuning_sample_size: Sample size for cache tuning
77
    - custom_operators: List of custom comparison operators
78
    - cutoff_distance_for_pairs: Distance threshold for pairing items
79
    - cutoff_intersection_for_pairs: Intersection threshold for pairing
80
    - default_timezone: Default timezone for datetime comparisons
81
    - encodings: List of encodings to try for string comparison
82
    - exclude_obj_callback: Callback function to exclude objects
83
    - exclude_obj_callback_strict: Callback function to exclude objects with strict checking
84
    - exclude_paths: Paths to exclude from comparison
85
    - exclude_regex_paths: Regex patterns for paths to exclude
86
    - exclude_types: List of types to exclude from comparison
87
    - get_deep_distance: Calculate distance metric between objects
88
    - group_by: Group similar changes together
89
    - group_by_sort_key: Sort key for grouping
90
    - hasher: Hash function to use for hashing
91
    - hashes: Pre-computed hashes to use
92
    - ignore_encoding_errors: Ignore encoding errors when comparing strings
93
    - ignore_nan_inequality: Ignore NaN inequality comparisons
94
    - ignore_numeric_type_changes: Ignore type changes between numeric types
95
    - ignore_order: Ignore order of elements in iterables
96
    - ignore_order_func: Function to determine when to ignore order
97
    - ignore_private_variables: Ignore private attributes (starting with _)
98
    - ignore_string_case: Ignore case when comparing strings
99
    - ignore_string_type_changes: Ignore changes between string types
100
    - ignore_type_in_groups: List of type groups to treat as equivalent
101
    - ignore_type_subclasses: Ignore type changes between subclasses
102
    - ignore_uuid_types: Ignore type differences between UUID and string
103
    - include_obj_callback: Callback function to include objects
104
    - include_obj_callback_strict: Callback function to include objects with strict checking
105
    - include_paths: List of paths to include (exclude all others)
106
    - iterable_compare_func: Custom function for comparing iterables
107
    - log_frequency_in_sec: Frequency of progress logging in seconds
108
    - log_scale_similarity_threshold: Threshold for log scale similarity
109
    - log_stacktrace: Log stack traces on errors
110
    - math_epsilon: Epsilon for floating point comparisons
111
    - max_diffs: Maximum number of differences to find
112
    - max_passes: Maximum number of passes for comparison
113
    - number_format_notation: Notation for number formatting ("f" or "e")
114
    - number_to_string_func: Custom function for number to string conversion
115
    - progress_logger: Function for logging progress
116
    - report_repetition: Report repetitive elements
117
    - significant_digits: Number of significant digits for float comparison
118
    - threshold_to_diff_deeper: Threshold for deeper comparison
119
    - truncate_datetime: Truncate datetime to specified precision
120
    - use_enum_value: Use enum values instead of enum objects
121
    - use_log_scale: Use logarithmic scale for similarity
122
    - verbose_level: Level of detail in output (0-2)
123
    - view: Output view format ('text' or 'tree')
124
    - zip_ordered_iterables: Zip iterables when comparing ordered sequences
125
    """
126
```
127

128
### Result Analysis
129

130
Methods for analyzing and extracting information from comparison results.
131

132
```python { .api }
133
def get_stats(self) -> Dict[str, Any]:
134
    """
135
    Get statistics about the comparison results.
136
    
137
    Returns:
138
    Dict containing comparison statistics including counts of different types of changes.
139
    """
140

141
def custom_report_result(self, report_type: str, level: Any, extra_info: Any = None) -> None:
142
    """
143
    Custom report result method for advanced reporting.
144
    
145
    Parameters:
146
    - report_type: Type of report to generate
147
    - level: Level object containing comparison information
148
    - extra_info: Optional extra information for the report
149
    """
150

151
@property
152
def affected_paths(self) -> List[str]:
153
    """
154
    List of paths that were affected by changes.
155
    
156
    Returns:
157
    List of path strings indicating where changes occurred.
158
    """
159

160
@property
161
def affected_root_keys(self) -> List[str]:
162
    """
163
    List of root keys that were affected by changes.
164
    
165
    Returns:
166
    List of root key strings that had changes.
167
    """
168
```
169

170

171
## Usage Examples
172

173
### Basic Comparison
174

175
```python
176
from deepdiff import DeepDiff
177

178
# Compare dictionaries
179
t1 = {"name": "John", "age": 30}
180
t2 = {"name": "Jane", "age": 30}
181

182
diff = DeepDiff(t1, t2)
183
print(diff)
184
# {'values_changed': {"root['name']": {'old_value': 'John', 'new_value': 'Jane'}}}
185
```
186

187
### Ignoring Order
188

189
```python
190
# Compare lists ignoring order
191
list1 = [1, 2, 3]
192
list2 = [3, 2, 1]
193

194
diff = DeepDiff(list1, list2, ignore_order=True)
195
print(diff)
196
# {} (no differences when ignoring order)
197
```
198

199
### Excluding Paths
200

201
```python
202
# Exclude specific paths from comparison
203
t1 = {"name": "John", "age": 30, "id": 1}
204
t2 = {"name": "John", "age": 31, "id": 2}
205

206
diff = DeepDiff(t1, t2, exclude_paths=["root['id']"])
207
print(diff)
208
# Only shows age difference, id difference is excluded
209
```
210

211
### Custom Operators
212

213
```python
214
from deepdiff.operator import BaseOperator
215

216
class CustomOperator(BaseOperator):
217
    def match(self, level):
218
        return "custom_field" in level.t1
219
    
220
    def give_up_diffing(self, level, diff_instance):
221
        # Custom comparison logic
222
        return True
223

224
diff = DeepDiff(t1, t2, custom_operators=[CustomOperator()])
225
```
226

227
### Working with Results
228

229
```python
230
diff = DeepDiff(t1, t2)
231

232
# Get statistics
233
stats = diff.get_stats()
234
print(f"Total changes: {stats['total_changes']}")
235

236
# Get affected paths
237
paths = diff.get_affected_paths()
238
print(f"Changed paths: {paths}")
239

240
# Serialize to JSON
241
json_diff = diff.to_json()
242
# Store or transmit json_diff
243

244
# Recreate from JSON
245
restored_diff = DeepDiff.from_json(json_diff)
246
```
247

248
## Types
249

250
```python { .api }
251
# Custom operator base class
252
class BaseOperator:
253
    def match(self, level: 'DiffLevel') -> bool: ...
254
    def give_up_diffing(self, level: 'DiffLevel', diff_instance: 'DeepDiff') -> bool: ...
255

256
# Level representation for custom operators
257
class DiffLevel:
258
    t1: Any  # First object being compared
259
    t2: Any  # Second object being compared
260
    path: List[str]  # Path to current comparison location
261
    
262
# Type groups for treating different types as equivalent
263
TypeGroup = Tuple[type, ...]
264

265
# Callback types
266
ExcludeCallback = Callable[[Any, str], bool]
267
NumberToStringFunc = Callable[[Any], str]
268
```