GitHub

This part of the documentation covers the GitHub object. A large portion of what you will likely want to do can be found in this class. If you’re looking for anonymous functions, you’re most likely looking for the API.

Examples

Examples utilizing this object can be found here.

GitHub Object

class github3.github.GitHub(login='', password='', token='')

Stores all the session information.

There are two ways to log into the GitHub API

from github3 import login
g = login(user, password)
g = login(token=token)
g = login(user, token=token)

or

from github3 import GitHub
g = GitHub(user, password)
g = GitHub(token=token)
g = GitHub(user, token=token)

This is simple backward compatibility since originally there was no way to call the GitHub object with authentication parameters.

authorization(id_num)

Get information about authorization id.

Parameters:id_num (int) – (required), unique id of the authorization Returns:Authorization

authorize(login, password, scopes, note='', note_url='', client_id='', client_secret='')

Obtain an authorization token from the GitHub API for the GitHub API.

Parameters:

• login (str) – (required)
• password (str) – (required)
• scopes (list) – (required), areas you want this token to apply to, i.e., ‘gist’, ‘user’
• note (str) – (optional), note about the authorization
• note_url (str) – (optional), url for the application
• client_id (str) – (optional), 20 character OAuth client key for which to create a token
• client_secret (str) – (optional), 40 character OAuth client secret for which to create the token

Returns:

Authorization

check_authorization(access_token)

OAuth applications can use this method to check token validity without hitting normal rate limits because of failed login attempts. If the token is valid, it will return True, otherwise it will return False.

Returns:bool

create_gist(description, files, public=True)

Create a new gist.

If no login was provided, it will be anonymous.

Parameters:

• description (str) – (required), description of gist
• files (dict) – (required), file names with associated dictionaries for content, e.g. {'spam.txt': {'content': 'File contents ...'}}
• public (bool) – (optional), make the gist public if True

Returns:

Gist

create_issue(owner, repository, title, body=None, assignee=None, milestone=None, labels=[])

Create an issue on the project ‘repository’ owned by ‘owner’ with title ‘title’.

body, assignee, milestone, labels are all optional.

Parameters:

• owner (str) – (required), login of the owner
• repository (str) – (required), repository name
• title (str) – (required), Title of issue to be created
• body (str) – (optional), The text of the issue, markdown formatted
• assignee (str) – (optional), Login of person to assign the issue to
• milestone (str) – (optional), Which milestone to assign the issue to
• labels (list) – (optional), List of label names.

Returns:

Issue

create_key(title, key)

Create a new key for the authenticated user.

Parameters:

• title (str) – (required), key title
• key – (required), actual key contents, accepts path as a string or file-like object

Returns:

Key

create_repo(name, description='', homepage='', private=False, has_issues=True, has_wiki=True, has_downloads=True, auto_init=False, gitignore_template='')

Create a repository for the authenticated user.

Parameters:

• name (str) – (required), name of the repository
• description (str) – (optional)
• homepage (str) – (optional)
• private (str) – (optional), If True, create a private repository. API default: False
• has_issues (bool) – (optional), If True, enable issues for this repository. API default: True
• has_wiki (bool) – (optional), If True, enable the wiki for this repository. API default: True
• has_downloads (bool) – (optional), If True, enable downloads for this repository. API default: True
• auto_init (bool) – (optional), auto initialize the repository
• gitignore_template (str) – (optional), name of the git template to use; ignored if auto_init = False.

Returns:

Repository

delete_key(key_id)

Delete user key pointed to by key_id.

Parameters:key_id (int) – (required), unique id used by Github Returns:bool

follow(login)

Make the authenticated user follow login.

Parameters:login (str) – (required), user to follow Returns:bool

classmethod from_json(json)

Return an instance of cls formed from json.

gist(id_num)

Gets the gist using the specified id number.

Parameters:id_num (int) – (required), unique id of the gist Returns:Gist

gitignore_template(language)

Returns the template for language.

Returns:str

gitignore_templates()

Returns the list of available templates.

