0
# github3.py
1
2
A comprehensive, actively developed, and extraordinarily stable Python wrapper around the GitHub API (v3). This library provides complete access to GitHub's REST API functionality including repositories, issues, pull requests, organizations, users, gists, and webhooks through an intuitive object-oriented interface.
3
4
## Package Information
5
6
- **Package Name**: github3.py
7
- **Language**: Python
8
- **Installation**: `pip install github3.py`
9
- **Requirements**: Python 3.7+
10
- **Dependencies**: requests, uritemplate, python-dateutil, PyJWT[crypto]
11
12
## Core Imports
13
14
```python
15
import github3
16
```
17
18
For authenticated access:
19
20
```python
21
# Using login function
22
from github3 import login
23
gh = login('username', token='your_token')
24
25
# Or using GitHub class directly
26
from github3 import GitHub
27
gh = GitHub(token='your_token')
28
```
29
30
For unauthenticated access:
31
32
```python
33
from github3 import GitHub
34
gh = GitHub()
35
```
36
37
## Basic Usage
38
39
```python
40
import github3
41
42
# Unauthenticated access for public data
43
gh = github3.GitHub()
44
45
# Get a repository
46
repo = gh.repository('octocat', 'Hello-World')
47
print(f"Repository: {repo.full_name}")
48
print(f"Description: {repo.description}")
49
print(f"Stars: {repo.stargazers_count}")
50
51
# Get a user
52
user = gh.user('octocat')
53
print(f"User: {user.login}")
54
print(f"Name: {user.name}")
55
56
# Authenticated access for full functionality
57
gh = github3.login(token='your_personal_access_token')
58
59
# Create a repository
60
new_repo = gh.create_repository('my-new-repo', description='A test repository')
61
62
# Create an issue
63
issue = gh.create_issue('owner', 'repo', 'Issue title', 'Issue body')
64
65
# Star a repository
66
gh.star('owner', 'repo')
67
```
68
69
## Architecture
70
71
The library is organized around these key components:
72
73
- **GitHub/GitHubEnterprise**: Main client classes providing session management and API access
74
- **Model Classes**: Rich objects representing GitHub entities (User, Repository, Issue, etc.)
75
- **Authentication**: Multiple auth methods including tokens, OAuth, GitHub Apps, and 2FA
76
- **Decorators**: Authentication requirement enforcement and API access control
77
- **Exception Handling**: Comprehensive error types for different HTTP status codes and scenarios
78
79
The object-oriented design allows for intuitive navigation between related entities (e.g., from a repository to its issues to individual comments) while providing both high-level convenience methods and low-level API access.
80
81
## Capabilities
82
83
### Authentication & Session Management
84
85
Core authentication functionality supporting multiple GitHub authentication methods including personal access tokens, OAuth, GitHub Apps, and enterprise instances.
86
87
```python { .api }
88
def login(username=None, password=None, token=None, two_factor_callback=None): ...
89
def enterprise_login(username=None, password=None, token=None, url=None, two_factor_callback=None): ...
90
91
class GitHub:
92
def __init__(self, username="", password="", token="", session=None, api_version=""): ...
93
def login(self, username=None, password=None, token=None, two_factor_callback=None): ...
94
def login_as_app(self, private_key_pem, app_id, expire_in=600): ...
95
def login_as_app_installation(self, private_key_pem, app_id, installation_id, expire_in=30): ...
96
```
97
98
[Authentication](./authentication.md)
99
100
### User Management
101
102
Complete user profile management, social features, and account operations for the authenticated user and public user information retrieval.
103
104
```python { .api }
105
def user(self, username): ...
106
def user_with_id(self, number): ...
107
def me(self): ...
108
def update_me(self, name=None, email=None, blog=None, company=None, location=None, hireable=False, bio=None): ...
109
def follow(self, username): ...
110
def unfollow(self, username): ...
111
def is_following(self, username): ...
112
def followers(self, number=-1, etag=None): ...
113
def following(self, number=-1, etag=None): ...
114
def followers_of(self, username, number=-1, etag=None): ...
115
def followed_by(self, username, number=-1, etag=None): ...
116
```
117
118
[User Management](./users.md)
119
120
### Repository Operations
121
122
Comprehensive repository management including creation, modification, collaboration, and content operations for both authenticated and public repositories.
123
124
```python { .api }
125
def repository(self, owner, repository): ...
126
def repository_with_id(self, number): ...
127
def repositories(self, type=None, sort=None, direction=None, number=-1, etag=None): ...
128
def repositories_by(self, username, type=None, sort=None, direction=None, number=-1, etag=None): ...
129
def all_repositories(self, number=-1, since=None, etag=None, per_page=None): ...
130
def create_repository(self, name, description="", homepage="", private=False, has_issues=True, has_wiki=True, auto_init=False, gitignore_template="", has_projects=True): ...
131
def star(self, username, repo): ...
132
def unstar(self, username, repo): ...
133
def is_starred(self, username, repo): ...
134
def starred(self, sort=None, direction=None, number=-1, etag=None): ...
135
def starred_by(self, username, sort=None, direction=None, number=-1, etag=None): ...
136
```
137
138
[Repository Operations](./repositories.md)
139
140
### Issue & Pull Request Management
141
142
Complete issue and pull request lifecycle management including creation, modification, labeling, milestones, and collaboration features.
143
144
```python { .api }
145
def issue(self, username, repository, number): ...
146
def issues(self, filter="", state="", labels="", sort="", direction="", since=None, number=-1, etag=None): ...
147
def issues_on(self, username, repository, milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None): ...
148
def user_issues(self, filter="", state="", labels="", sort="", direction="", since=None, per_page=None, number=-1, etag=None): ...
149
def create_issue(self, owner, repository, title, body=None, assignee=None, milestone=None, labels=[], assignees=None): ...
150
def pull_request(self, owner, repository, number): ...
151
```
152
153
[Issues & Pull Requests](./issues-prs.md)
154
155
### Organization Management
156
157
Organization administration, team management, membership handling, and organization-wide operations for enterprise GitHub usage.
158
159
```python { .api }
160
def organization(self, username): ...
161
def organizations(self, number=-1, etag=None): ...
162
def organizations_with(self, username, number=-1, etag=None): ...
163
def all_organizations(self, number=-1, since=None, etag=None, per_page=None): ...
164
def membership_in(self, organization): ...
165
def activate_membership(self, organization): ...
166
def organization_memberships(self, state=None, number=-1, etag=None): ...
167
def organization_issues(self, name, filter="", state="", labels="", sort="", direction="", since=None, number=-1, etag=None): ...
168
```
169
170
**Note**: Organization management capabilities are included in the User Management and Repository Operations documentation.
171
172
### Gist Operations
173
174
Complete gist management including creation, modification, commenting, and sharing of code snippets and small files.
175
176
```python { .api }
177
def gist(self, id_num): ...
178
def gists(self, number=-1, etag=None): ...
179
def gists_by(self, username, number=-1, etag=None): ...
180
def public_gists(self, number=-1, etag=None, since=None): ...
181
def create_gist(self, description, files, public=True): ...
182
```
183
184
**Note**: Gist operations follow similar patterns to repository operations documented above.
185
186
### Search & Discovery
187
188
Powerful search capabilities across repositories, code, issues, users, and commits with advanced query syntax and filtering options.
189
190
```python { .api }
191
def search_repositories(self, query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None): ...
192
def search_code(self, query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None): ...
193
def search_issues(self, query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None): ...
194
def search_users(self, query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None): ...
195
def search_commits(self, query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None): ...
196
```
197
198
**Note**: Search functionality is accessible through the main GitHub client with comprehensive querying capabilities.
199
200
### GitHub Apps Integration
201
202
GitHub Apps authentication, installation management, and programmatic access for building integrations and automation tools.
203
204
```python { .api }
205
def app(self, app_slug): ...
206
def authenticated_app(self): ...
207
def app_installations(self, number=-1): ...
208
def app_installation(self, installation_id): ...
209
def app_installation_for_organization(self, organization): ...
210
def app_installation_for_repository(self, owner, repository): ...
211
def app_installation_for_user(self, user): ...
212
def app_installation_repos(self, number=-1, etag=None): ...
213
```
214
215
**Note**: GitHub Apps authentication is covered in the Authentication documentation above.
216
217
### SSH & GPG Key Management
218
219
Complete SSH and GPG key lifecycle management for secure authentication and commit signing configuration.
220
221
```python { .api }
222
def keys(self, number=-1, etag=None): ...
223
def key(self, id_num): ...
224
def create_key(self, title, key, read_only=False): ...
225
def gpg_keys(self, number=-1, etag=None): ...
226
def gpg_key(self, id_num): ...
227
def create_gpg_key(self, armored_public_key): ...
228
```
229
230
**Note**: SSH and GPG key management is covered in the User Management documentation above.
231
232
### Utility & Metadata
233
234
GitHub platform utilities including rate limiting, API metadata, templates, licenses, and various GitHub-specific features.
235
236
```python { .api }
237
def rate_limit(self): ...
238
def meta(self): ...
239
def emojis(self): ...
240
def gitignore_templates(self): ...
241
def gitignore_template(self, language): ...
242
def licenses(self, number=-1, etag=None): ...
243
def license(self, name): ...
244
def markdown(self, text, mode="", context="", raw=False): ...
245
def octocat(self, say=None): ...
246
def zen(self): ...
247
def feeds(self): ...
248
def pubsubhubbub(self, mode, topic, callback, secret=""): ...
249
```
250
251
**Note**: Utility functions provide direct access to GitHub's platform features and metadata.
252
253
## Core Types
254
255
```python { .api }
256
class GitHub:
257
"""Main GitHub API client for github.com"""
258
def __init__(self, username="", password="", token="", session=None, api_version=""): ...
259
260
class GitHubEnterprise:
261
"""GitHub API client for Enterprise instances"""
262
def __init__(self, url, username="", password="", token="", verify=True, session=None): ...
263
def create_user(self, login, email): ...
264
def admin_stats(self, option): ...
265
266
class GitHubError(Exception):
267
"""Base exception class for GitHub API errors"""
268
pass
269
270
# Core entity types
271
class User:
272
"""GitHub user representation"""
273
login: str
274
name: str
275
email: str
276
id: int
277
avatar_url: str
278
html_url: str
279
type: str
280
site_admin: bool
281
282
class Repository:
283
"""GitHub repository representation"""
284
name: str
285
full_name: str
286
description: str
287
id: int
288
private: bool
289
html_url: str
290
clone_url: str
291
stargazers_count: int
292
forks_count: int
293
language: str
294
default_branch: str
295
296
class Issue:
297
"""GitHub issue representation"""
298
number: int
299
title: str
300
body: str
301
state: str
302
id: int
303
html_url: str
304
user: User
305
assignee: User
306
labels: list
307
milestone: object
308
309
class PullRequest:
310
"""GitHub pull request representation"""
311
number: int
312
title: str
313
body: str
314
state: str
315
id: int
316
html_url: str
317
user: User
318
base: object
319
head: object
320
merged: bool
321
322
class Gist:
323
"""GitHub gist representation"""
324
id: str
325
description: str
326
public: bool
327
html_url: str
328
files: dict
329
user: User
330
331
class Organization:
332
"""GitHub organization representation"""
333
login: str
334
name: str
335
id: int
336
description: str
337
html_url: str
338
avatar_url: str
339
public_repos: int
340
341
# Short object types (used in listings)
342
class ShortUser:
343
"""Abbreviated user representation"""
344
login: str
345
id: int
346
avatar_url: str
347
html_url: str
348
349
class ShortRepository:
350
"""Abbreviated repository representation"""
351
name: str
352
full_name: str
353
id: int
354
private: bool
355
html_url: str
356
357
class ShortIssue:
358
"""Abbreviated issue representation"""
359
number: int
360
title: str
361
state: str
362
id: int
363
html_url: str
364
365
# Utility types
366
class Email:
367
"""User email address representation"""
368
email: str
369
primary: bool
370
verified: bool
371
visibility: str
372
```