API

This part of the documentation covers the API. This is intended to be a beautifully written module which allows the user (developer) to interact with github3.py elegantly and easily.

Module Contents

To interact with the GitHub API you can either authenticate to access protected functionality or you can interact with it anonymously. Authenticating provides more functionality to the the user (developer).

To authenticate, you simply use github3.login().

github3.login(username=None, password=None, token=None, two_factor_callback=None)

Construct and return an authenticated GitHub session.

Note

To allow you to specify either a username and password combination or a token, none of the parameters are required. If you provide none of them, you will receive None.

Parameters:
  • username (str) – login name
  • password (str) – password for the login
  • token (str) – OAuth token
  • two_factor_callback (func) – (optional), function you implement to provide the Two Factor Authentication code to GitHub when necessary
Returns:

GitHub

With the GitHub object that is returned you have access to more functionality. See that object’s documentation for more information.

To use the API anonymously, you can create a new GitHub object, e.g.,

from github3 import GitHub

gh = GitHub()

Or you can simply use the following functions


github3.authorize(username, password, scopes, note='', note_url='', client_id='', client_secret='', two_factor_callback=None, github=None)

Obtain an authorization token for the GitHub API.

Parameters:
  • username (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
  • two_factor_callback (func) – (optional), function to call when a Two-Factor Authentication code needs to be provided by the user.
  • github (GitHub) – (optional), GitHub (or GitHubEnterprise) object for login.
Returns:

Authorization


github3.create_gist(description, files)

Create an anonymous public gist.

Parameters:
  • description (str) – (required), short description of the gist
  • files (dict) – (required), file names with associated dictionaries for content, e.g. {‘spam.txt’: {‘content’: ‘File contents …’}}
Returns:

Gist


github3.gist(id_num)

Retrieve the gist identified by id_num.

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

github3.gitignore_template(language)

Return the template for language.

Returns:str

github3.gitignore_templates()

Return the list of available templates.

Returns:list of template names

github3.issue(owner, repository, number)

Anonymously gets issue :number on :owner/:repository.

Parameters:
  • owner (str) – (required), repository owner
  • repository (str) – (required), repository name
  • number (int) – (required), issue number
Returns:

Issue


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

Iterate over issues on owner/repository.

    Changed in version 0.9.0:
  • The state parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.

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: (‘all’, ‘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 (datetime or string) – (optional), Only issues after this date will be returned. This can be a datetime or an ISO8601 formatted date string, 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 ShortIssues


github3.all_repositories(number=-1, 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
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Repository


github3.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


github3.all_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 Event


github3.followers_of(username, number=-1, etag=None)

List the followers of username.

Parameters:
  • username (str) – (required), login of the person to list the followers of
  • number (int) – (optional), number of followers to return, Default: -1, return all of them
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of User


github3.followed_by(username, number=-1, etag=None)

List the people username follows.

Parameters:
  • username (str) – (required), login of the user
  • number (int) – (optional), number of users being followed by username to return. Default: -1, return all of them
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of User


github3.public_gists(number=-1, etag=None)

Iterate over all public gists.

New in version 1.0: This was split from github3.iter_gists before 1.0.

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

generator of Gist


github3.gists_by(username, number=-1, etag=None)

Iterate over gists created by the provided username.

Parameters:
  • username (str) – (required), if provided, get the gists for this user instead of the authenticated user.
  • number (int) – (optional), number of gists to return. Default: -1, return all of them
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Gist


github3.organizations_with(username, number=-1, etag=None)

List the organizations with username as a member.

Parameters:
  • username (str) – (required), login of the user
  • number (int) – (optional), number of orgs to return. Default: -1, return all of the issues
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of ShortOrganization


github3.repositories_by(username, type=None, sort=None, direction=None, number=-1, etag=None)

List public repositories for the specified username.

New in version 0.6.

Note

This replaces github3.iter_repos

Parameters:
  • username (str) – (required)
  • 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


github3.starred_by(username, number=-1, etag=None)

Iterate over repositories starred by username.

Parameters:
  • username (str) – (optional), name of user whose stars 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


github3.subscriptions_for(username, number=-1, etag=None)

Iterate over repositories subscribed to by username.

Parameters:
  • username (str) – 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


github3.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


github3.octocat(say=None)

Return an easter egg from the API.

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

github3.organization(name)

Return an Organization object for the login name.

Parameters:username (str) – (required), login name of the org
Returns:the organization
Return type:Organization

github3.pull_request(owner, repository, number)

Anonymously retrieve pull request :number on :owner/:repository.

Parameters:
  • owner (str) – (required), repository owner
  • repository (str) – (required), repository name
  • number (int) – (required), pull request number
Returns:

PullRequest


github3.rate_limit()

Return a dictionary with information from /rate_limit.

The dictionary has two keys: resources and rate. In resources you can access information about core or search.

Note: the rate key will be deprecated before version 3 of the GitHub API is finalized. Do not rely on that key. Instead, make your code future-proof by using core in resources, e.g.,

rates = g.rate_limit()
rates['resources']['core']  # => your normal ratelimit info
rates['resources']['search']  # => your search ratelimit info

New in version 0.8.

Returns:ratelimit mapping
Return type:dict

github3.repository(owner, repository)

Retrieve the desired repository.

Parameters:
  • owner (str) – (required)
  • repository (str) – (required)
Returns:

the repository

Return type:

Repository


github3.search_code(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)

Find code via the code search API.

Warning

You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated GitHub Session with login.

The query can contain any combination of the following supported qualifiers:

  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the file contents, the file path, or both.
  • language Searches code based on the language it’s written in.
  • fork Specifies that code from forked repositories should be searched. Repository forks will not be searchable unless the fork has more stars than the parent repository.
  • size Finds files that match a certain size (in bytes).
  • path Specifies the path that the resulting file must be at.
  • extension Matches files with a certain extension.
  • user or repo Limits searches to a specific user or repository.

For more information about these qualifiers, see: http://git.io/-DvAuA

Parameters:
  • query (str) – (required), a valid query as described above, e.g., addClass in:file language:js repo:jquery/jquery
  • sort (str) – (optional), how the results should be sorted; option(s): indexed; default: best match
  • order (str) – (optional), the direction of the sorted results, options: asc, desc; default: desc
  • per_page (int) – (optional)
  • text_match (bool) – (optional), if True, return matching search terms. See http://git.io/4ct1eQ for more information
  • number (int) – (optional), number of repositories to return. Default: -1, returns all available repositories
  • etag (str) – (optional), previous ETag header value
Returns:

generator of CodeSearchResult


github3.search_issues(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)

Find issues by state and keyword

Warning

You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated GitHub Session with login.

The query can contain any combination of the following supported qualifers:

  • type With this qualifier you can restrict the search to issues or pull request only.
  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the title, body, comments, or any combination of these.
  • author Finds issues created by a certain user.
  • assignee Finds issues that are assigned to a certain user.
  • mentions Finds issues that mention a certain user.
  • commenter Finds issues that a certain user commented on.
  • involves Finds issues that were either created by a certain user, assigned to that user, mention that user, or were commented on by that user.
  • state Filter issues based on whether they’re open or closed.
  • labels Filters issues based on their labels.
  • language Searches for issues within repositories that match a certain language.
  • created or updated Filters issues based on times of creation, or when they were last updated.
  • comments Filters issues based on the quantity of comments.
  • user or repo Limits searches to a specific user or repository.

For more information about these qualifiers, see: http://git.io/d1oELA

Parameters:
  • query (str) – (required), a valid query as described above, e.g., windows label:bug
  • sort (str) – (optional), how the results should be sorted; options: created, comments, updated; default: best match
  • order (str) – (optional), the direction of the sorted results, options: asc, desc; default: desc
  • per_page (int) – (optional)
  • text_match (bool) – (optional), if True, return matching search terms. See http://git.io/QLQuSQ for more information
  • number (int) – (optional), number of issues to return. Default: -1, returns all available issues
  • etag (str) – (optional), previous ETag header value
Returns:

generator of IssueSearchResult


github3.search_repositories(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)

Find repositories via various criteria.

Warning

You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated GitHub Session with login.

The query can contain any combination of the following supported qualifers:

  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the repository name, description, readme, or any combination of these.
  • size Finds repositories that match a certain size (in kilobytes).
  • forks Filters repositories based on the number of forks, and/or whether forked repositories should be included in the results at all.
  • created or pushed Filters repositories based on times of creation, or when they were last updated. Format: YYYY-MM-DD. Examples: created:<2011, pushed:<2013-02, pushed:>=2013-03-06
  • user or repo Limits searches to a specific user or repository.
  • language Searches repositories based on the language they’re written in.
  • stars Searches repositories based on the number of stars.

For more information about these qualifiers, see: http://git.io/4Z8AkA

Parameters:
  • query (str) – (required), a valid query as described above, e.g., tetris language:assembly
  • sort (str) – (optional), how the results should be sorted; options: stars, forks, updated; default: best match
  • order (str) – (optional), the direction of the sorted results, options: asc, desc; default: desc
  • per_page (int) – (optional)
  • text_match (bool) – (optional), if True, return matching search terms. See http://git.io/4ct1eQ for more information
  • number (int) – (optional), number of repositories to return. Default: -1, returns all available repositories
  • etag (str) – (optional), previous ETag header value
Returns:

generator of Repository


github3.search_users(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)

Find users via the Search API.

Warning

You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated GitHub Session with login.

The query can contain any combination of the following supported qualifers:

  • type With this qualifier you can restrict the search to just personal accounts or just organization accounts.
  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the username, public email, full name, or any combination of these.
  • repos Filters users based on the number of repositories they have.
  • location Filter users by the location indicated in their profile.
  • language Search for users that have repositories that match a certain language.
  • created Filter users based on when they joined.
  • followers Filter users based on the number of followers they have.

For more information about these qualifiers see: http://git.io/wjVYJw

Parameters:
  • query (str) – (required), a valid query as described above, e.g., tom repos:>42 followers:>1000
  • sort (str) – (optional), how the results should be sorted; options: followers, repositories, or joined; default: best match
  • order (str) – (optional), the direction of the sorted results, options: asc, desc; default: desc
  • per_page (int) – (optional)
  • text_match (bool) – (optional), if True, return matching search terms. See http://git.io/_V1zRwa for more information
  • number (int) – (optional), number of search results to return; Default: -1 returns all available
  • etag (str) – (optional), ETag header value of the last request.
Returns:

generator of UserSearchResult


github3.user(username)

Retrieve a User object for the specified user name.

Parameters:username (str) – name of the user
Returns:the user
Return type:User

github3.zen()

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

Returns:str

Enterprise Use

If you’re using github3.py to interact with an enterprise installation of GitHub, you must use the GitHubEnterprise object. Upon initialization, the only parameter you must supply is the URL of your enterprise installation, e.g.

from github3 import GitHubEnterprise

g = GitHubEnterprise('https://github.examplesintl.com')
stats = g.admin_stats('all')
assert 'issues' in stats, ('Key issues is not included in the admin'
                           'statistics')