Overview¶
tests | |
---|---|
package | |
docs |
Python client for GitHub API
Installation¶
requires python 3.5+
Yes that is opinionated. Python 2 is near the end of the life and this is a new project.
Note octokit and octokit.py were already taken in the cheese shop
pip install octokitpy
Documentation¶
https://octokitpy.readthedocs.io/en/latest/
Examples¶
REST API:
from octokit import Octokit
repos = Octokit().repos.get_for_org(org='octokit', type='public')
# Make an unauthenticated request for the public repositories of the octokit organization
Webhooks:
from octokit import webhook
webhook.verify(headers, payload, secret, events=['push'])
octokit.py
provides a function to verify webhooks sent to your application.
- headers
- dictionary of request headers
- payload
- string; payload of request
- secret
- string; secret provided to GitHub to sign webhook
- events
- list; events that you want to receive
- verify_user_agent
- boolean; whether or not you want to verify the user agent string of the request
- return_app_id
- boolean; whether or not you want to return the app id from the ping event for GitHub applications. This will only return the
id
if the event is theping
event. Otherwise the return value will be boolean.
Authentication¶
Instatiate a client with the authentication scheme and credentials that you want to use.
basic:
octokit = Octokit(auth='basic', username='myuser', password='mypassword')
octokit.repos.get_for_org(org='octokit', type='private')
token:
response = Octokit(auth='token', token='yak').authorization.get(id=100)
app:
octokit = Octokit(auth='app', app_id='42', private_key=private_key)
app installation:
octokit = Octokit(auth='installation', app_id='42', private_key=private_key)
For applications provide the application id either from the ping webhook or the application’s page on GitHub.
The private_key
is a string of your private key provided for the application.
The app
scheme will use the application id and private key to get a token for the first installation id of the application.
API Schema/Routes/Specifications¶
One can instantiate the Octokit
with routes=specification
where the specification
is one of api.github.com
, ghe-2.15
, etc.
TODOs¶
GitHub APIs¶
[-] REST (see best practices, integration tests, and errors)
[ ] GraphQL client
[x] GitHub Apps
[ ] OAuth Apps
[x] Webhooks
Data¶
The octokit
client based on the available route data and webhook data
[x] Periodically, check if ``routes.json`` has changed and if so fetch and open a PR for it to be merged
[ ] Periodically, check if ``webhook-names.json`` has changed and if so fetch and open a PR for it to be merged
Tests¶
[x] unit tests
[ ] integration tests - need fixtures to assert against
[ ] coverage uploaded to code climate -- not sure why it is not working
Errors¶
[ ] Raise :code:`OctokitValidationError` for param validation error
[ ] Raise :code:`OctokitAuthenticationError` for auth error
[ ] Raise :code:`OctokitRateLimitError` for rate limiting errors
Best Practices¶
[ ] throttling
[ ] handles rate limiting
[x] pagination
Documentation¶
[ ] Auto generated documentation
Deployment¶
[x] Deploy wheels
[ ] Make GitHub releases work
Check box guide
[ ] Incomplete
[-] Partially completed
[x] Completed
Credits¶
Package based on cookiecutter-pylibrary
License¶
MIT