Returns:list of template names

is_following(login)

Check if the authenticated user is following login.

Parameters:login (str) – (required), login of the user to check if the authenticated user is checking Returns:bool

is_starred(login, repo)

Check if the authenticated user starred login/repo.

Parameters:

• login (str) – (required), owner of repository
• repo (str) – (required), name of repository

Returns:

bool

is_subscribed(login, repo)

Check if the authenticated user is subscribed to login/repo.

Parameters:

• login (str) – (required), owner of repository
• repo (str) – (required), name of repository

Returns:

bool

issue(owner, repository, number)

Fetch issue #:number: from https://github.com/:owner:/:repository:

Parameters:

• owner (str) – (required), owner of the repository
• repository (str) – (required), name of the repository
• number (int) – (required), issue number

Returns:

Issue

iter_all_repos(number=-1, since=None, etag=None)

Iterate over every repository in the order they were created.

Parameters:

• number (int) – (optional), number of repositories to return. Default: -1, returns all of them
• since (int) – (optional), last repository id seen (allows restarting this iteration)
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Repository

iter_all_users(number=-1, etag=None)

Iterate over every user in the order they signed up for GitHub.

Parameters:

• number (int) – (optional), number of users to return. Default: -1, returns all of them
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of User

iter_authorizations(number=-1, etag=None)

Iterate over authorizations for the authenticated user. This will return a 404 if you are using a token for authentication.

Parameters:

• number (int) – (optional), number of authorizations to return. Default: -1 returns all available authorizations
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Authorizations

iter_emails(number=-1, etag=None)

Iterate over email addresses for the authenticated user.

Parameters:

• number (int) – (optional), number of email addresses to return. Default: -1 returns all available email addresses
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of dicts

iter_events(number=-1, etag=None)

Iterate over public events.

Parameters:

• number (int) – (optional), number of events to return. Default: -1 returns all available events
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Events

iter_followers(login=None, number=-1, etag=None)

If login is provided, iterate over a generator of followers of that login name; otherwise return a generator of followers of the authenticated user.

Parameters:

• login (str) – (optional), login of the user to check
• number (int) – (optional), number of followers to return. Default: -1 returns all followers
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Users

iter_following(login=None, number=-1, etag=None)

If login is provided, iterate over a generator of users being followed by login; otherwise return a generator of people followed by the authenticated user.

Parameters:

• login (str) – (optional), login of the user to check
• number (int) – (optional), number of people to return. Default: -1 returns all people you follow
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Users

iter_gists(username=None, number=-1, etag=None)

If no username is specified, GET /gists, otherwise GET /users/:username/gists

Parameters:

• login (str) – (optional), login of the user to check
• number (int) – (optional), number of gists to return. Default: -1 returns all available gists
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Gists

iter_issues(filter='', state='', labels='', sort='', direction='', since='', number=-1, etag=None)

List all of the authenticated user’s (and organization’s) issues.

Parameters:

• filter (str) – accepted values: (‘assigned’, ‘created’, ‘mentioned’, ‘subscribed’) api-default: ‘assigned’
• state (str) – accepted values: (‘open’, ‘closed’) api-default: ‘open’
• labels (str) – comma-separated list of label names, e.g., ‘bug,ui,@high’
• sort (str) – accepted values: (‘created’, ‘updated’, ‘comments’) api-default: created
• direction (str) – accepted values: (‘asc’, ‘desc’) api-default: desc
• since (str) – ISO 8601 formatted timestamp, e.g., 2012-05-20T23:10:27Z
• number (int) – (optional), number of issues to return. Default: -1 returns all issues
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Issue

iter_keys(number=-1, etag=None)

Iterate over public keys for the authenticated user.

Parameters:

• number (int) – (optional), number of keys to return. Default: -1 returns all your keys
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Keys

iter_notifications(all=False, participating=False, number=-1, etag=None)

Iterate over the user’s notification.

Parameters:

