0
# Search and Discovery
1

2
Search functionality across repositories, users, issues, code, commits, and topics. Provides comprehensive search capabilities with filtering and sorting options to discover GitHub content.
3

4
## Capabilities
5

6
### Repository Search
7

8
Search for repositories across GitHub with advanced filtering and sorting options.
9

10
```python { .api }
11
class Github:
12
    def search_repositories(
13
        self,
14
        query: str,
15
        sort: str = None,
16
        order: str = None
17
    ):
18
        """
19
        Search repositories.
20
        
21
        Args:
22
            query (str): Search query with optional qualifiers
23
            sort (str, optional): Sort field ("stars", "forks", "help-wanted-issues", "updated")
24
            order (str, optional): Sort order ("asc", "desc")
25
            
26
        Returns:
27
            PaginatedList[Repository]: Search results
28
        """
29
```
30

31
Repository search query qualifiers:
32
- `user:USERNAME` - repositories owned by specific user
33
- `org:ORGNAME` - repositories owned by specific organization  
34
- `language:LANGUAGE` - repositories primarily written in language
35
- `stars:>NUMBER` - repositories with more than NUMBER stars
36
- `forks:>NUMBER` - repositories with more than NUMBER forks
37
- `size:>NUMBER` - repositories larger than NUMBER KB
38
- `created:>YYYY-MM-DD` - repositories created after date
39
- `pushed:>YYYY-MM-DD` - repositories pushed after date
40
- `is:public` or `is:private` - public or private repositories
41
- `archived:true` or `archived:false` - archived status
42
- `fork:true` or `fork:false` - include/exclude forks
43
- `mirror:true` or `mirror:false` - include/exclude mirrors
44
- `topic:TOPIC` - repositories tagged with topic
45

46
### User Search
47

48
Search for users and organizations on GitHub.
49

50
```python { .api }
51
class Github:
52
    def search_users(
53
        self,
54
        query: str,
55
        sort: str = None,
56
        order: str = None
57
    ):
58
        """
59
        Search users and organizations.
60
        
61
        Args:
62
            query (str): Search query with optional qualifiers
63
            sort (str, optional): Sort field ("followers", "repositories", "joined")
64
            order (str, optional): Sort order ("asc", "desc")
65
            
66
        Returns:
67
            PaginatedList[NamedUser]: Search results
68
        """
69
```
70

71
User search query qualifiers:
72
- `type:user` - search only users
73
- `type:org` - search only organizations
74
- `location:LOCATION` - users in specific location
75
- `language:LANGUAGE` - users with repositories in language
76
- `created:>YYYY-MM-DD` - users joined after date
77
- `followers:>NUMBER` - users with more than NUMBER followers
78
- `repos:>NUMBER` - users with more than NUMBER repositories
79

80
### Issue and Pull Request Search
81

82
Search issues and pull requests across repositories with detailed filtering.
83

84
```python { .api }
85
class Github:
86
    def search_issues(
87
        self,
88
        query: str,
89
        sort: str = None,
90
        order: str = None
91
    ):
92
        """
93
        Search issues and pull requests.
94
        
95
        Args:
96
            query (str): Search query with optional qualifiers
97
            sort (str, optional): Sort field ("comments", "reactions", "reactions-+1", "reactions--1", "reactions-smile", "reactions-thinking_face", "reactions-heart", "reactions-tada", "interactions", "created", "updated")
98
            order (str, optional): Sort order ("asc", "desc")
99
            
100
        Returns:
101
            PaginatedList[Issue]: Search results (includes pull requests)
102
        """
103
```
104

