0
# Deep Search and Grep
1

2
Search for objects within nested data structures using flexible matching criteria. Provides both class-based search functionality and pipe-friendly grep operations for finding specific values, patterns, or objects within complex Python data structures.
3

4
## Capabilities
5

6
### Deep Search
7

8
Search for items within nested Python objects with configurable matching options and path filtering.
9

10
```python { .api }
11
class DeepSearch:
12
    def __init__(
13
        self,
14
        obj: Any,
15
        item: Any,
16
        exclude_paths: Union[SetOrdered, Set[str], List[str]] = SetOrdered(),
17
        exclude_regex_paths: Union[SetOrdered, Set[Union[str, Pattern[str]]], List[Union[str, Pattern[str]]]] = SetOrdered(),
18
        exclude_types: Union[SetOrdered, Set[type], List[type]] = SetOrdered(),
19
        verbose_level: int = 1,
20
        case_sensitive: bool = False,
21
        match_string: bool = False,
22
        use_regexp: bool = False,
23
        strict_checking: bool = True,
24
        **kwargs
25
    ):
26
    """
27
    Search for objects within nested data structures.
28
    
29
    Parameters:
30
    - obj: Object to search within
31
    - item: Item to search for
32
    - exclude_paths: Paths to exclude from search
33
    - exclude_regex_paths: Regex patterns for paths to exclude
34
    - exclude_types: Types to exclude from search
35
    - verbose_level: Level of detail in output (0-2)
36
    - case_sensitive: Whether string matching should be case sensitive (default False)
37
    - match_string: Whether to match strings partially or exactly
38
    - use_regexp: Whether to treat search item as regular expression
39
    - strict_checking: Use strict type checking for matches
40
    """
41
```
42

43
### Search Result Analysis
44

45
Methods for analyzing search results and extracting information about found matches.
46

47
```python { .api }
48
def get_stats(self) -> Dict[str, Any]:
49
    """
50
    Get statistics about the search results.
51
    
52
    Returns:
53
    Dict containing search statistics including match counts and coverage information.
54
    """
55

56
def get_paths(self) -> List[str]:
57
    """
58
    Get list of all paths where matches were found.
59
    
60
    Returns:
61
    List of path strings indicating where matches were found.
62
    """
63
```
64

65
### Grep Function
66

67
Pipe-friendly search function that can be used with the | operator for functional-style searching.
68

69
```python { .api }
70
class grep:
71
    def __init__(self, item: Any, **kwargs: Any) -> None:
72
        """
73
        Create a pipe-friendly search object.
74
        
75
        Parameters:
76
        - item: Item to search for
77
        - **kwargs: Same parameters as DeepSearch class
78
        """
79
    
80
    def __ror__(self, other: Any) -> "DeepSearch":
81
        """
82
        Support for | operator piping.
83
        
84
        Usage:
85
        result = data | grep("search_term")
86
        
87
        Parameters:
88
        - other: Object to search within
89
        
90
        Returns:
91
        DeepSearch result object
92
        """
93
```
94

95
## Usage Examples
96

97
### Basic Search
98

99
```python
100
from deepdiff import DeepSearch
101

102
# Search for a value in nested structure
103
data = {
104
    "users": [
105
        {"id": 1, "name": "John", "email": "john@example.com"},
106
        {"id": 2, "name": "Jane", "email": "jane@example.com"}
107
    ],
108
    "settings": {"theme": "dark", "language": "en"}
109
}
110

111
# Search for specific value
112
search = DeepSearch(data, "John")
113
print(search)
114
# {'matched_values': {"root['users'][0]['name']"}}
115

116
# Search for partial string match
117
search = DeepSearch(data, "john", case_sensitive=False, match_string=True)
118
print(search)
119
# Finds both "John" and "john@example.com"
120
```
121

122
### Regular Expression Search
123

124
```python
125
import re
126

127
# Search using regular expressions
128
email_pattern = re.compile(r'[\w\.-]+@[\w\.-]+\.\w+')
129
search = DeepSearch(data, email_pattern, use_regexp=True)
130
print(search)
131
# Finds all email addresses in the data structure
132
```
133

134
### Path Filtering
135

136
```python
137
# Exclude specific paths from search
138
search = DeepSearch(
139
    data, 
140
    "John", 
141
    exclude_paths=["root['users'][0]['email']"]
142
)
143

144
# Include only specific paths
145
search = DeepSearch(
146
    data,
147
    "dark",
148
    include_paths=["root['settings']"]
149
)
150
```
151

152
### Grep with Pipe Operator
153

154
```python
155
from deepdiff import grep
156

157
# Functional-style searching with pipe operator
158
result = data | grep("John")
159
print(result)
160

161
# Chain multiple operations
162
result = data | grep("@", match_string=True) | len
163
print(f"Found {result} email addresses")
164

165
# Search with options
166
result = data | grep("JOHN", case_sensitive=False)
167
```
168

169
### Type-Based Exclusion
170

171
```python
172
# Exclude certain types from search
173
data_with_numbers = {
174
    "name": "John",
175
    "age": 30,
176
    "scores": [85, 90, 95],
177
    "metadata": {"created": 2023}
178
}
179

180
# Search excluding numeric types
181
search = DeepSearch(
182
    data_with_numbers,
183
    30,
184
    exclude_types=[int, float]
185
)
186
```
187

188
### Working with Search Results
189

190
```python
191
search = DeepSearch(data, "John")
192

193
# Get detailed statistics
194
stats = search.get_stats()
195
print(f"Total matches: {stats['total_matches']}")
196
print(f"Matched paths: {stats['matched_paths']}")
197

198
# Get all paths where matches were found
199
paths = search.get_paths()
200
for path in paths:
201
    print(f"Found match at: {path}")
202

203
# Access the raw results
204
if 'matched_values' in search:
205
    for path, value in search['matched_values'].items():
206
        print(f"At {path}: {value}")
207
```
208

209
### Advanced Search Options
210

211
```python
212
# Return paths instead of values
213
search = DeepSearch(data, "John", return_paths=True)
214

215
# Verbose output for debugging
216
search = DeepSearch(data, "John", verbose_level=2)
217

218
# Strict type checking
219
search = DeepSearch(data, 1, strict_checking=True)  # Only matches exactly int(1)
220
search = DeepSearch(data, 1, strict_checking=False)  # Matches 1, 1.0, "1", etc.
221
```
222

223
## Types
224

225
```python { .api }
226
# Search result structure
227
SearchResult = Dict[str, Dict[str, Any]]
228

229
# Possible result keys:
230
# - 'matched_values': Dict mapping paths to found values
231
# - 'matched_paths': Dict mapping paths to match information  
232
# - 'unmatched_paths': Dict of paths that didn't match
233

234
# Grep function type
235
GrepFunction = Callable[[Any], SearchResult]
236

237
# Search statistics type
238
SearchStats = Dict[str, Union[int, List[str], Dict[str, Any]]]
239
```