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(username=u'', password=u'', token=u'')

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.

class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
GitHub.add_email_addresses(addresses=[])

Add the email addresses in addresses to the authenticated user’s account.

Parameters:addresses (list) – (optional), email addresses to be added
Returns:list of Email
GitHub.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 Events

GitHub.all_organizations(number=-1, since=None, etag=None, per_page=None)

Iterate over every organization in the order they were created.

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

generator of Organization

GitHub.all_repositories(number=-1, since=None, etag=None, per_page=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
  • per_page (int) – (optional), number of repositories to list per request
Returns:

generator of Repository

GitHub.all_users(number=-1, etag=None, per_page=None, since=None)

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

Changed in version 1.0.0: Inserted the since parameter after the number parameter.

Parameters:
  • number (int) – (optional), number of users to return. Default: -1, returns all of them
  • since (int) – (optional), ID of the last user that you’ve seen.
  • etag (str) – (optional), ETag from a previous request to the same endpoint
  • per_page (int) – (optional), number of users to list per request
Returns:

generator of User

GitHub.as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())
Returns:this object’s attributes serialized to a dictionary
Return type:dict
GitHub.as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())
Returns:this object’s attributes as a JSON string
Return type:str
GitHub.authorization(id_num)

Get information about authorization id.

Parameters:id_num (int) – (required), unique id of the authorization
Returns:Authorization
GitHub.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

GitHub.authorize(username, password, scopes=None, note=u'', note_url=u'', client_id=u'', client_secret=u'')

Obtain an authorization token.

The retrieved token will allow future consumers to use the API without a username and password.

Parameters:
  • username (str) – (required)
  • password (str) – (required)
  • scopes (list) – (optional), 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

GitHub.check_authorization(access_token)

Check an authorization created by a registered application.

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

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

Warning

This method retrieves the repository first and then uses it to create an issue. If you’re making several issues, you should use repository and then use create_issue

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 (int) – (optional), id number of the milestone to attribute this issue to (e.g. m is a Milestone object, m.number is what you pass here.)
  • labels (list) – (optional), List of label names.
Returns:

Issue if successful

GitHub.create_key(title, key, read_only=False)

Create a new key for the authenticated user.

Parameters:
  • title (str) – (required), key title
  • key (str) – (required), actual key contents, accepts path as a string or file-like object
  • read_only (bool) – (optional), restrict key access to read-only, default to False
Returns:

Key

GitHub.create_repository(name, description=u'', homepage=u'', private=False, has_issues=True, has_wiki=True, auto_init=False, gitignore_template=u'')

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

GitHub.delete_email_addresses(addresses=[])

Delete the email addresses in addresses from the authenticated user’s account.

Parameters:addresses (list) – (optional), email addresses to be removed
Returns:bool
GitHub.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

GitHub.emojis()

Retrieves a dictionary of all of the emojis that GitHub supports.

Returns:dictionary where the key is what would be in between the colons and the value is the URL to the image, e.g.,
{
    '+1': 'https://github.global.ssl.fastly.net/images/...',
    # ...
}
GitHub.feeds()

List GitHub’s timeline resources in Atom format.

Returns:dictionary parsed to include URITemplates
GitHub.follow(username)

Make the authenticated user follow the provided username.

Parameters:username (str) – (required), user to follow
Returns:bool
GitHub.followed_by(username, number=-1, etag=None)

Iterate over users being followed by username.

New in version 1.0.0: This replaces iter_following(‘sigmavirus24’).

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

GitHub.followers(number=-1, etag=None)

Iterate over followers of the authenticated user.

New in version 1.0.0: This replaces iter_followers().

Parameters:
  • 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

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

Iterate over followers of username.

New in version 1.0.0: This replaces iter_followers(‘sigmavirus24’).

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

GitHub.following(number=-1, etag=None)

Iterate over users the authenticated user is following.

New in version 1.0.0: This replaces iter_following().

Parameters:
  • 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

GitHub.from_dict(json_dict)

Return an instance of this class formed from json_dict.

GitHub.from_json(json)

Return an instance of this class formed from json.

GitHub.gist(id_num)

Retrieve the gist using the specified id number.

Parameters:id_num (int) – (required), unique id of the gist
Returns:Gist
GitHub.gists(number=-1, etag=None)

Retrieve the authenticated user’s gists.

New in version 1.0.

Parameters:
  • 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

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

Iterate over the gists owned by a user.

New in version 1.0.

Parameters:
  • username (str) – login of the user who owns the gists
  • 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

GitHub.gitignore_template(language)

Return the template for language.

Returns:str
GitHub.gitignore_templates()

Return the list of available templates.

Returns:list of template names
GitHub.is_following(username)

Check if the authenticated user is following login.

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

Check if the authenticated user starred username/repo.

Parameters:
  • username (str) – (required), owner of repository
  • repo (str) – (required), name of repository
Returns:

bool

GitHub.issue(username, repository, number)

Fetch issue from owner/repository.

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

Issue

GitHub.issues(filter=u'', state=u'', labels=u'', sort=u'', direction=u'', since=None, number=-1, etag=None)

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

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

