0
# Search Operations
1

2
Comprehensive search functionality across repositories, users, issues, code, and commits with advanced filtering, sorting, and pagination support.
3

4
## Capabilities
5

6
### Repository Search
7

8
Search across GitHub repositories with filters for language, size, stars, forks, and more.
9

10
```python { .api }
11
class GitHub:
12
    def search_repositories(self, query, sort="stars", order="desc"):
13
        """
14
        Search for repositories.
15
        
16
        Args:
17
            query (str): Search query with optional qualifiers
18
            sort (str): Sort field ('stars', 'forks', 'help-wanted-issues', 'updated')
19
            order (str): Sort order ('asc', 'desc')
20
            
21
        Returns:
22
            SearchIterator: Iterator of RepositorySearchResult objects
23
        """
24
```
25

26
**Usage Examples:**
27

28
```python
29
import github3
30

31
gh = github3.login(token='your_token')
32

33
# Basic repository search
34
for repo in gh.search_repositories('machine learning python'):
35
    print(f"{repo.full_name} - ⭐ {repo.stargazers_count}")
36

37
# Advanced search with qualifiers
38
for repo in gh.search_repositories('language:python stars:>1000 forks:>100'):
39
    print(f"{repo.full_name} - {repo.description}")
40

41
# Search with specific sorting
42
for repo in gh.search_repositories('web framework', sort='updated', order='desc'):
43
    print(f"{repo.full_name} - Updated: {repo.updated_at}")
44
```
45

46
**Query Qualifiers:**
47
- `language:python` - Repositories in Python
48
- `stars:>100` - More than 100 stars
49
- `forks:10..50` - Between 10-50 forks
50
- `size:>1000` - Repository size > 1000 KB
51
- `created:>2020-01-01` - Created after date
52
- `pushed:>2023-01-01` - Pushed to after date
53
- `user:octocat` - Repositories by user
54
- `org:github` - Repositories by organization
55
- `topic:machine-learning` - Repositories with topic
56

57
### User Search
58

59
Search for GitHub users and organizations.
60

61
```python { .api }
62
class GitHub:
63
    def search_users(self, query, sort="followers", order="desc"):
64
        """
65
        Search for users.
66
        
67
        Args:
68
            query (str): Search query with optional qualifiers
69
            sort (str): Sort field ('followers', 'repositories', 'joined')
70
            order (str): Sort order ('asc', 'desc')
71
            
72
        Returns:
73
            SearchIterator: Iterator of UserSearchResult objects
74
        """
75
```
76

77
**Usage Examples:**
78

79
```python
80
# Basic user search
81
for user in gh.search_users('john smith'):
82
    print(f"{user.login} - {user.html_url}")
83

84
# Search users by location and language
85
for user in gh.search_users('location:sf language:python'):
86
    print(f"{user.login} - Followers: {user.followers}")
87

88
# Search organizations
89
for org in gh.search_users('type:org location:california'):
90
    print(f"{org.login} - {org.company}")
91
```
92

93
**User Query Qualifiers:**
94
- `type:user` or `type:org` - User type
95
- `language:python` - Primary language
96
- `location:california` - Location
97
- `followers:>100` - Follower count
98
- `repos:>10` - Repository count
99
- `created:>2015-01-01` - Account creation date
100

101
### Issue & Pull Request Search
102

103
Search across issues and pull requests with advanced filtering.
104

105
```python { .api }
106
class GitHub:
107
    def search_issues(self, query, sort="created", order="desc"):
108
        """
109
        Search for issues and pull requests.
110
        
111
        Args:
112
            query (str): Search query with optional qualifiers
113
            sort (str): Sort field ('comments', 'reactions', 'interactions', 'created', 'updated')
114
            order (str): Sort order ('asc', 'desc')
115
            
116
        Returns:
117
            SearchIterator: Iterator of IssueSearchResult objects
118
        """
119
```
120

121
**Usage Examples:**
122

123
```python
124
# Search open issues with label
125
for issue in gh.search_issues('is:issue is:open label:bug'):
126
    print(f"#{issue.number}: {issue.title}")
127

128
# Search pull requests by author
129
for pr in gh.search_issues('is:pr author:octocat'):
130
    print(f"PR #{pr.number}: {pr.title}")
131

132
# Search issues in specific repository
133
for issue in gh.search_issues('repo:microsoft/vscode is:issue state:open'):
134
    print(f"#{issue.number}: {issue.title}")
135

136
# Search by date range
137
for issue in gh.search_issues('is:issue created:2023-01-01..2023-12-31'):
138
    print(f"#{issue.number}: {issue.title} - {issue.created_at}")
139
```
140

141
**Issue Query Qualifiers:**
142
- `type:issue` or `type:pr` - Issue type
143
- `is:open` or `is:closed` - State
144
- `author:username` - Issue author
145
- `assignee:username` - Assigned user
146
- `mentions:username` - User mentioned
147
- `label:bug` - Issues with label
148
- `milestone:"v1.0"` - Issues in milestone
149
- `repo:owner/name` - Specific repository
150
- `org:github` - Organization repositories
151
- `language:python` - Repository language
152
- `created:>2023-01-01` - Creation date
153
- `updated:>2023-01-01` - Last updated date
154
- `comments:>5` - Comment count
155

156
### Code Search
157

158
Search within code files across repositories.
159

160
```python { .api }
161
class GitHub:
162
    def search_code(self, query, sort="indexed", order="desc"):
163
        """
164
        Search for code.
165
        
166
        Args:
167
            query (str): Search query with optional qualifiers
168
            sort (str): Sort field ('indexed', 'best-match')
169
            order (str): Sort order ('asc', 'desc')
170
            
171
        Returns:
172
            SearchIterator: Iterator of CodeSearchResult objects
173
        """
174
```
175

