python-github -----------
A simple python library to access the GitHub API.
API Usage all stems from the Github
object. You can instantiate one easily:
>>> import github
>>> gh = github.Github()
>>> gh
<Github API>
Github's API also has a lot of write access, and some private data for a user is only accessible when authenticated as that user. Github's auth is HTTP Basic over https, and you can authenticate with either a username/password pair or a username/token pair. Your token can be found in the _Account Admin section of your github account preferences. You can auth either of these two ways:
>>> gh = github.Github('jmoiron', 'mypassword') >>> gh <Github API (auth: jmoiron)> >>> gh = github.Github('jmoiron', token='mytokenwhichisquiteabitlonger') >>> gh <Github API (auth: jmoiron)>
If at any time you set the username
and one of the password
or token
attributes on the Github object, authentication becomes active on your subsequent requests.
Github
provides an objected oriented querying hierarchy that is based on ownership relationships between data on Github more than it is on the structure of the REST API itself:
>>> import pprint
>>> jmoiron = gh.user("jmoiron")
>>> jmoiron
<User: jmoiron>
>>> pprint.pprint(jmoiron.repositories())
[{u'created_at': u'2010/10/26 20:28:08 -0700',
u'description': u'python command-line photo management thing',
u'fork': False,
u'forks': 1,
u'name': u'iris',
...
]
>>> iris = jmoiron.repository('iris')
>>> iris
<Repository: jmoiron's iris>
>>> pprint.pprint(iris.commits()[0])
{u'author': {u'email': u'jmoiron@jmoiron.net',
u'login': u'jmoiron',
u'name': u'Jason Moiron'},
u'authored_date': u'2010-11-10T21:19:10-08:00',
u'committed_date': u'2010-11-10T21:19:10-08:00',
u'committer': {u'email': u'jmoiron@jmoiron.net',
u'login': u'jmoiron',
u'name': u'Jason Moiron'},
u'id': u'9cf5068398cfd1b2dbbaf86a33583a2ed395d259',
u'message': u'a little work on the shell side of parsing the queries',
u'parents': [{u'id': u'3291c3c8e891d0d00ca832450998446472bd902e'}],
u'tree': u'd61d15176f0a865365bb9cfaacad7286470626b4',
u'url': u'/jmoiron/iris/commit/9cf5068398cfd1b2dbbaf86a33583a2ed395d259'}
github
mostly returns results that are unmodified from what the Github REST API itself returns. The result formats can thus be mostly determined from _github's developer API documents.
Some parts of github's API limits the number of results returned on a request, and offers pagination to fetch older items. The calls that support this, notably User.repositories
and Repository.commits
support both direct access to paging via a page
kwarg as well as an all
kwarg that fetches all pages. Note that large repositories with thousands of commits could require more requests than fit within the 1-minute request limit for the Github API, which means passing all=true
can block for a substantial amount of time.
Github's API has access limits throttled to 60 accesses per minute. By default, Github
objects will obey these limits by waiting until 60 accesses have been made within a minute, and then waiting for the oldest access time + 60s to perform subsequent requests. If you want to disable this (at the risk of getting access limit errors from the Github API), pass throttle=False
to Github when instantiating a new handle.