0
# DeepDiff
1

2
DeepDiff is a comprehensive Python library for analyzing differences, searching, and hashing complex data structures and objects. It provides advanced comparison capabilities beyond basic equality checks, offering detailed reporting of changes between dictionaries, lists, strings, and any Python objects. The library features multiple core modules for deep difference analysis, object searching, content-based hashing, delta storage and application, and path-based extraction from nested structures.
3

4
## Package Information
5

6
- **Package Name**: deepdiff
7
- **Language**: Python  
8
- **Installation**: `pip install deepdiff`
9
- **Optional Dependencies**: `pip install deepdiff[cli]` for command-line usage, `pip install deepdiff[optimize]` for performance optimizations
10

11
## Core Imports
12

13
```python
14
from deepdiff import DeepDiff, DeepSearch, DeepHash, Delta, extract, parse_path, grep
15
```
16

17
## Basic Usage
18

19
```python
20
from deepdiff import DeepDiff, DeepSearch, DeepHash, Delta, extract
21

22
# Deep difference analysis
23
t1 = {"name": "John", "age": 30, "hobbies": ["reading", "gaming"]}
24
t2 = {"name": "John", "age": 31, "hobbies": ["reading", "coding"]}
25

26
diff = DeepDiff(t1, t2)
27
print(diff)
28
# {'values_changed': {"root['age']": {'old_value': 30, 'new_value': 31}}, 
29
#  'iterable_item_added': {"root['hobbies'][1]": 'coding'}, 
30
#  'iterable_item_removed': {"root['hobbies'][1]": 'gaming'}}
31

32
# Deep search within nested structures
33
data = {"users": [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]}
34
search = DeepSearch(data, "John")
35
print(search)
36
# {'matched_values': {"root['users'][0]['name']"}}
37

38
# Content-based hashing
39
hash1 = DeepHash({"a": 1, "b": 2})
40
hash2 = DeepHash({"b": 2, "a": 1})  # Same content, different order
41
print(hash1 == hash2)  # True
42

43
# Delta creation and application
44
delta = Delta(diff)
45
t3 = delta + t1  # Apply delta to original object
46
print(t3 == t2)  # True
47

48
# Path-based extraction
49
nested_data = {"level1": {"level2": {"target": "found"}}}
50
value = extract(nested_data, "root['level1']['level2']['target']")
51
print(value)  # "found"
52
```
53

54
## Architecture
55

56
The DeepDiff library is built around five core capabilities that work together to provide comprehensive object analysis:
57

58
- **DeepDiff**: The primary comparison engine that analyzes differences between objects with extensive customization options
59
- **DeepSearch**: Search functionality for finding objects within nested data structures
60
- **DeepHash**: Content-based hashing system that generates consistent hashes regardless of object organization
61
- **Delta**: Difference storage and application system for creating patches and applying changes
62
- **Extract**: Path-based navigation system for retrieving values from deeply nested structures
63

64
All classes inherit from common base classes providing serialization, distance calculation, and other shared functionality.
65

66
## Capabilities
67

68
### Deep Difference Analysis
69

70
Comprehensive comparison of Python objects with detailed change reporting. Supports extensive customization through 40+ parameters including type handling, path filtering, numerical precision, and output formatting.
71

72
```python { .api }
73
class DeepDiff:
74
    def __init__(
75
        self,
76
        t1: Any,
77
        t2: Any,
78
        ignore_order: bool = False,
79
        ignore_string_case: bool = False,
80
        ignore_numeric_type_changes: bool = False,
81
        ignore_type_in_groups: List[Tuple[type, ...]] = None,
82
        significant_digits: int = None,
83
        exclude_paths: List[str] = None,
84
        exclude_regex_paths: List[str] = None,
85
        exclude_types: List[type] = None,
86
        include_paths: List[str] = None,
87
        custom_operators: List = None,
88
        view: str = 'text',
89
        verbose_level: int = 1,
90
        **kwargs
91
    ): ...
92
    
93
    def get_stats(self) -> Dict[str, Any]: ...
94
    def get_affected_paths(self) -> List[str]: ...
95
    def to_json(self) -> str: ...
96
    def from_json(self, json_string: str) -> 'DeepDiff': ...
97
```
98

99
[Deep Difference Analysis](./difference.md)
100

101
### Deep Search and Grep
102

103
Search for objects within nested data structures using flexible matching criteria. Includes both class-based search and pipe-friendly grep functionality.
104

