This is a library that implements github's API in python.
All API access begins with the creation of a GitHub object. For the sake of brevity, this document assumes you've created an object called gh as a github endpoint:
gh = github.GitHub() Some operations require (or are enhanced by) authentication. These are noted within the documentation and will use an object called agh created the following way:
agh = github.GitHub('myusername', 'mytoken') You can find your token from your account page.
The user API is available via gh.users.
This is a simple user search call. All properties returned by the API will be available as properties.
Example displaying search results using the name and fullname properties:
for u in gh.users.search(myquery): print "User: %s (%s)" % (u.name, u.fullname) Get details about an individual user.
username = 'dustin' print "%s's web site: %s" % (username, gh.users.show(%s).blog) Note that this API returns more information if you're authenticated and ask for yourself:
print "My disk usage: %d" % agh.users.show(me).disk_usage List your ssh keys:
print "Names of my keys:" for k in agh.users.keys(): print k.title The repository API is available via gh.repos.
List the repositories owned by a user. If you are authenticated this user, private repositories will also be returned.
print "My repo names:" for r in gh.repos.forUser(me): print r.name List the branches within a repo:
print "memcached branches:" for branchname, branchhash in gh.repos.branches('dustin', 'memcached'): print branchname for r in gh.repos.search('memcached'): print "%s's %s" % (r.username, r.name) Retrieve an individual repository.
print gh.repos.show('dustin', 'py-github').homepage Begin watching a repository.
gh.repos.watch('dustin', 'memcached') Stop watching a repository.
gh.repos.unwatch('dustin', 'memcached') Retrieve the network for a repository.
for r in gh.repos.network('dustin', 'memcached'): print "%'s %s" % (r.owner_name, r.name) You can adjust repository visibility for your own repositories only (therefore the username is omitted).
To set a repository public:
agh.repos.setVisible('repo-name') To set a repository private:
agh.repos.setVisible('repo-name', False) The most simple invocation (create a public repository with no description or URL) would look like this:
agh.repos.create('testrepository') You can pass many flags in to set up the repository, however. Consider this case where a private repository is created.
agh.repos.create('testrepo', description='My test repo', homepage='http://www.spy.net/', public=0) You may delete repositories attached to your account only.
agh.repos.delete('testrepo') agh.repos.fork('dustin', 'memcached') agh.repos.addCollaborator('memcached', 'trondn') agh.repos.removeCollaborator('memcached', 'trondn') agh.repos.deployKeys('myrepo') keyContents = open(os.path.expanduser("~/.ssh/id_dsa.pub")).read() agh.repos.addDeployKey('myrepo', 'Key Name', keyContents) agh.repos.removeDeployKey('myrepo', 8582) The commit API is available via gh.commits.
Master is assumed:
for c in gh.commits.forBranch('dustin', 'py-github'): print "%s %s" % (c.id[:7], c.message[:60].split("\n")[0]) Otherwise, you can specify a branch name:
for c in gh.commits.forBranch('dustin', 'py-github', 'v2'): print "%s %s" % (c.id[:7], c.message[:60].split("\n")[0]) Retrieve all of the commits for the specified file. Again, master is assumed):
for c in gh.commits.forFile('dustin', 'py-github', 'README.markdown'): print "%s %s" % (c.id[:7], c.message[:60].split("\n")[0]) ...but you can also specify a branch name:
for c in gh.commits.forFile('dustin', 'py-github', 'README.markdown', 'v2'): print "%s %s" % (c.id[:7], c.message[:60].split("\n")[0]) print gh.commits.show('dustin', 'memcached', '923a335bf8613696d658448cd9c48a963924d436').message The issues api is available via gh.issues.
for i in gh.issues.list('dustin', 'py-github'): print "issue #%s: %s" % (i.number, i.title) i = gh.issues.show('dustin', 'py-github', 1) print "%s: %s" % (i.state, i.title) agh.issues.add_label('dustin', 'py-github', 38, 'awesome') agh.issues.remove_label('dustin', 'py-github', 38, 'fun') agh.issues.close('dustin', 'py-github', 38) agh.issues.reopen('dustin', 'py-github', 38) agh.issues.new('dustin', 'py-github', 'more code', 'Write more code.') The body parameter (last) is optional.
agh.issues.edit('dustin', 'py-github', 8284, 'New Title', 'New Body') The objects API is available via gh.objects.
Retreive the tree object with the given hash:
t = gh.objects.tree('dustin', 'py-github', 'b34f658fd7be0d3e00cc961b75da10ca0d44d050') for k,v in t.items(): print "%s\t%s\t%s" % (v.sha, v.type, k) b = gh.objects.blob('dustin', 'py-github', 'b34f658fd7be0d3e00cc961b75da10ca0d44d050', 'README.markdown') print b.data print b.raw_blob('dustin', 'py-github', 'a1ae3723758a0dc1ea857e9efe6640f18a6b3865')