105
Issue search query qualifiers:
106
- `repo:OWNER/NAME` - issues in specific repository
107
- `user:USERNAME` - issues involving specific user
108
- `assignee:USERNAME` - issues assigned to user
109
- `mentions:USERNAME` - issues mentioning user
110
- `author:USERNAME` - issues created by user
111
- `commenter:USERNAME` - issues commented on by user
112
- `involves:USERNAME` - issues involving user in any way
113
- `state:open` or `state:closed` - issue state
114
- `is:issue` or `is:pr` - filter by type
115
- `is:public` or `is:private` - repository visibility
116
- `label:LABEL` - issues with specific label
117
- `milestone:MILESTONE` - issues in milestone
118
- `project:PROJECT` - issues in project board
119
- `status:pending` - pull request status checks
120
- `review:required` - pull requests requiring review
121
- `draft:true` or `draft:false` - draft pull requests
122
- `created:>YYYY-MM-DD` - issues created after date
123
- `updated:>YYYY-MM-DD` - issues updated after date
124
- `closed:>YYYY-MM-DD` - issues closed after date
125
- `merged:>YYYY-MM-DD` - pull requests merged after date
126
- `comments:>NUMBER` - issues with more than NUMBER comments
127

128
### Code Search
129

130
Search code content within repositories.
131

132
```python { .api }
133
class Github:
134
    def search_code(
135
        self,
136
        query: str,
137
        sort: str = None,
138
        order: str = None
139
    ):
140
        """
141
        Search code.
142
        
143
        Args:
144
            query (str): Search query with optional qualifiers
145
            sort (str, optional): Sort field ("indexed" - when file was indexed)
146
            order (str, optional): Sort order ("asc", "desc")
147
            
148
        Returns:
149
            PaginatedList[ContentFile]: Search results
150
        """
151
```
152

153
Code search query qualifiers:
154
- `repo:OWNER/NAME` - code in specific repository
155
- `user:USERNAME` - code in user's repositories
156
- `org:ORGNAME` - code in organization's repositories
157
- `language:LANGUAGE` - code in specific programming language
158
- `filename:NAME` - code in files with specific name
159
- `extension:EXT` - code in files with specific extension
160
- `path:PATH` - code in specific path
161
- `size:>NUMBER` - files larger than NUMBER bytes
162
- `fork:true` or `fork:false` - include/exclude forks
163

164
### Commit Search
165

166
Search commits across repositories.
167

168
```python { .api }
169
class Github:
170
    def search_commits(
171
        self,
172
        query: str,
173
        sort: str = None,
174
        order: str = None
175
    ):
176
        """
177
        Search commits.
178
        
179
        Args:
180
            query (str): Search query with optional qualifiers
181
            sort (str, optional): Sort field ("author-date", "committer-date")
182
            order (str, optional): Sort order ("asc", "desc")
183
            
184
        Returns:
185
            PaginatedList[Commit]: Search results
186
        """
187
```
188

189
Commit search query qualifiers:
190
- `repo:OWNER/NAME` - commits in specific repository
191
- `user:USERNAME` - commits in user's repositories
192
- `org:ORGNAME` - commits in organization's repositories  
193
- `author:USERNAME` - commits authored by user
194
- `committer:USERNAME` - commits committed by user
195
- `author-email:EMAIL` - commits by author email
196
- `committer-email:EMAIL` - commits by committer email
197
- `author-date:>YYYY-MM-DD` - commits authored after date
198
- `committer-date:>YYYY-MM-DD` - commits committed after date
199
- `merge:true` or `merge:false` - merge commits
200
- `hash:SHA` - commits with specific SHA prefix
201
- `tree:SHA` - commits with specific tree SHA
202
- `parent:SHA` - commits with specific parent SHA
203

204
### Topic Search
205

206
Search repository topics for content discovery.
207

208
```python { .api }
209
class Github:
210
    def search_topics(self, query: str):
211
        """
212
        Search topics.
213
        
214
        Args:
215
            query (str): Topic search query
216
            
217
        Returns:
218
            PaginatedList[Topic]: Search results
219
        """
220

221
class Topic:
222
    @property
223
    def name(self) -> str: ...
224
    @property
225
    def display_name(self) -> str: ...
226
    @property
227
    def short_description(self) -> str: ...
228
    @property
229
    def description(self) -> str: ...
230
    @property
231
    def created_by(self) -> str: ...
232
    @property
233
    def released(self) -> str: ...
234
    @property
235
    def created_at(self) -> datetime: ...
236
    @property
237
    def updated_at(self) -> datetime: ...
238
    @property
239
    def featured(self) -> bool: ...
240
    @property
241
    def curated(self) -> bool: ...
242
    @property
243
    def score(self) -> float: ...
244
```
245