176
**Usage Examples:**
177

178
```python
179
# Search for function definitions
180
for code in gh.search_code('def authenticate language:python'):
181
    print(f"{code.repository.full_name}:{code.path}")
182

183
# Search in specific repository
184
for code in gh.search_code('console.log repo:facebook/react'):
185
    print(f"{code.path}:{code.html_url}")
186

187
# Search by file extension
188
for code in gh.search_code('function extension:js'):
189
    print(f"{code.repository.full_name}:{code.name}")
190
```
191

192
**Code Query Qualifiers:**
193
- `language:python` - Programming language
194
- `extension:py` - File extension  
195
- `filename:README` - Filename
196
- `path:src/` - File path
197
- `repo:owner/name` - Specific repository
198
- `org:github` - Organization repositories
199
- `user:octocat` - User repositories
200
- `size:>1000` - File size
201

202
### Commit Search
203

204
Search commits across repositories.
205

206
```python { .api }
207
class GitHub:
208
    def search_commits(self, query, sort="author-date", order="desc"):
209
        """
210
        Search for commits.
211
        
212
        Args:
213
            query (str): Search query with optional qualifiers
214
            sort (str): Sort field ('author-date', 'committer-date')
215
            order (str): Sort order ('asc', 'desc')
216
            
217
        Returns:
218
            SearchIterator: Iterator of CommitSearchResult objects
219
        """
220
```
221

222
**Usage Examples:**
223

224
```python
225
# Search commits by author
226
for commit in gh.search_commits('author:octocat'):
227
    print(f"{commit.sha[:7]}: {commit.commit.message}")
228

229
# Search commits in repository
230
for commit in gh.search_commits('repo:torvalds/linux merge:false'):
231
    print(f"{commit.sha[:7]} by {commit.author.login}")
232

233
# Search by commit message
234
for commit in gh.search_commits('fix bug'):
235
    print(f"{commit.repository.full_name}: {commit.commit.message}")
236
```
237

238
**Commit Query Qualifiers:**
239
- `author:username` - Commit author
240
- `committer:username` - Committer
241
- `author-email:email` - Author email
242
- `committer-email:email` - Committer email
243
- `author-date:>2023-01-01` - Author date
244
- `committer-date:>2023-01-01` - Commit date
245
- `merge:true` or `merge:false` - Merge commits
246
- `hash:SHA` - Commit hash
247
- `parent:SHA` - Parent commit
248
- `tree:SHA` - Tree hash
249
- `repo:owner/name` - Specific repository
250
- `org:github` - Organization repositories
251

252
## Search Result Model Classes
253

254
```python { .api }
255
class RepositorySearchResult:
256
    """Repository search result."""
257
    id: int
258
    name: str
259
    full_name: str
260
    owner: 'User'
261
    private: bool
262
    html_url: str
263
    description: str
264
    fork: bool
265
    language: str
266
    stargazers_count: int
267
    forks_count: int
268
    open_issues_count: int
269
    default_branch: str
270
    score: float
271
    created_at: str
272
    updated_at: str
273
    pushed_at: str
274

275
class UserSearchResult:
276
    """User search result."""
277
    login: str
278
    id: int
279
    html_url: str
280
    type: str  # 'User' or 'Organization'
281
    company: str
282
    blog: str
283
    location: str
284
    email: str
285
    bio: str
286
    public_repos: int
287
    public_gists: int
288
    followers: int
289
    following: int
290
    created_at: str
291
    updated_at: str
292
    score: float
293

294
class IssueSearchResult:
295
    """Issue or pull request search result."""
296
    id: int
297
    number: int
298
    title: str
299
    body: str
300
    user: 'User'
301
    labels: list
302
    state: str
303
    assignee: 'User'
304
    milestone: 'Milestone'
305
    comments: int
306
    created_at: str
307
    updated_at: str
308
    closed_at: str
309
    pull_request: dict
310
    repository_url: str
311
    html_url: str
312
    score: float
313

314
class CodeSearchResult:
315
    """Code search result."""
316
    name: str
317
    path: str
318
    sha: str
319
    url: str
320
    git_url: str
321
    html_url: str
322
    repository: 'Repository'
323
    score: float
324

325
class CommitSearchResult:
326
    """Commit search result."""
327
    sha: str
328
    commit: 'GitCommit'
329
    author: 'User'
330
    committer: 'User'
331
    parents: list
332
    html_url: str
333
    comments_url: str
334
    repository: 'Repository'
335
    score: float
336

337
class SearchIterator:
338
    """Iterator for search results with special pagination."""
339
    total_count: int
340
    incomplete_results: bool
341
    
342
    def __iter__(self): ...
343
    def __next__(self): ...
344
```
345

346
## Search Tips
347

348
### Query Construction
349
- Use quotes for exact phrases: `"machine learning"`
350
- Use qualifiers to narrow results: `language:python stars:>100`
351
- Combine multiple qualifiers: `is:issue is:open label:bug author:octocat`
352
- Use ranges for numbers and dates: `stars:10..50 created:2020-01-01..2023-12-31`
353

354
### Rate Limiting
355
Search API has separate rate limits:
356
- Authenticated: 30 requests per minute
357
- Unauthenticated: 10 requests per minute
358

359
### Result Limits
360
- Maximum 1000 results per search query
361
- Use more specific queries to find relevant results within the limit