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
```