246
### Advanced Search with Github Instance
247

248
Access comprehensive search functionality through the main Github client.
249

250
```python { .api }
251
class Github:
252
    def get_licenses(self):
253
        """
254
        Get available open source licenses.
255
        
256
        Returns:
257
            PaginatedList[License]: List of licenses
258
        """
259
    
260
    def get_license(self, key: str):
261
        """
262
        Get a specific license.
263
        
264
        Args:
265
            key (str): License key (e.g., "mit", "apache-2.0")
266
            
267
        Returns:
268
            License: License object
269
        """
270
    
271
    def get_gitignore_templates(self):
272
        """
273
        Get available .gitignore templates.
274
        
275
        Returns:
276
            list: List of template names
277
        """
278
    
279
    def get_gitignore_template(self, name: str):
280
        """
281
        Get a .gitignore template.
282
        
283
        Args:
284
            name (str): Template name
285
            
286
        Returns:
287
            GitignoreTemplate: Template object
288
        """
289
    
290
    def get_repos(self, since: int = None):
291
        """
292
        Get public repositories in order of creation.
293
        
294
        Args:
295
            since (int, optional): Repository ID to start from
296
            
297
        Returns:
298
            PaginatedList[Repository]: List of repositories
299
        """
300
    
301
    def get_users(self, since: int = None):
302
        """
303
        Get users in order of sign-up.
304
        
305
        Args:
306
            since (int, optional): User ID to start from
307
            
308
        Returns:
309
            PaginatedList[NamedUser]: List of users
310
        """
311
```
312

313
## Usage Examples
314

315
### Repository Search
316

317
```python
318
from github import Github, Auth
319

320
g = Github(auth=Auth.Token("your_token"))
321

322
# Search for Python repositories with many stars
323
repos = g.search_repositories(
324
    query="language:python stars:>1000",
325
    sort="stars",
326
    order="desc"
327
)
328

329
print(f"Found {repos.totalCount} repositories")
330
for repo in repos[:10]:  # First 10 results
331
    print(f"{repo.full_name}: {repo.stargazers_count} stars")
332

333
# Search for repositories by organization
334
org_repos = g.search_repositories(
335
    query="org:microsoft language:typescript",
336
    sort="updated",
337
    order="desc"
338
)
339

340
for repo in org_repos[:5]:
341
    print(f"{repo.full_name} - Updated: {repo.updated_at}")
342
```
343

344
### User Search
345

346
```python
347
# Search for users by location and language
348
users = g.search_users(
349
    query="location:\"San Francisco\" language:python",
350
    sort="followers",
351
    order="desc"
352
)
353

354
for user in users[:5]:
355
    print(f"{user.login}: {user.followers} followers")
356

357
# Search for organizations
358
orgs = g.search_users(
359
    query="type:org location:\"New York\"",
360
    sort="repositories",
361
    order="desc"
362
)
363

364
for org in orgs[:5]:
365
    print(f"{org.login}: {org.public_repos} repos")
366
```
367

368
### Issue and Pull Request Search
369

370
```python
371
# Search for open issues with specific label
372
issues = g.search_issues(
373
    query="is:issue is:open label:bug language:python",
374
    sort="created",
375
    order="desc"
376
)
377

378
print(f"Found {issues.totalCount} open bug issues")
379
for issue in issues[:5]:
380
    print(f"#{issue.number} in {issue.repository.full_name}: {issue.title}")
381

382
# Search for pull requests needing review
383
prs = g.search_issues(
384
    query="is:pr is:open review:required",
385
    sort="created",
386
    order="asc"  # Oldest first
387
)
388

389
for pr in prs[:5]:
390
    print(f"PR #{pr.number} in {pr.repository.full_name}: {pr.title}")
391
```
392

