0
# Core Search Engine
1

2
The main search functionality that orchestrates username lookups across multiple social networks and platforms. The core engine provides efficient concurrent searching with extensive configuration options for different use cases.
3

4
## Capabilities
5

6
### Main Search Function
7

8
The primary function that performs username searches across social media sites with concurrent HTTP requests and comprehensive result tracking.
9

10
```python { .api }
11
def sherlock(
12
    username: str,
13
    site_data: dict,
14
    query_notify: QueryNotify,
15
    tor: bool = False,
16
    unique_tor: bool = False,
17
    dump_response: bool = False,
18
    proxy=None,
19
    timeout=60,
20
) -> dict:
21
    """
22
    Run Sherlock Analysis to check for username existence across social media sites.
23
    
24
    Args:
25
        username: String indicating username to search for
26
        site_data: Dictionary containing all site data (SiteInformation objects)
27
        query_notify: Object with base type QueryNotify() for result notifications
28
        tor: Boolean indicating whether to use Tor circuit (deprecated)
29
        unique_tor: Boolean indicating whether to use unique Tor circuit per request (deprecated)
30
        dump_response: Boolean indicating whether to dump HTTP response data
31
        proxy: String indicating proxy URL or None
32
        timeout: Time in seconds to wait before timing out request (default 60)
33
        
34
    Returns:
35
        Dictionary containing results from report. Key is site name, value is dict with:
36
        - url_main: URL of main site
37
        - url_user: URL of user on site (if account exists)  
38
        - status: QueryResult() object indicating test results
39
        - http_status: HTTP status code of query
40
        - response_text: Text from request (may be None on HTTP error)
41
    """
42
```
43

44
### Enhanced HTTP Session
45

46
Custom HTTP session class that extends FuturesSession to add response timing metrics for performance analysis.
47

48
```python { .api }
49
class SherlockFuturesSession(FuturesSession):
50
    def request(
51
        self,
52
        method: str,
53
        url: str,
54
        hooks: dict = None,
55
        *args,
56
        **kwargs
57
    ):
58
        """
59
        Request URL with response time measurement.
60
        
61
        Extends FuturesSession request method to calculate response time metric.
62
        
63
        Args:
64
            method: String containing HTTP method for request
65
            url: String containing URL for request
66
            hooks: Dictionary containing hooks to execute after request finishes
67
            args: Additional arguments
68
            kwargs: Additional keyword arguments
69
            
70
        Returns:
71
            Request object with elapsed time attached to response
72
        """
73
```
74

75
### Username Utilities
76

77
Helper functions for username processing and validation.
78

79
```python { .api }
80
def interpolate_string(input_object, username: str):
81
    """
82
    Replace {} placeholder with username in strings.
83
    
84
    Args:
85
        input_object: String or other object to interpolate
86
        username: Username to substitute
87
        
88
    Returns:
89
        String with {} replaced by username, or original object if not string
90
    """
91

92
def check_for_parameter(username: str) -> bool:
93
    """
94
    Check if {?} parameter exists in username.
95
    
96
    Indicates if sherlock is looking for multiple username variations.
97
    
98
    Args:
99
        username: Username string to check
100
        
101
    Returns:
102
        Boolean indicating if parameter syntax found
103
    """
104

105
def multiple_usernames(username: str) -> list:
106
    """
107
    Replace parameter syntax with symbols and return list of usernames.
108
    
109
    Args:
110
        username: Username with parameter syntax
111
        
112
    Returns:
113
        List of username variations
114
    """
115
```
116

117
### Response Processing
118

119
Low-level function for processing HTTP request futures and handling errors.
120

121
```python { .api }
122
def get_response(request_future, error_type: str, social_network: str):
123
    """
124
    Get response from request future with error handling.
125
    
126
    Args:
127
        request_future: Future object from HTTP request
128
        error_type: String describing type of error expected
129
        social_network: String name of social network being queried
130
        
131
    Returns:
132
        Response object or None if error occurred
133
    """
134
```
135

136
### CLI Functions
137

138
Command-line interface utilities and validation.
139

140
```python { .api }
141
def main():
142
    """
143
    Main CLI entry point function.
144
    
145
    Handles argument parsing, site loading, username validation,
146
    and orchestrates the search process with appropriate output formatting.
147
    """
148

149
def timeout_check(value: str) -> float:
150
    """
151
    Check and validate timeout argument.
152
    
153
    Args:
154
        value: String value from command line argument
155
        
156
    Returns:
157
        Float timeout value in seconds
158
        
159
    Raises:
160
        ArgumentTypeError: If value is invalid
161
    """
162

163
def handler(signal_received, frame):
164
    """
165
    Signal handler for graceful exit without throwing errors.
166
    
167
    Args:
168
        signal_received: Signal number received
169
        frame: Current stack frame
170
    """
171
```
172

173
## Usage Examples
174

175
### Basic Search
176

177
```python
178
from sherlock_project.sherlock import sherlock
179
from sherlock_project.notify import QueryNotifyPrint
180
from sherlock_project.sites import SitesInformation
181

182
# Load all available sites
183
sites = SitesInformation()
184

185
# Create notification handler
186
notify = QueryNotifyPrint(verbose=True)
187

188
# Perform search
189
results = sherlock("john_doe", sites.sites, notify, timeout=30)
190

191
# Check results
192
for site_name, result in results.items():
193
    if result['status'].status.value == "Claimed":
194
        print(f"Account found: {result['url_user']}")
195
```
196

197
### Search with Proxy
198

199
```python
200
# Use proxy for requests
201
results = sherlock(
202
    "username", 
203
    sites.sites, 
204
    notify,
205
    proxy="http://proxy.example.com:8080",
206
    timeout=45
207
)
208
```
209

210
### Search Subset of Sites
211

212
```python
213
# Search only specific sites
214
site_subset = {
215
    "GitHub": sites.sites["GitHub"],
216
    "Twitter": sites.sites["Twitter"]
217
}
218

219
results = sherlock("username", site_subset, notify)
220
```
221

222
### Processing Multiple Usernames
223

224
```python
225
usernames = ["user1", "user2", "user3"]
226

227
for username in usernames:
228
    print(f"\nSearching for: {username}")
229
    results = sherlock(username, sites.sites, notify)
230
    
231
    # Process results for this username
232
    claimed_accounts = [
233
        result['url_user'] for result in results.values() 
234
        if result['status'].status.value == "Claimed"
235
    ]
236
    
237
    print(f"Found {len(claimed_accounts)} accounts for {username}")
238
```