A simple GitHub v3 API SDK for Python
githubpy is a simple Python SDK for GitHub's API v3. It's all contained in one easy-to-use file.
It runs on Python 2 (2.6 and above) and Python 3 (3.3 and above).
Sample code:
>>> gh = GitHub() >>> gh.users('michaelliao').get() {'public_repos': 11, 'name': u'Michael Liao', ... }
Requirement:
Python 2.6, 2.7, 3.3, 3.4
All APIs are dynamic calls. You can construct an API call by GitHub's API doc.
For example, according to GitHub API doc of how to get a single user:
GET /users/:user
Note the
:uservariable. You can make a call in Python like this:
>>> gh.users('michaelliao').get() {'public_repos': 11, 'name': u'Michael Liao', ...}
This returns a dict, but it can also be treated like an object:
>>> u['name'] u'Michael Liao' >>> u.name u'Michael Liao'
Another example of how to list issues for a repository:
GET /repos/:owner/:repo/issues Parameters milestone Integer Milestone number none for Issues with no Milestone. * for Issues with any Milestone. state open, closed, default: open assignee String User login none for Issues with no assigned User. * for Issues with any assigned User. ...
Python keywords can filter for
openissues assigned to
michaelliao:
>>> gh.repos('michaelliao')('githubpy').issues \ .get(state='open', assignee='michaelliao')
POST /repos/:owner/:repo/issues Input title Required string body Optional string assignee Optional string - Login for the user that this issue should be assigned to. ...
Python code to create an issue:
>>> gh.repos('michaelliao')('githubpy').issues \ .post(title='sample issue', body='found a bug')
Remember, all APIs are dynamic calls...so you won't need update this SDK if GitHub add new APIs!
Anonymous API call:
>>> gh = GitHub()
Basic authentication using username and password:
>>> gh = GitHub(username='«loginname»', password='«your-password»')
OAuth authentication is a bit complicated:
Step 1: Redirect user to the generated URL:
>>> gh = GitHub(client_id='1234', client_secret='secret') >>> print gh.authorize_url(state='a-random-string') 'https://github.com/login/oauth/authorize?client_id=1234'
Step 2: GitHub redirects back to your site with the parameters
codeand
state(optional). Then get an access token:
>>> code = request.input('code') >>> state = request.input('state') >>> print gh.get_access_token(code, state) 'abc1234567xyz'
Step 3: Using access token as authentication to call APIs:
>>> gh = GitHub(access_token='abc1234567xyz')
An
ApiErroris raised if something wrong. There are 2 sub-classes:
ApiAuthErrorand
ApiNotFoundError.
try: gh.user.emails.delete('[email protected]') except ApiNotFoundError as e: print e, e.request, e.response
NOTE: You may get
ApiNotFoundError(404 Not Found) even if the URL is correct, but authentication fails. According to GitHub's API docs:
Requests that require authentication will return 404, instead of 403, in some places. This is to prevent the accidental leakage of private repositories to unauthorized users.
You can check rate limits after any API call:
>>> u = gh.users('michaelliao').get() >>> gh.x_ratelimit_limit 5000 >>> gh.x_ratelimit_remaining 4999
githubpy is distributed under Apache License 2.0. See LICENSE file.