• all (bool) – (optional), iterate over all notifications
• participating (bool) – (optional), only iterate over notifications in which the user is participating
• number (int) – (optional), how many notifications to return
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Thread

iter_org_issues(name, filter='', state='', labels='', sort='', direction='', since='', number=-1, etag=None)

Iterate over the organnization’s issues if the authenticated user belongs to it.

Parameters:

• name (str) – (required), name of the organization
• filter (str) – accepted values: (‘assigned’, ‘created’, ‘mentioned’, ‘subscribed’) api-default: ‘assigned’
• state (str) – accepted values: (‘open’, ‘closed’) api-default: ‘open’
• labels (str) – comma-separated list of label names, e.g., ‘bug,ui,@high’
• sort (str) – accepted values: (‘created’, ‘updated’, ‘comments’) api-default: created
• direction (str) – accepted values: (‘asc’, ‘desc’) api-default: desc
• since (str) – ISO 8601 formatted timestamp, e.g., 2012-05-20T23:10:27Z
• number (int) – (optional), number of issues to return. Default: -1, returns all available issues
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Issue

iter_orgs(login=None, number=-1, etag=None)

Iterate over public organizations for login if provided; otherwise iterate over public and private organizations for the authenticated user.

Parameters:

• login (str) – (optional), user whose orgs you wish to list
• number (int) – (optional), number of organizations to return. Default: -1 returns all available organizations
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Organizations

iter_repo_issues(owner, repository, milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None)

List issues on owner/repository. Only owner and repository are required.

Parameters:

• owner (str) – login of the owner of the repository
• repository (str) – name of the repository
• milestone (int) – None, ‘*’, or ID of milestone
• state (str) – accepted values: (‘open’, ‘closed’) api-default: ‘open’
• assignee (str) – ‘*’ or login of the user
• mentioned (str) – login of the user
• labels (str) – comma-separated list of label names, e.g., ‘bug,ui,@high’
• sort (str) – accepted values: (‘created’, ‘updated’, ‘comments’) api-default: created
• direction (str) – accepted values: (‘asc’, ‘desc’) api-default: desc
• since (str) – ISO 8601 formatted timestamp, e.g., 2012-05-20T23:10:27Z
• number (int) – (optional), number of issues to return. Default: -1 returns all issues
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Issues

iter_repos(type=None, sort=None, direction=None, number=-1, etag=None)

List public repositories for the authenticated user.

Changed in version 0.6: Removed the login parameter for correctness. Use iter_user_repos instead

Parameters:

• type (str) – (optional), accepted values: (‘all’, ‘owner’, ‘public’, ‘private’, ‘member’) API default: ‘all’
• sort (str) – (optional), accepted values: (‘created’, ‘updated’, ‘pushed’, ‘full_name’) API default: ‘created’
• direction (str) – (optional), accepted values: (‘asc’, ‘desc’), API default: ‘asc’ when using ‘full_name’, ‘desc’ otherwise
• number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Repository objects

iter_starred(login=None, sort=None, direction=None, number=-1, etag=None)

Iterate over repositories starred by login or the authenticated user.

Changed in version 0.5: Added sort and direction parameters (optional) as per the change in GitHub’s API.

Parameters:

• login (str) – (optional), name of user whose stars you want to see
• sort (str) – (optional), either ‘created’ (when the star was created) or ‘updated’ (when the repository was last pushed to)
• direction (str) – (optional), either ‘asc’ or ‘desc’. Default: ‘desc’
• number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Repository

iter_subscriptions(login=None, number=-1, etag=None)

Iterate over repositories subscribed to by login or the authenticated user.

Parameters:

• login (str) – (optional), name of user whose subscriptions you want to see
• number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Repository

iter_user_issues(filter='', state='', labels='', sort='', direction='', since='', number=-1, etag=None)

List only the authenticated user’s issues. Will not list organization’s issues

Parameters:

• filter (str) – accepted values: (‘assigned’, ‘created’, ‘mentioned’, ‘subscribed’) api-default: ‘assigned’
• state (str) – accepted values: (‘open’, ‘closed’) api-default: ‘open’
• labels (str) – comma-separated list of label names, e.g., ‘bug,ui,@high’
• sort (str) – accepted values: (‘created’, ‘updated’, ‘comments’) api-default: created
• direction (str) – accepted values: (‘asc’, ‘desc’) api-default: desc
• since (str) – ISO 8601 formatted timestamp, e.g., 2012-05-20T23:10:27Z
• number (int) – (optional), number of issues to return. Default: -1 returns all issues
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Issue

iter_user_repos(login, type=None, sort=None, direction=None, number=-1, etag=None)

List public repositories for the specified login.

New in version 0.6.

Parameters:

• login (str) – (required), username
• type (str) – (optional), accepted values: (‘all’, ‘owner’, ‘member’) API default: ‘all’
• sort (str) – (optional), accepted values: (‘created’, ‘updated’, ‘pushed’, ‘full_name’) API default: ‘created’
• direction (str) – (optional), accepted values: (‘asc’, ‘desc’), API default: ‘asc’ when using ‘full_name’, ‘desc’ otherwise
• number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of Repository objects

key(id_num)

Gets the authenticated user’s key specified by id_num.

Parameters:id_num (int) – (required), unique id of the key Returns:Key

login(username=None, password=None, token=None)

Logs the user into GitHub for protected API calls.

Parameters:

• username (str) – (optional)
• password (str) – (optional)
• token (str) – (optional)

markdown(text, mode='', context='', raw=False)

Render an arbitrary markdown document.

Parameters:

• text (str) – (required), the text of the document to render
• mode (str) – (optional), ‘markdown’ or ‘gfm’
• context (str) – (optional), only important when using mode ‘gfm’, this is the repository to use as the context for the rendering
• raw (bool) – (optional), renders a document like a README.md, no gfm, no context

Returns:

str – HTML formatted text

meta()

Returns an array of addresses in CIDR format specifying the addresses that the incoming service hooks will originate from.

New in version 0.5.

octocat(say=None)

Returns an easter egg of the API.

Params str say:(optional), pass in what you’d like Octocat to say Returns:ascii art of Octocat

organization(login)

Returns a Organization object for the login name

Parameters:login (str) – (required), login name of the org Returns:Organization

pubsubhubbub(mode, topic, callback, secret='')

Create/update a pubsubhubbub hook.

Parameters:

• mode (str) – (required), accepted values: (‘subscribe’, ‘unsubscribe’)
• topic (str) – (required), form: https://github.com/:user/:repo/events/:event
• callback (str) – (required), the URI that receives the updates
• secret (str) – (optional), shared secret key that generates a SHA1 HMAC of the payload content.

Returns:

bool

pull_request(owner, repository, number)

Fetch pull_request #:number: from :owner:/:repository

Parameters:

• owner (str) – (required), owner of the repository
• repository (str) – (required), name of the repository
• number (int) – (required), issue number

Returns:

Issue

ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

refresh(conditional=False)

Re-retrieve the information for this object and returns the refreshed instance.

Parameters:conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs Returns:self

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('kennethreitz')]

Without the return value, that would be an array of None‘s and you would otherwise have to do:

