Documentation Overview¶

pygithub3 is a Github APIv3 python wrapper.

You can consume the API with several Services (users, repos...) like you see in Github API v3 documentation.

When you do an API request, pygithub3 map the result into Resources which can do its own related requests in future releases.

Fast sample¶

from pygithub3 import Github

gh = Github(login='octocat', password='password')

octocat = gh.users.get() # Auth required
copitux = gh.users.get('copitux')
# copitux = <User (copitux)>

octocat_followers = gh.users.followers.list().all()
copitux_followers = gh.users.followers.list('copitux').all()
# copitux_followers = [<User (ahmontero)>, <User (alazaro)>, ...]

Others¶

You must apologize my English level. I’m trying to do my best

Installation¶

pip install pygithub3

or

easy_install pygithub3

Dependencies¶

Required¶

This library depends only on the requests module.

If you install pygithub3 with pip all is done. This is the best option.

Optional¶

The test suite uses nose, mock, and unittest2 (python 2.6). Compiling the documentation requires sphinx.

Install all of these by running pip install -r test_requirements.txt. Then just run nosetests to run the tests.

Github¶

This is the main entrance of pygithub3

class pygithub3.Github(**config)¶

You can preconfigure all services globally with a config dict. See Service

Example:

gh = Github(user='kennethreitz', token='ABC...', repo='requests')

events¶: Events service

gists¶: Gists service

git_data¶: Git Data service

issues¶: Issues service

orgs¶: Orgs service

pull_requests¶: Pull Requests service

remaining_requests¶: Limit of Github API v3

repos¶: Repos service

users¶: Users service

Services¶

Github class is a glue to all of them and the recommended option to start

Overview¶

You can access to the API requests through the different services.

If you take a look at github API v3 documentation, you’ll see a few sections in the sidebar.

pygithub3 has one service per each section of request-related

For example:

repos => services.repos.repo
    collaborators => services.repos.collaborators
    commits => services.repos.commits
    ....

Each service has the functions to throw the API requests and is isolated from the rest.

Config each service¶

Each service can be configurated with some variables (behind the scenes, each service has her client which is configurated with this variables).

Note

Also you can configure Github as a service

class pygithub3.services.base.Service(**config)¶

You can configure each service with this keyword variables:

Parameters:

login (str) – Username to authenticate
password (str) – Username to authenticate
user (str) – Default username in requests
repo (str) – Default repository in requests
token (str) – Token to OAuth
per_page (int) – Items in each page of multiple returns
base_url (str) – To support another github-related API (untested)
verbose (stream) – Stream to write debug logs
float (timeout) – Timeout for requests

You can configure the authentication with BasicAuthentication (login and password) and with OAuth ( token). If you include login, password and token in config; Oauth has precedence

Some API requests need user and/or repo arguments (e.g repos service). You can configure the default value here to avoid repeating

Some API requests return multiple resources with pagination. You can configure how many items has each page.

You can configure verbose logging like requests library

set_credentials(login, password)¶

Set Basic Authentication

Parameters:	login (str) – Username to authenticate password (str) – Username to authenticate

set_repo(repo)¶

Set repository

Parameters:	repo (str) – Default repository in requests

set_token(token)¶

Set OAuth token

Parameters:	token (str) – Token to OAuth

set_user(user)¶

Set user

Parameters:	user (str) – Default username in requests

MimeTypes¶

Some services supports mimetypes

With them the Resources will have body, body_text, body_html attributes or all of them.

class pygithub3.services.base.MimeTypeMixin¶

Mimetype support to Services

Adds 4 public functions to service:

set_full()¶: Resource will have body, body_text and body_html attributes

set_html()¶: Resource will have body_html attribute

set_raw()¶: Resource will have body attribute

set_text()¶: Resource will have body_text attribute

Fast example:

from pygithub3 import Github

gh = Github()

gh.gists.comments.set_html()
comment = gh.gists.comments.list(1).all()[0]
print comment.body, comment.body_text, comment.body_html

List of services¶

Users services¶

Fast sample:

from pygithub3 import Github

auth = dict(login='octocat', password='pass')
gh = Github(**auth)

# Get copitux user
gh.users.get('copitux')

# Get copitux's followers
gh.users.followers.list('copitux')

# Get octocat's emails
gh.users.emails.list()

User¶

class pygithub3.services.users.User(**config)¶

Consume Users API

emails¶: Emails

keys¶: Keys

followers¶: Followers

get(user=None)¶

Get a single user

Parameters:	user (str) – Username

If you call it without user and you are authenticated, get the authenticated user.

Warning

If you aren’t authenticated and call without user, it returns 403

user_service.get('copitux')
user_service.get()

update(data)¶

Update the authenticated user

Parameters:	data (dict) – Input to update

user_service.update(dict(name='new_name', bio='new_bio'))

Emails¶

class pygithub3.services.users.Emails(**config)¶

Consume Emails API

Warning

You must be authenticated for all requests

