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 more, with robust authentication support, comprehensive error handling, and pagination support.
3

4
## Package Information
5

6
- **Package Name**: github3.py
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install github3.py`
10
- **Python Version**: 3.6+ or PyPy3
11

12
## Core Imports
13

14
```python
15
import github3
16
```
17

18
For authenticated sessions:
19

20
```python
21
from github3 import login, enterprise_login
22
```
23

24
For main classes:
25

26
```python
27
from github3 import GitHub, GitHubEnterprise, GitHubError
28
```
29

30
## Basic Usage
31

32
```python
33
import github3
34

35
# Anonymous access (limited API rate)
36
gh = github3.GitHub()
37

38
# Authenticated access with token (recommended)
39
gh = github3.login(token='your_personal_access_token')
40

41
# Or using username and token
42
gh = github3.login('username', token='your_personal_access_token')
43

44
# Get authenticated user info
45
me = gh.me()
46
print(f"Hello {me.name}")
47

48
# Get a repository
49
repo = gh.repository('owner', 'repo_name')
50
print(f"Repository: {repo.full_name}")
51
print(f"Stars: {repo.stargazers_count}")
52

53
# List user's repositories
54
for repo in gh.repositories():
55
    print(f"{repo.full_name} - {repo.description}")
56

57
# Create an issue
58
issue = repo.create_issue(
59
    title="Bug report",
60
    body="Description of the bug"
61
)
62
print(f"Created issue #{issue.number}")
63

64
# Search repositories
65
for repo in gh.search_repositories('machine learning python'):
66
    print(f"{repo.full_name} - ⭐ {repo.stargazers_count}")
67
```
68

69
## Architecture
70

71
GitHub3.py follows an object-oriented design centered around the main `GitHub` client class:
72

73
- **GitHub/GitHubEnterprise**: Main API client classes providing authenticated access
74
- **Model Classes**: Rich objects representing GitHub entities (User, Repository, Issue, etc.)
75
- **Session Management**: Custom HTTP session handling with authentication and rate limiting
76
- **Pagination Support**: Automatic handling of paginated API responses via iterators
77
- **Exception Hierarchy**: Comprehensive error handling for different API response codes
78

79
## Capabilities
80

81
### Authentication & Sessions
82

83
Complete authentication support including personal access tokens, OAuth, username/password, two-factor authentication, and GitHub Apps authentication.
84

85
```python { .api }
86
def login(username=None, password=None, token=None, two_factor_callback=None):
87
    """Construct and return an authenticated GitHub session."""
88

89
def enterprise_login(username=None, password=None, token=None, url=None, two_factor_callback=None):
90
    """Construct and return an authenticated GitHub Enterprise session."""
91

92
class GitHub:
93
    def __init__(self, username="", password="", token="", session=None): ...
94
    def login(self, username=None, password=None, token=None, two_factor_callback=None): ...
95
    def login_as_app(self, private_key_pem, app_id, expire_in=600): ...
96
    def login_as_app_installation(self, private_key_pem, app_id, installation_id): ...
97
```
98

99
[Authentication & Sessions](./authentication.md)
100

101
### User Management
102

103
Access to user profiles, account management, email addresses, SSH keys, GPG keys, and user relationships (followers, following).
104

105
```python { .api }
106
class GitHub:
107
    def me(self): ...
108
    def user(self, username): ...
109
    def update_me(self, name=None, email=None, blog=None, company=None, location=None, hireable=None, bio=None): ...
110
    def add_email_addresses(self, addresses=[]): ...
111
    def followers_of(self, username): ...
112
    def followed_by(self, username): ...
113
```
114

115
[User Management](./users.md)
116

117
### Repository Operations
118

119
Complete repository management including creation, forking, starring, watching, branch operations, and repository settings.
120

121
```python { .api }
122
class GitHub:
123
    def repository(self, owner, repository): ...
124
    def create_repository(self, name, description="", homepage="", private=False, **kwargs): ...
125
    def repositories(self, type=None, sort="created", direction="desc"): ...
