0
# ghapi
1

2
A Python client for the GitHub API that provides 100% always-updated coverage of the entire GitHub REST API. The library automatically converts GitHub's OpenAPI specification to a Pythonic API, ensuring it stays current with the latest GitHub API changes while maintaining a compact package size.
3

4
## Package Information
5

6
- **Package Name**: ghapi
7
- **Language**: Python
8
- **Installation**: `pip install ghapi`
9
- **Requirements**: Python 3.7+, fastcore>=1.7.2
10

11
## Core Imports
12

13
```python
14
from ghapi.all import GhApi
15
```
16

17
Individual modules:
18

19
```python
20
from ghapi.core import GhApi, date2gh, gh2date, print_summary, GH_HOST, EMPTY_TREE_SHA
21
from ghapi.auth import GhDeviceAuth, github_auth_device, Scope, scope_str
22
from ghapi.actions import Event, contexts, env_github, user_repo
23
from ghapi.page import paged, parse_link_hdr
24
from ghapi.event import GhEvent, load_sample_events, save_sample_events
25
from ghapi.cli import ghapi, ghpath, ghraw, completion_ghapi
26
```
27

28
## Basic Usage
29

30
```python
31
from ghapi.all import GhApi
32

33
# Create API client with token authentication
34
api = GhApi(token='your_github_token')
35

36
# Access API endpoints by group and operation
37
repo = api.repos.get(owner='fastai', repo='ghapi')
38
print(f"Repository: {repo.full_name}")
39
print(f"Stars: {repo.stargazers_count}")
40

41
# List issues
42
issues = api.issues.list_for_repo(owner='fastai', repo='ghapi', state='open')
43
for issue in issues:
44
    print(f"#{issue.number}: {issue.title}")
45

46
# Create a new issue
47
new_issue = api.issues.create(
48
    owner='fastai', 
49
    repo='ghapi',
50
    title='Example Issue',
51
    body='This is an example issue created via ghapi'
52
)
53

54
# Work with gists
55
gist = api.create_gist(
56
    description='Example gist',
57
    content='print("Hello from ghapi!")',
58
    filename='example.py',
59
    public=False
60
)
61
```
62

63
## Architecture
64

65
ghapi is built around several key components:
66

67
- **GhApi**: The main API client that dynamically creates methods from GitHub's OpenAPI specification
68
- **Endpoint Groups**: GitHub API endpoints organized by functionality (repos, issues, actions, etc.)
69
- **Authentication**: Support for token-based and JWT authentication, plus OAuth device flow
70
- **Pagination**: Automatic handling of paginated API responses
71
- **CLI Tools**: Command-line interfaces for direct API access
72
- **Event System**: Support for GitHub webhook events and GitHub Actions contexts
73

74
The library uses a dynamic approach where all GitHub API endpoints are automatically generated from metadata, ensuring 100% API coverage that stays synchronized with GitHub's evolving API.
75

76
## Capabilities
77

78
### Core API Client
79

80
The main GhApi class providing access to all GitHub API endpoints, authentication management, and core functionality like repository operations, issue management, and release handling.
81

82
```python { .api }
83
class GhApi:
84
    def __init__(self, owner=None, repo=None, token=None, jwt_token=None, 
85
                 debug=None, limit_cb=None, gh_host=None, authenticate=True, **kwargs): ...
86
    def __call__(self, path: str, verb: str = None, headers: dict = None, 
87
                 route: dict = None, query: dict = None, data=None, timeout=None, decode=True): ...
88
    def __getitem__(self, k): ...
89
    def full_docs(self): ...
90

91
def print_summary(req: Request): ...
92
def date2gh(dt: datetime) -> str: ...
93
def gh2date(dtstr: str) -> datetime: ...
94
```
95

96
[Core API Client](./core-api.md)
97

98
### Authentication & Authorization
99

100
OAuth device flow authentication, token management, and GitHub API scopes for secure API access.
101

102
```python { .api }
103
class GhDeviceAuth:
104
    def __init__(self, client_id=None, *scopes): ...
105
    def url_docs(self) -> str: ...
106
    def open_browser(self): ...
107
    def auth(self) -> str: ...
108
    def wait(self, cb: callable = None, n_polls=9999) -> str: ...
109

110
def github_auth_device(wb='', n_polls=9999): ...
111
def scope_str(*scopes) -> str: ...
112
```
113

114
[Authentication](./authentication.md)
115

116
### GitHub Actions Integration
117

118
Support for GitHub Actions workflows, contexts, events, and automation workflows including workflow creation and event handling.
119

120
```python { .api }
121
def user_repo(): ...
122
def create_workflow_files(): ...
123
def fill_workflow_templates(): ...
124
def create_workflow(): ...
125
def gh_create_workflow(): ...
126
def actions_output(): ...
127
def actions_debug(): ...
128
def actions_warn(): ...
129
def actions_error(): ...
130
def actions_group(): ...
131
def actions_mask(): ...
132
def set_git_user(): ...
133
```
134