add(*emails)¶

Add emails

Parameters:	emails (list) – Emails to add

Note

It rejects non-valid emails

email_service.add('test1@xample.com', 'test2@xample.com')

delete(*emails)¶

Delete emails

Parameters:	emails (list) – List of emails

email_service.delete('test1@xample.com', 'test2@xample.com')

list()¶

Get user’s emails

Returns:	A Result

Keys¶

class pygithub3.services.users.Keys(**config)¶

Consume Keys API

Warning

You must be authenticated for all requests

add(data)¶

Add a public key

Parameters:	data (dict) – Key (title and key attributes required)

key_service.add(dict(title='host', key='ssh-rsa AAA...'))

delete(key_id)¶

Delete a public key

Parameters:	key_id (int) – Key id

get(key_id)¶

Get a public key

Parameters:	key_id (int) – Key id

list()¶

Get public keys

Returns:	A Result

update(key_id, data)¶

Update a public key

Parameters:	key_id (int) – Key id data (dict) – Key (title and key attributes required)

key_service.update(42, dict(title='host', key='ssh-rsa AAA...'))

Followers¶

class pygithub3.services.users.Followers(**config)¶

Consume Followers API

follow(user)¶

Follow a user

Parameters:	user (str) – Username

Warning

You must be authenticated

is_following(user)¶

Check if you are following a user

Parameters:	user (str) – Username

list(user=None)¶

Get user’s followers

Parameters:	user (str) – Username
Returns:	A Result

If you call it without user and you are authenticated, get the authenticated user’s followers

Warning

If you aren’t authenticated and call without user, it returns 403

followers_service.list()
followers_service.list('octocat')

list_following(user=None)¶

Get who a user is following

Parameters:	user (str) – Username
Returns:	A Result

If you call it without user and you are authenticated, get the authenticated user’s followings

Warning

If you aren’t authenticated and call without user, it returns 403

followers_service.list_following()
followers_service.list_following('octocat')

unfollow(user)¶

Unfollow a user

Parameters:	user (str) – Username

Warning

You must be authenticated

Repos services¶

Fast sample:

from pygithub3 import Github

gh = Github()

django_compressor = gh.repos.get(user='jezdez', repo='django_compressor')
requests_collaborators = gh.repos.collaborators(user='kennethreitz',
    repo='requests')

Config precedence¶

Some request always need user and repo parameters, both, to identify a repository. Because there are a lot of requests which need that parameters, you can Config each service with user and repo globally.

So several requests follow a simple precedence user_in_arg > user_in_config | repo_in_arg > repo_in_config

You can see it better with an example:

from pygithub3 import Github

gh = Github(user='octocat', repo='oct_repo')
oct_repo = gh.repos.get()
another_repo_from_octocat = gh.repos.get(repo='another_repo')

django_compressor = gh.repos.get(user='jezdez', repo='django_compressor')

Note

Remember that each service is isolated from the rest

# continue example...
gh.repos.commits.set_user('copitux')
oct_repo = gh.repos.get()
oct_repo_collaborators = gh.repos.collaborators.list().all()

# Fail because copitux/oct_repo doesn't exist
gh.repos.commits.list_comments()

Repo¶

class pygithub3.services.repos.Repo(**config)¶

Consume Repos API

collaborators¶: Collaborators

commits¶: Commits

downloads¶: Downloads

forks¶: Forks

keys¶: Keys

watchers¶: Watchers

create(data, in_org=None)¶

Create a new repository

Parameters:	data (dict) – Input. See github repos doc in_org (str) – Organization where create the repository (optional)

Warning

You must be authenticated

If you use in_org arg, the authenticated user must be a member of <in_org>

repo_service.create(dict(name='new_repo', description='desc'))
repo_service.create(dict(name='new_repo_in_org', team_id=2300),
    in_org='myorganization')

delete(user=None, repo=None)¶

Delete a single repo

Parameters:	user (str) – Username repo (str) – Repository

Note

Documentation Overview¶

Fast sample¶

Others¶

Installation¶

Dependencies¶

Required¶

Optional¶

Github¶

Services¶

Overview¶

Config each service¶

MimeTypes¶

List of services¶

Users services¶

User¶

Emails¶

Keys¶

Followers¶

Repos services¶

Config precedence¶

Repo¶

Collaborators¶

Commits¶

Downloads¶

Forks¶

Keys¶

Watchers¶

Hooks¶

Gists services¶

Gist¶

Comments¶

Git Data services¶

GitData¶

Blobs¶

Commits¶

References¶

Tags¶

Trees¶

Pull Requests service¶

Pull Requests¶

Pull Request Comments¶

Orgs services¶

Org¶

Members¶

Teams¶

Issues services¶

Issues¶

Comments¶

Events¶

Labels¶

Milestones¶

Events service¶

Public Events¶

Repo Events¶

Organization Events¶

User Events¶

Result¶

Smart Result¶

Normal Result¶

Resources¶