126
    def starred(self): ...
127
    def star(self, owner, repo): ...
128
    def all_repositories(self, since=None): ...
129
```
130

131
[Repository Operations](./repositories.md)
132

133
### Issue Management
134

135
Full issue lifecycle management including creation, editing, commenting, labeling, milestones, and issue events.
136

137
```python { .api }
138
class GitHub:
139
    def issue(self, owner, repository, number): ...
140
    def issues(self, filter="assigned", state="open", labels="", sort="created", direction="desc", since=None): ...
141
```
142

143
[Issue Management](./issues.md)
144

145
### Pull Request Workflows
146

147
Complete pull request operations including creation, review management, merging, file changes, and review comments.
148

149
```python { .api }
150
class GitHub:
151
    def pull_request(self, owner, repository, number): ...
152
```
153

154
[Pull Request Workflows](./pull-requests.md)
155

156
### Organization Management
157

158
Organization operations including team management, member access, organization repositories, and webhooks.
159

160
```python { .api }
161
class GitHub:
162
    def organization(self, login): ...
163
    def organizations(self): ...
164
```
165

166
[Organization Management](./organizations.md)
167

168
### Gist Operations
169

170
Complete gist management including creation, editing, forking, commenting, and file operations.
171

172
```python { .api }
173
class GitHub:
174
    def gist(self, id): ...
175
    def create_gist(self, description, files, public=True): ...
176
    def gists(self, type="owner"): ...
177
    def public_gists(self): ...
178
```
179

180
[Gist Operations](./gists.md)
181

182
### Search Operations
183

184
Comprehensive search across repositories, users, issues, code, and commits with advanced filtering and sorting options.
185

186
```python { .api }
187
class GitHub:
188
    def search_repositories(self, query, sort="stars", order="desc"): ...
189
    def search_users(self, query, sort="followers", order="desc"): ...
190
    def search_issues(self, query, sort="created", order="desc"): ...
191
    def search_code(self, query, sort="indexed", order="desc"): ...
192
```
193

194
[Search Operations](./search.md)
195

196
### Git Operations
197

198
Low-level Git object access including blobs, trees, commits, references, and tags for advanced repository manipulation.
199

200
[Git Operations](./git-objects.md)
201

202
### GitHub Apps & Checks
203

204
GitHub Apps integration including installation management, check runs, and check suites for CI/CD integrations.
205

206
```python { .api }
207
class GitHub:
208
    def app(self): ...
209
    def app_installation(self, installation_id): ...
210
    def app_installations(self): ...
211
```
212

213
[GitHub Apps & Checks](./apps-checks.md)
214

215
## Exception Handling
216

217
```python { .api }
218
class GitHubError(Exception):
219
    """Base exception for GitHub API errors."""
220

221
class AuthenticationFailed(GitHubError):
222
    """HTTP 401 Unauthorized."""
223

224
class ForbiddenError(GitHubError):
225
    """HTTP 403 Forbidden."""
226

227
class NotFoundError(GitHubError):
228
    """HTTP 404 Not Found."""
229

230
class UnprocessableEntity(GitHubError):
231
    """HTTP 422 Unprocessable Entity."""
232
```
233

234
## Utility Functions
235

236
```python { .api }
237
class GitHub:
238
    def rate_limit(self): ...
239
    def emojis(self): ...
240
    def markdown(self, text, mode="gfm", context=""): ...
241
    def zen(self): ...
242
    def licenses(self): ...
243
    def gitignore_templates(self): ...
244
```
245

246
## Core Types
247

248
```python { .api }
249
from typing import Union, List, Dict, Optional
250

251
UserLike = Union[str, 'User', 'ShortUser', 'AuthenticatedUser']
252

253
class GitHub:
254
    """Main GitHub API client."""
255
    
256
class GitHubEnterprise(GitHub):
257
    """GitHub Enterprise API client."""
258
    def __init__(self, url, username="", password="", token="", verify=True, session=None): ...
259

260
class GitHubError(Exception):
261
    """Base exception for all GitHub API errors."""
262
```