Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Python interface for talking to the github API
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
github
.gitignore
AUTHORS
COPYING
LICENSE
MANIFEST.in
README.markdown
setup.py

README.markdown

What's on Github?

This is a library that implements github's API in python.

Supported APIs

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.

User

The user API is available via gh.users.

Search

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

Show

Get details about an individual user.

username = 'dustin'
print "%s's web site:  %s" % (username, gh.users.show(username).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)

Keys

List your ssh keys:

print "Names of my keys:"
for k in list(agh.users.keys()):
    print(k.title)

Repositories

The repository API is available via gh.repos.

Repository List for a User

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)

Branches Within a Repo

List the branches within a repo:

print("memcached branches:")
for branchname, branchhash in gh.repos.branches('dustin', 'memcached'):
    print(branchname)

Search for a Repository

for r in gh.repos.search('memcached'):
    print("%s's %s" % (r.username, r.name))

Show a Repository

Retrieve an individual repository.

print(gh.repos.show('dustin', 'py-github').homepage)

Watch a Repository

Begin watching a repository.

gh.repos.watch('dustin', 'memcached')

Unwatch a Repository

Stop watching a repository.

gh.repos.unwatch('dustin', 'memcached')

Get a Repository's Network

Retrieve the network for a repository.

for r in gh.repos.network('dustin', 'memcached'):
    print("%s's %s" % (r.owner, r.name))

Adjust a Repository's Visibility

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)

Create a New Repository

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)

Deleting a Repository

You may delete repositories attached to your account only.

agh.repos.delete('testrepo')

Forking a Repository

agh.repos.fork('dustin', 'memcached')

Adding a Collaborator

agh.repos.addCollaborator('memcached', 'trondn')

Removing a Collaborator

agh.repos.removeCollaborator('memcached', 'trondn')

Listing Deploy Keys

agh.repos.deployKeys('myrepo')

Add a Deploy Key

keyContents = open(os.path.expanduser("~/.ssh/id_dsa.pub")).read()
agh.repos.addDeployKey('myrepo', 'Key Name', keyContents)

Remove a Deploy Key

agh.repos.removeDeployKey('myrepo', 8582)

Commits

The commit API is available via gh.commits.

Get the Commits from a Branch

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]))

Get the Commits Affecting a File

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]))

Show a Specific Commit

print gh.commits.show('dustin', 'memcached',
    '923a335bf8613696d658448cd9c48a963924d436').message

Issues

The issues api is available via gh.issues.

List Repository Issues

for i in gh.issues.list('dustin', 'py-github'):
    print("issue #%s:  %s" % (i.number, i.title))

Show a Particular Issue

i = gh.issues.show('dustin', 'py-github', 1)
print("%s:  %s" % (i.state, i.title))

Add a Label to an Issue

agh.issues.add_label('dustin', 'py-github', 38, 'awesome')

Remove a Label from an Issue

agh.issues.remove_label('dustin', 'py-github', 38, 'fun')

Close an Issue

agh.issues.close('dustin', 'py-github', 38)

Reopen a Closed Issue

agh.issues.reopen('dustin', 'py-github', 38)

Create a New Issue

agh.issues.new('dustin', 'py-github', 'more code', 'Write more code.')

The body parameter (last) is optional.

Edit an Existing Issue

agh.issues.edit('dustin', 'py-github', 8284, 'New Title', 'New Body')

Objects

The objects API is available via gh.objects.

Get a Tree

Retreive the tree object with the given hash:

t = gh.objects.tree('dustin', 'py-github',
    'b34f658fd7be0d3e00cc961b75da10ca0d44d050')
for k,v in list(t.items()):
    print "%s\t%s\t%s" % (v.sha, v.type, k)

Retrieve a Blob (with info)

b = gh.objects.blob('dustin', 'py-github',
    'b34f658fd7be0d3e00cc961b75da10ca0d44d050', 'README.markdown')
print b.data

Retrieve a Raw Blob

print b.raw_blob('dustin', 'py-github',
    'a1ae3723758a0dc1ea857e9efe6640f18a6b3865')

Organizations

The organizations API is available via gh.organizations.

Getting Organization Information

Get the full information on organizations by the screen name.

org = 'ff0000'
print "%s's location:  %s" % (org, gh.organizations.show(org).location)

Updating fields

Owners can update the organization with these fields:

  • name
  • email
  • blog
  • company
  • location
  • billing_email

    org = 'ff0000' print "%s's old location: %s" % (org, gh.organizations.show(org).location) agh.organizations.set('ff0000', location='Los Angeles, CA')

Checking Organization Membership

Get all the public organizations that a user is part of. If you are authenticated, concealed memberships will also be returned.

print "My organizations:"
for org in gh.organizations.forUser(me):
    print org

Listing Organization Memberships

List all repositories across all the organizations that you can access.

print "Repositories of my organizations:"
for repo in agh.organizations.repositories():
    print repo.name

List all members of the organization's Owners team:

print "Owner of my organization:"
for owner in agh.organizations.owners('ff0000'):
    print owner.name

List all public repositories of any other organization:

print "Public repositories of the github organization:"
for repo in gh.organizations.publicRepositories('github'):
    print repo.name

List all public members of any organization:

print "Public members of the github organization:"
for member in gh.organizations.publicMembers('github'):
    print member.name
Something went wrong with that request. Please try again.