105
```python { .api }
106
class DeepSearch:
107
    def __init__(
108
        self,
109
        obj: Any,
110
        item: Any,
111
        exclude_paths: List[str] = None,
112
        exclude_regex_paths: List[str] = None,
113
        exclude_types: List[type] = None,
114
        verbose_level: int = 1,
115
        case_sensitive: bool = True,
116
        match_string: bool = False,
117
        use_regexp: bool = False,
118
        **kwargs
119
    ): ...
120
    
121
    def get_stats(self) -> Dict[str, Any]: ...
122
    def get_paths(self) -> List[str]: ...
123

124
def grep(item: Any, **kwargs) -> Callable: ...
125
```
126

127
[Deep Search and Grep](./search.md)
128

129
### Deep Hashing
130

131
Content-based hashing that generates consistent hashes for objects regardless of key ordering or minor structural differences. Supports custom hash functions and extensive filtering options.
132

133
```python { .api }
134
class DeepHash:
135
    def __init__(
136
        self,
137
        obj: Any,
138
        hasher: Any = None,
139
        ignore_type_in_groups: List[Tuple[type, ...]] = None,
140
        ignore_encoding_errors: bool = False,
141
        ignore_numeric_type_changes: bool = False,
142
        significant_digits: int = None,
143
        exclude_types: List[type] = None,
144
        exclude_paths: List[str] = None,
145
        **kwargs
146
    ): ...
147
    
148
    def get(self, path: str = None) -> str: ...
149
    def hexdigest(self) -> str: ...
150
```
151

152
[Deep Hashing](./hashing.md)
153

154
### Delta Operations
155

156
Store differences as delta objects and apply them to create new objects or modify existing ones. Supports multiple serialization formats and bidirectional operations.
157

158
```python { .api }
159
class Delta:
160
    def __init__(
161
        self,
162
        diff: Union['DeepDiff', Dict],
163
        mutate: bool = False,
164
        log_errors: bool = False,
165
        safe_to_import: List[str] = None,
166
        bidirectional: bool = False
167
    ): ...
168
    
169
    def dump(self, file_path: str, **kwargs) -> None: ...
170
    def dumps(self, **kwargs) -> str: ...
171
    def load(self, file_path: str, **kwargs) -> 'Delta': ...
172
    def loads(self, string: str, **kwargs) -> 'Delta': ...
173
    def apply_to(self, obj: Any) -> Any: ...
174
    def create_new_from(self, obj: Any) -> Any: ...
175
```
176

177
[Delta Operations](./delta.md)
178

179
### Path Extraction and Parsing
180

181
Navigate and extract values from deeply nested Python objects using string-based path notation. Includes both extraction and path parsing utilities.
182

183
```python { .api }
184
def extract(obj: Any, path: Union[str, List]) -> Any:
185
    """Extract item from nested object using path notation."""
186

187
def parse_path(path: str) -> List:
188
    """Parse path string to machine-readable format."""
189
```
190

191
[Path Operations](./extract.md)
192

193
### Command Line Interface
194

195
Full-featured CLI providing access to all core functionality through command-line tools with extensive options and output formatting.
196

197
```bash { .api }
198
# Compare objects from files or command line
199
deep diff file1.json file2.json
200

201
# Search within objects  
202
deep grep "search_term" data.json
203

204
# Extract values using paths
205
deep extract "root['key']['subkey']" data.json
206

207
# Apply delta patches
208
deep patch original.json delta.json
209
```
210

211
[Command Line Interface](./cli.md)
212

213
## Exception Classes
214

215
```python { .api }
216
class DeltaError(ValueError):
217
    """Exception raised during Delta operations."""
218

219
class DeltaNumpyOperatorOverrideError(ValueError):
220
    """Exception raised when Delta NumPy operator override fails."""
221

222
class PathExtractionError(ValueError):
223
    """Exception raised during path extraction operations."""
224

225
class RootCanNotBeModified(ValueError):
226
    """Exception raised when attempting to modify root in path operations."""
227

228
class UnsupportedFormatErr(TypeError):
229
    """Exception raised for unsupported serialization formats."""
230

231
class CannotCompare(Exception):
232
    """Exception raised when objects cannot be compared."""
233

234
class DoesNotExist(Exception):
235
    """Exception raised when a required object does not exist."""
236
```
237

238
## Common Types
239

240
```python { .api }
241
# Result types used across multiple modules
242
TreeResult = Dict[str, Any]
243
DiffLevel = Dict[str, Any]
244

245
# Path types
246
PathStr = str
247
PathList = List[Union[str, int]]
248

249
# Comparison customization types
250
CustomOperator = Callable
251
TypeGroup = Tuple[type, ...]
252
HashFunction = Callable[[Any], str]
253
```