0
# Result Management
1
2
Data structures and enumerations for handling search results from username lookups. The result management system provides structured representations of query outcomes with comprehensive metadata about each search operation.
3
4
## Capabilities
5
6
### Query Status Enumeration
7
8
Enumeration that represents the possible outcomes of a username search on a social media platform.
9
10
```python { .api }
11
class QueryStatus(Enum):
12
"""
13
Query Status Enumeration for username detection results.
14
"""
15
CLAIMED = "Claimed" # Username detected/exists on the platform
16
AVAILABLE = "Available" # Username not detected/available for registration
17
UNKNOWN = "Unknown" # Error occurred while trying to detect username
18
ILLEGAL = "Illegal" # Username format not allowable for this site
19
WAF = "WAF" # Request blocked by Web Application Firewall
20
21
def __str__(self) -> str:
22
"""
23
Convert status to string representation.
24
25
Returns:
26
String value of the status
27
"""
28
```
29
30
### Query Result Object
31
32
Container object that holds comprehensive information about the result of a username query on a specific platform.
33
34
```python { .api }
35
class QueryResult:
36
"""
37
Query Result Object containing information about username detection on a site.
38
"""
39
40
def __init__(
41
self,
42
username: str,
43
site_name: str,
44
site_url_user: str,
45
status: QueryStatus,
46
query_time: float = None,
47
context: str = None
48
):
49
"""
50
Create Query Result Object.
51
52
Args:
53
username: String indicating username that query result was about
54
site_name: String which identifies the site
55
site_url_user: String containing URL for username on site
56
(NOTE: may or may not exist - indicates what the URL would be)
57
status: QueryStatus enumeration indicating the status of the query
58
query_time: Time in seconds required to perform query (optional)
59
context: String indicating additional context about the query,
60
such as error details (optional)
61
"""
62
63
# Attributes set by constructor
64
username: str # Username that was searched
65
site_name: str # Name of the social media site
66
site_url_user: str # Full URL where the user profile would be located
67
status: QueryStatus # Result status of the query
68
query_time: float # Time taken for the query in seconds (may be None)
69
context: str # Additional context information (may be None)
70
71
def __str__(self) -> str:
72
"""
73
Convert Object to String representation.
74
75
Returns:
76
Nicely formatted string with status and context information
77
"""
78
```
79
80
## Types
81
82
### Status Values
83
84
The QueryStatus enum provides these specific status values:
85
86
- **CLAIMED**: Username exists on the platform - account was found
87
- **AVAILABLE**: Username does not exist on the platform - available for registration
88
- **UNKNOWN**: An error occurred during the check (network issue, site down, etc.)
89
- **ILLEGAL**: The username format is not valid for this particular site
90
- **WAF**: Request was blocked by a Web Application Firewall (like Cloudflare)
91
92
### Result Dictionary Structure
93
94
When the main `sherlock()` function returns results, each site result contains:
95
96
```python { .api }
97
ResultDict = {
98
"url_main": str, # Main homepage URL of the site
99
"url_user": str, # Full URL to the user's profile page
100
"status": QueryResult, # QueryResult object with detailed information
101
"http_status": int, # HTTP status code from the request
102
"response_text": str # Raw response text (may be None on errors)
103
}
104
```
105
106
## Usage Examples
107
108
### Basic Result Processing
109
110
```python
111
from sherlock_project.sherlock import sherlock
112
from sherlock_project.result import QueryStatus
113
from sherlock_project.notify import QueryNotifyPrint
114
from sherlock_project.sites import SitesInformation
115
116
# Perform search
117
sites = SitesInformation()
118
notify = QueryNotifyPrint()
119
results = sherlock("john_doe", sites.sites, notify)
120
121
# Process results by status
122
claimed_accounts = []
123
available_usernames = []
124
errors = []
125
126
for site_name, result_data in results.items():
127
result = result_data['status'] # This is a QueryResult object
128
129
if result.status == QueryStatus.CLAIMED:
130
claimed_accounts.append({
131
'site': site_name,
132
'url': result.site_url_user,
133
'response_time': result.query_time
134
})
135
elif result.status == QueryStatus.AVAILABLE:
136
available_usernames.append(site_name)
137
elif result.status in [QueryStatus.UNKNOWN, QueryStatus.WAF]:
138
errors.append({
139
'site': site_name,
140
'error': result.context,
141
'status': result.status.value
142
})
143
144
print(f"Found accounts: {len(claimed_accounts)}")
145
print(f"Available on: {len(available_usernames)} sites")
146
print(f"Errors: {len(errors)}")
147
```
148
149
### Filtering Results by Response Time
150
151
```python
152
# Find accounts with fast response times (under 500ms)
153
fast_results = []
154
155
for site_name, result_data in results.items():
156
result = result_data['status']
157
if (result.status == QueryStatus.CLAIMED and
158
result.query_time and result.query_time < 0.5):
159
fast_results.append({
160
'site': site_name,
161
'username': result.username,
162
'url': result.site_url_user,
163
'time': result.query_time
164
})
165
166
# Sort by response time
167
fast_results.sort(key=lambda x: x['time'])
168
```
169
170
### Creating Custom Result Objects
171
172
```python
173
from sherlock_project.result import QueryResult, QueryStatus
174
175
# Create a custom result (e.g., for testing or custom site checking)
176
custom_result = QueryResult(
177
username="test_user",
178
site_name="CustomSite",
179
site_url_user="https://customsite.com/user/test_user",
180
status=QueryStatus.CLAIMED,
181
query_time=0.234,
182
context="Account verified"
183
)
184
185
print(f"Result: {custom_result}") # Uses __str__ method
186
print(f"Status: {custom_result.status}")
187
print(f"URL: {custom_result.site_url_user}")
188
```
189
190
### Error Handling with Context
191
192
```python
193
# Process results with detailed error information
194
for site_name, result_data in results.items():
195
result = result_data['status']
196
197
if result.status == QueryStatus.UNKNOWN:
198
print(f"Error on {site_name}: {result.context}")
199
elif result.status == QueryStatus.WAF:
200
print(f"Blocked by WAF on {site_name} - consider using proxy")
201
elif result.status == QueryStatus.ILLEGAL:
202
print(f"Username format invalid for {site_name}")
203
```
204
205
### Export Results to Different Formats
206
207
```python
208
import json
209
import csv
210
211
# Export claimed accounts to JSON
212
claimed_data = []
213
for site_name, result_data in results.items():
214
result = result_data['status']
215
if result.status == QueryStatus.CLAIMED:
216
claimed_data.append({
217
'username': result.username,
218
'site_name': result.site_name,
219
'profile_url': result.site_url_user,
220
'response_time_ms': round(result.query_time * 1000) if result.query_time else None,
221
'found_at': result_data.get('timestamp') # If you add timestamps
222
})
223
224
# Save to JSON
225
with open('sherlock_results.json', 'w') as f:
226
json.dump(claimed_data, f, indent=2)
227
228
# Save to CSV
229
with open('sherlock_results.csv', 'w', newline='') as f:
230
if claimed_data:
231
writer = csv.DictWriter(f, fieldnames=claimed_data[0].keys())
232
writer.writeheader()
233
writer.writerows(claimed_data)
234
```