393
### Code Search
394

395
```python
396
# Search for specific function usage
397
code_results = g.search_code(
398
    query="requests.get language:python",
399
    sort="indexed",
400
    order="desc"
401
)
402

403
print(f"Found {code_results.totalCount} code matches")
404
for result in code_results[:5]:
405
    print(f"{result.repository.full_name}:{result.path}")
406

407
# Search for configuration files
408
config_files = g.search_code(
409
    query="filename:docker-compose.yml",
410
    sort="indexed",
411
    order="desc"
412
)
413

414
for file in config_files[:3]:
415
    print(f"Docker Compose in: {file.repository.full_name}")
416
```
417

418
### Commit Search
419

420
```python
421
# Search for commits by author
422
commits = g.search_commits(
423
    query="author:octocat repo:octocat/Hello-World",
424
    sort="author-date",
425
    order="desc"
426
)
427

428
for commit in commits[:5]:
429
    print(f"{commit.sha[:8]}: {commit.commit.message}")
430

431
# Search for merge commits
432
merge_commits = g.search_commits(
433
    query="merge:true repo:owner/repo",
434
    sort="committer-date",
435
    order="desc"
436
)
437

438
for commit in merge_commits[:3]:
439
    print(f"Merge commit: {commit.sha[:8]}")
440
```
441

442
### Topic Discovery
443

444
```python
445
# Search for topics
446
topics = g.search_topics("machine-learning")
447

448
for topic in topics[:5]:
449
    print(f"Topic: {topic.name}")
450
    print(f"Description: {topic.short_description}")
451
    print(f"Featured: {topic.featured}")
452
    print("---")
453
```
454

455
### Advanced Discovery
456

457
```python
458
# Get trending repositories (approximation using recent activity)
459
trending = g.search_repositories(
460
    query="created:>2024-01-01 stars:>100",
461
    sort="stars",
462
    order="desc"
463
)
464

465
print("Trending repositories:")
466
for repo in trending[:10]:
467
    print(f"{repo.full_name}: {repo.stargazers_count} stars, created {repo.created_at}")
468

469
# Find repositories with good first issues
470
good_first_issues = g.search_issues(
471
    query="label:\"good first issue\" is:open is:issue",
472
    sort="created",
473
    order="desc"
474
)
475

476
print("\nGood first issues:")
477
for issue in good_first_issues[:5]:
478
    print(f"#{issue.number} in {issue.repository.full_name}: {issue.title}")
479

480
# Find repositories needing help
481
help_wanted = g.search_repositories(
482
    query="help-wanted-issues:>0",
483
    sort="help-wanted-issues",
484
    order="desc"
485
)
486

487
print("\nRepositories needing help:")
488
for repo in help_wanted[:5]:
489
    print(f"{repo.full_name}: {repo.open_issues_count} open issues")
490
```
491

492
### Complex Search Queries
493

494
```python
495
# Multi-criteria repository search
496
complex_search = g.search_repositories(
497
    query=(
498
        "language:javascript "
499
        "stars:>500 "
500
        "pushed:>2024-01-01 "
501
        "size:<10000 "
502
        "NOT archived:true "
503
        "topic:react"
504
    ),
505
    sort="updated",
506
    order="desc"
507
)
508

509
print("Active React repositories:")
510
for repo in complex_search[:5]:
511
    print(f"{repo.full_name}: {repo.stargazers_count} stars, updated {repo.updated_at}")
512

513
# Find beginner-friendly projects
514
beginner_friendly = g.search_repositories(
515
    query=(
516
        "good-first-issues:>5 "
517
        "help-wanted-issues:>0 "
518
        "stars:>100 "
519
        "language:python"
520
    ),
521
    sort="stars",
522
    order="desc"
523
)
524

525
print("\nBeginner-friendly Python projects:")
526
for repo in beginner_friendly[:3]:
527
    print(f"{repo.full_name}: {repo.stargazers_count} stars")
528
```