repos = [r for i in g.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

repository(owner, repository)

Returns a Repository object for the specified combination of owner and repository

Parameters:

• owner (str) – (required)
• repository (str) – (required)

Returns:

Repository

search_email(email)

Search users by email.

Parameters:email (str) – (required) Returns:LegacyUser

search_issues(owner, repo, state, keyword, start_page=0)

Find issues by state and keyword.

Parameters:

• owner (str) – (required)
• repo (str) – (required)
• state (str) – (required), accepted values: (‘open’, ‘closed’)
• keyword (str) – (required), what to search for
• start_page (int) – (optional), page to get (results come 100/page)

Returns:

list of LegacyIssues

search_repos(keyword, language=None, start_page=None, sort=None, order=None)

Search all repositories by keyword.

Parameters:

• keyword (str) – (required)
• language (str) – (optional), language to filter by
• start_page (int) – (optional), page to get (results come 100/page)
• sort (str) – (optional), how to sort the results; accepted values: (‘stars’, ‘forks’, ‘updated’)
• order (str) – (optional), sort order if sort isn’t provided, accepted values: (‘asc’, ‘desc’)

Returns:

list of LegacyRepos

search_users(keyword, start_page=0, sort=None, order=None)

Search all users by keyword.

Parameters:

• keyword (str) – (required)
• start_page (int) – (optional), page to get (results come 100/page)
• sort (str) – (optional), how to sort the results; accepted values: (‘followers’, ‘joined’, ‘repositories’)
• order (str) – (optional), sort order if sort isn’t provided, accepted values: (‘asc’, ‘desc’)

Returns:

list of LegacyUsers

set_client_id(id, secret)

Allows the developer to set their client_id and client_secret for their OAuth application.

Parameters:

• id (str) – 20-character hexidecimal client_id provided by GitHub
• secret (str) – 40-character hexidecimal client_secret provided by GitHub

set_user_agent(user_agent)

Allows the user to set their own user agent string to identify with the API.

Parameters:user_agent (str) – String used to identify your application. Library default: “github3.py/{version}”, e.g., “github3.py/0.5”

star(login, repo)

Star to login/repo

Parameters:

• login (str) – (required), owner of the repo
• repo (str) – (required), name of the repo

Returns:

bool

subscribe(login, repo)

Subscribe to login/repo

Parameters:

• login (str) – (required), owner of the repo
• repo (str) – (required), name of the repo

Returns:

bool

to_json()

Return the json representing this object.

unfollow(login)

Make the authenticated user stop following login

Parameters:login (str) – (required) Returns:bool

unstar(login, repo)

Unstar to login/repo

Parameters:

• login (str) – (required), owner of the repo
• repo (str) – (required), name of the repo

Returns:

bool

unsubscribe(login, repo)

Unsubscribe to login/repo

Parameters:

• login (str) – (required), owner of the repo
• repo (str) – (required), name of the repo

Returns:

bool

update_user(name=None, email=None, blog=None, company=None, location=None, hireable=False, bio=None)

If authenticated as this user, update the information with the information provided in the parameters. All parameters are optional.

Parameters:

• name (str) – e.g., ‘John Smith’, not login name
• email (str) – e.g., 'john.smith@example.com‘
• blog (str) – e.g., ‘http://www.example.com/jsmith/blog‘
• company (str) – company name
• location (str) – where you are located
• hireable (bool) – defaults to False
• bio (str) – GitHub flavored markdown

Returns:

bool

user(login=None)

Returns a User object for the specified login name if provided. If no login name is provided, this will return a User object for the authenticated user.

Parameters:login (str) – (optional) Returns:User

zen()

Returns a quote from the Zen of GitHub. Yet another API Easter Egg

Returns:str

GitHubEnterprise Object

This has all of the same attributes ass the GitHub object so for brevity’s sake, I’m not listing all of it’s inherited members.

class github3.github.GitHubEnterprise(url, login='', password='', token='')

For GitHub Enterprise users, this object will act as the public API to your instance. You must provide the URL to your instance upon initializaiton and can provide the rest of the login details just like in the GitHub object.

There is no need to provide the end of the url (e.g., /api/v3/), that will be taken care of by us.

admin_stats(option)

This is a simple way to get statistics about your system.

Parameters:option (str) – (required), accepted values: (‘all’, ‘repos’, ‘hooks’, ‘pages’, ‘orgs’, ‘users’, ‘pulls’, ‘issues’, ‘milestones’, ‘gists’, ‘comments’) Returns:dict

GitHubStatus Object

class github3.github.GitHubStatus

A sleek interface to the GitHub System Status API. This will only ever return the JSON objects returned by the API.

api()

GET /api.json

last_message()

GET /api/last-message.json

messages()

GET /api/messages.json

status()

GET /api/status.json