135
[GitHub Actions](./github-actions.md)
136

137
### Pagination & Data Handling
138

139
Utilities for handling paginated API responses and parsing GitHub API response headers.
140

141
```python { .api }
142
def paged(oper, *args, per_page=30, max_pages=9999, **kwargs): ...
143
def pages(): ...
144
def parse_link_hdr(header): ...
145
```
146

147
[Pagination](./pagination.md)
148

149
### Event System
150

151
GitHub webhook event handling, event parsing, and sample event management for testing and development.
152

153
```python { .api }
154
class GhEvent: ...
155
def load_sample_events(): ...
156
def save_sample_events(): ...
157
```
158

159
[Events](./events.md)
160

161
### Command Line Interface
162

163
CLI tools for direct GitHub API access from the command line, including endpoint calling and tab completion.
164

165
```python { .api }
166
def ghapi(): ...
167
def ghpath(): ...
168
def ghraw(): ...
169
def completion_ghapi(): ...
170
```
171

172
[CLI Tools](./cli-tools.md)
173

174
## Types
175

176
```python { .api }
177
# Standard library imports used in API signatures
178
from datetime import datetime
179
from urllib.request import Request
180

181
# GitHub API endpoint groups (dynamically created)
182
class _GhVerbGroup:
183
    def __init__(self, name, verbs): ...
184

185
class _GhVerb:
186
    def __init__(self, path, verb, oper, summary, url, params, data, preview, client, kwargs): ...
187
    def __call__(self, *args, headers=None, **kwargs): ...
188

189
# Authentication scopes
190
Scope = AttrDict({
191
    'repo': 'repo',
192
    'repo_status': 'repo:status',
193
    'repo_deployment': 'repo_deployment',
194
    'public_repo': 'public_repo',
195
    'repo_invite': 'repo:invite',
196
    'security_events': 'security_events',
197
    'admin_repo_hook': 'admin:repo_hook',
198
    'write_repo_hook': 'write:repo_hook',
199
    'read_repo_hook': 'read:repo_hook',
200
    'admin_org': 'admin:org',
201
    'write_org': 'write:org',
202
    'read_org': 'read:org',
203
    'admin_public_key': 'admin:public_key',
204
    'write_public_key': 'write:public_key',
205
    'read_public_key': 'read:public_key',
206
    'admin_org_hook': 'admin:org_hook',
207
    'gist': 'gist',
208
    'notifications': 'notifications',
209
    'user': 'user',
210
    'read_user': 'read:user',
211
    'user_email': 'user:email',
212
    'user_follow': 'user:follow',
213
    'delete_repo': 'delete_repo',
214
    'write_discussion': 'write:discussion',
215
    'read_discussion': 'read:discussion',
216
    'write_packages': 'write:packages',
217
    'read_packages': 'read:packages',
218
    'delete_packages': 'delete:packages',
219
    'admin_gpg_key': 'admin:gpg_key',
220
    'write_gpg_key': 'write:gpg_key',
221
    'read_gpg_key': 'read:gpg_key',
222
    'workflow': 'workflow'
223
})
224

225
# GitHub Actions event types
226
Event = str_enum('Event', [
227
    'page_build', 'content_reference', 'repository_import', 'create', 'workflow_run',
228
    'delete', 'organization', 'sponsorship', 'project_column', 'push', 'context',
229
    'milestone', 'project_card', 'project', 'package', 'pull_request',
230
    'repository_dispatch', 'team_add', 'workflow_dispatch', 'member', 'meta',
231
    'code_scanning_alert', 'public', 'needs', 'check_run', 'security_advisory',
232
    'pull_request_review_comment', 'org_block', 'commit_comment', 'watch',
233
    'marketplace_purchase', 'star', 'installation_repositories', 'check_suite',
234
    'github_app_authorization', 'team', 'status', 'repository_vulnerability_alert',
235
    'pull_request_review', 'label', 'installation', 'release', 'issues',
236
    'repository', 'gollum', 'membership', 'deployment', 'deploy_key',
237
    'issue_comment', 'ping', 'deployment_status', 'fork', 'schedule'
238
])
239

240
# Context objects for GitHub Actions
241
context_github: dict
242
context_env: dict  
243
context_job: dict
244
context_steps: dict
245
context_runner: dict
246
context_secrets: dict
247
context_strategy: dict
248
context_matrix: dict
249
context_needs: dict
250

251
# Environment data
252
env_github: dict
253

254
# Constants
255
GH_HOST: str = "https://api.github.com"
256
EMPTY_TREE_SHA: str = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
257
contexts: tuple = ('github', 'env', 'job', 'steps', 'runner', 'secrets', 'strategy', 'matrix', 'needs')
258
```