Parameters:
  • filter (str) – accepted values: (‘assigned’, ‘created’, ‘mentioned’, ‘subscribed’) api-default: ‘assigned’
  • state (str) – accepted values: (‘all’, ‘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 (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 Issue

GitHub.issues_on(username, 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.

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

Parameters:
  • username (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 Issues

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

GitHub.license(name)

Retrieve the license specified by the name.

Parameters:name (string) – (required), name of license
Returns:License
GitHub.licenses(number=-1, etag=None)

Iterate over open source licenses.

Returns:generator of License
GitHub.login(username=None, password=None, token=None, two_factor_callback=None)

Logs the user into GitHub for protected API calls.

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
GitHub.markdown(text, mode=u'', context=u'', 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 (or unicode on Python 2) – HTML formatted text

GitHub.me()

Retrieves the info for the authenticated user.

New in version 1.0: This was separated from the user method.

Returns:The representation of the authenticated user.
Return type:User
GitHub.membership_in(organization)

Retrieve the user’s membership in the specified organization.

GitHub.meta()

Returns a dictionary with arrays of addresses in CIDR format specifying theaddresses that the incoming service hooks will originate from.

New in version 0.5.

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

GitHub.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
Return type:str (or unicode on Python 3)
GitHub.organization(username)

Returns a Organization object for the login name

Parameters:username (str) – (required), login name of the org
Returns:Organization
GitHub.organization_issues(name, filter=u'', state=u'', labels=u'', sort=u'', direction=u'', since=None, number=-1, etag=None)

Iterate over the organization’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 (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 available issues
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Issue

GitHub.organization_memberships(state=None, number=-1, etag=None)

List organizations of which the user is a current or pending member.

Parameters:state (str) – (option), state of the membership, i.e., active, pending
Returns:iterator of Membership
GitHub.organizations(number=-1, etag=None)

Iterate over all organizations the authenticated user belongs to.

This will display both the private memberships and the publicized memberships.

Parameters:
  • 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

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

Iterate over organizations with username as a public member.

New in version 1.0.0: Replaces iter_orgs('sigmavirus24').

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

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

Retrieve all public gists and iterate over them.

New in version 1.0.

Parameters:
  • 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

GitHub.pubsubhubbub(mode, topic, callback, secret=u'')

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

GitHub.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:

PullRequest

GitHub.rate_limit()

Returns 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:dict
GitHub.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
GitHub.refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('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.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

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
GitHub.repositories(type=None, sort=None, direction=None, number=-1, etag=None)

List repositories for the authenticated user, filterable by type.

Changed in version 0.6: Removed the login parameter for correctness. Use repositories_by 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

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

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

GitHub.repository(owner, repository)

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

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

Repository

GitHub.repository_with_id(number)

Returns the Repository with id number.

Parameters:number (int) – id of the repository
Returns:Repository
GitHub.revoke_authorization(*args, **kwargs)

Revoke specified authorization for an OAuth application.

Revoke all authorization tokens created by your application. This will only work if you have already called set_client_id.

Parameters:access_token (str) – (required), the access_token to revoke
Returns:bool – True if successful, False otherwise
GitHub.revoke_authorizations(*args, **kwargs)

Revoke all authorizations for an OAuth application.

Revoke all authorization tokens created by your application. This will only work if you have already called set_client_id.

Parameters:client_id (str) – (required), the client_id of your application
Returns:bool – True if successful, False otherwise
GitHub.search_code(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)

Find code via the code search API.

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/iRmJxg 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

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

Find issues by state and keyword

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

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

Find repositories via various criteria.

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

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

Find users via the Search API.

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

GitHub.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
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”
GitHub.star(username, repo)

Star to username/repo

Parameters:
  • username (str) – (required), owner of the repo
  • repo (str) – (required), name of the repo
Returns:

bool

GitHub.starred(sort=None, direction=None, number=-1, etag=None)

Iterate over repositories starred by the authenticated user.

Changed in version 1.0: This was split from iter_starred and requires authentication.

Parameters:
  • 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

GitHub.starred_by(username, sort=None, direction=None, number=-1, etag=None)

Iterate over repositories starred by username.

New in version 1.0: This was split from iter_starred and requires the login parameter.

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

GitHub.subscriptions(number=-1, etag=None)

Iterate over repositories subscribed to by the authenticated user.

Parameters:
  • 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

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

GitHub.unfollow(username)

Make the authenticated user stop following username

Parameters:username (str) – (required)
Returns:bool
GitHub.unstar(username, repo)

Unstar username/repo.

Parameters:
  • username (str) – (required), owner of the repo
  • repo (str) – (required), name of the repo
Returns:

bool

GitHub.update_me(name=None, email=None, blog=None, company=None, location=None, hireable=False, bio=None)

Update the profile of the authenticated user.

Parameters:
Returns:

whether the operation was successful or not

Return type:

bool

GitHub.user(username)

Returns a User object for the specified user name.

Parameters:username (str) – name of the user
Returns:User
GitHub.user_issues(filter=u'', state=u'', labels=u'', sort=u'', direction=u'', since=None, per_page=None, number=-1, etag=None)

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

Changed in version 1.0: per_page parameter added before number

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

Parameters:
  • filter (str) – accepted values: (‘assigned’, ‘created’, ‘mentioned’, ‘subscribed’) api-default: ‘assigned’
  • state (str) – accepted values: (‘all’, ‘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 (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 Issue

GitHub.user_teams(number=-1, etag=None)

Gets the authenticated user’s teams across all of organizations.

List all of the teams across all of the organizations to which the authenticated user belongs. This method requires user or repo scope when authenticating via OAuth.

Returns:generator of Team objects
GitHub.user_with_id(number)

Get the user’s information with id number.

Parameters:number (int) – the user’s id number
Returns:User
GitHub.zen()

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

Returns:str (on Python 3, unicode on Python 2)

GitHubEnterprise Object

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

class github3.github.GitHubEnterprise(url, username=u'', password=u'', token=u'', verify=True)

For GitHub Enterprise users, this object will act as the public API to your instance. You must provide the URL to your instance upon initialization 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.

If you have a self signed SSL for your local github enterprise you can override the validation by passing verify=False.

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
create_user(login, email)

Create a new user. This is only available for administrators of the instance.

Parameters:
  • login (str) – (required), The user’s username.
  • email (str) – (required), The user’s email address.
Returns:

User, if successful

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