GitHub Object

The GitHub objects is the point at which most usage of github3.py works.

GitHub.com Object

class github3.github.GitHub(username='', password='', token='', session=None, api_version='')

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.

activate_membership(organization)

Activate the membership to an organization.

Parameters

organization (Organization) – the organization or organization login for which to activate the membership

Returns

the activated membership

Return type

Membership

add_email_addresses(addresses=[])

Add the addresses to the authenticated user’s account.

Parameters

addresses (list) – (optional), email addresses to be added

Returns

list of email objects

Return type

[Email]

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

Return type

Event

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 an 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 organizations

Return type

ShortOrganization

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 an 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 repositories

Return type

ShortRepository

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 users

Return type

ShortUser

app(app_slug)

Retrieve information about a specific app using its “slug”.

New in version 1.2.0.

See also

Get a single GitHub App

API Documentation

Parameters

app_slug – The identifier for the specific slug, e.g., test-github3-py-apps.

Returns

The app if and only if it is public.

Return type

App

app_installation(installation_id)

Retrieve a specific App installation by its ID.

See also

Get a single installation

API Documentation

Parameters

installation_id (int) – The ID of the specific installation.

Returns

The installation.

Return type

Installation

app_installation_for_organization(organization)

Retrieve an App installation for a specific organization.

New in version 1.2.0.

See also

Find organization installation

API Documentation

Parameters

organization (str) – The name of the organization.

Returns

The installation

Return type

Installation

app_installation_for_repository(owner, repository)

Retrieve an App installation for a specific repository.

New in version 1.2.0.

See also

Find repository installation

API Documentation

Parameters

  • owner (str) – The name of the owner.

  • repostory (str) – The name of the repository.

Returns

The installation

Return type

Installation

app_installation_for_user(user)

Retrieve an App installation for a specific repository.

New in version 1.2.0.

See also

Find user installation

API Documentation

Parameters

user (str) – The name of the user.

Returns

The installation

Return type

Installation

app_installation_repos(number=-1, etag=None)

Retrieve repositories accessible by app installation.

New in version 3.2.1.

See also

List repositories accessible to the app installation

API Documentation

Returns

The repositories accessible to the app installation

Return type

ShortRepository

app_installations(number=-1)

Retrieve the list of installations for the authenticated app.

New in version 1.2.0.

See also

Find installations

API Documentation

Returns

The installations of the authenticated App.

Return type

Installation

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

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

authenticated_app()

Retrieve information about the current app.

New in version 1.2.0.

See also

Get the authenticated GitHub App

API Documentation

Returns

Metadata about the application

Return type

App

authorization(id_num)

Get information about authorization id.

Parameters

id_num (int) – (required), unique id of the authorization

Returns

Authorization

authorizations(number=-1, etag=None)

Iterate over authorizations for the authenticated user.

Note

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

Return type

Authorization

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

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

created authorization

Return type

Authorization

block(username: Union[ShortUser, User, AuthenticatedUser, Collaborator, Contributor, str]) → bool

Block a specific user from an organization.

New in version 2.1.0.

Parameters

username (str) – Name (or user-like instance) of the user to block.

Returns

True if successful, Fales otherwise

Return type

bool

blocked_users(number: int = -1, etag: Optional[str] = None) → Generator[ShortUser, None, None]

Iterate over the users blocked by this organization.

New in version 2.1.0.

Parameters

  • number (int) – (optional), number of users to iterate over. Default: -1 iterates over all values

  • etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of the members of this team

Return type

ShortUser

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

True if token is valid, False otherwise

Return type

bool

create_gist(description, files, public=True)

Create a new gist.

Changed in version 1.1.0: Per GitHub’s recent announcement authentication is now required for creating gists.

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

the created gist if successful, otherwise None

Return type

created gist

Return type

Gist

create_gpg_key(armored_public_key)

Create a new GPG key.

New in version 1.2.0.

Parameters

armored_public_key (str) – (required), your GPG key, generated in ASCII-armored format

Returns

the created GPG key if successful, otherwise None

Return type

GPGKey

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

Create an issue on the repository.

Note

body, assignee, assignees, 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

  • assignees – (optional), logins of the users to assign the issue to

  • milestone (int) – (optional), id number of the milestone to attribute this issue to (e.g. if m is a Milestone object, m.number is what you pass here.)

  • labels (list) – (optional), List of label names.

Returns

created issue

Return type

ShortIssue

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

created key

Return type

Key

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

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.

  • has_projects (bool) – (optional), If True, enable projects for this repository. API default: True

Returns

created repository

Return type

Repository

delete_email_addresses(addresses=[])

Delete the specified addresses the authenticated user’s account.

Parameters

addresses (list) – (optional), email addresses to be removed

Returns

True if successful, False otherwise

Return type

bool

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 emails

Return type

Email

emojis()

Retrieve 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/...',
    # ...
}

feeds()

List GitHub’s timeline resources in Atom format.

Returns

dictionary parsed to include URITemplates

Return type

dict

follow(username)

Make the authenticated user follow the provided username.

Parameters

username (str) – (required), user to follow

Returns

True if successful, False otherwise

Return type

bool

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

Return type

ShortUser

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 followers

Return type

ShortUser

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 followers

Return type

ShortUser

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

Return type

ShortUser

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

gist(id_num)

Retrieve the gist using the specified id number.

Parameters

id_num (int) – (required), unique id of the gist

Returns

the gist identified by id_num

Return type

Gist

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 short gists

Return type

:class:~github3.gists.ShortGist`

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 short gists owned by the specified user

Return type

ShortGist

gitignore_template(language)

Return the template for language.

Returns

the template string

Return type

str

gitignore_templates()

Return the list of available templates.

Returns

list of template names

Return type

[str]

gpg_key(id_num)

Retrieve the GPG key of the authenticated user specified by id_num.

New in version 1.2.0.

Returns

the GPG key specified by id_num

Return type

GPGKey

gpg_keys(number=-1, etag=None)

Iterate over the GPG keys of the authenticated user.

New in version 1.2.0.

Parameters

  • number (int) – (optional), number of GPG keys to return. Default: -1 returns all available GPG keys

  • etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of the GPG keys belonging to the authenticated user

Return type

GPGKey

is_blocking(username: Union[ShortUser, User, AuthenticatedUser, Collaborator, Contributor, str]) → bool

Check if this organization is blocking a specific user.

New in version 2.1.0.

Parameters

username (str) – Name (or user-like instance) of the user to unblock.

Returns

True if successful, Fales otherwise

Return type

bool

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

True if following, False otherwise

Return type

bool

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

True if starred, False otherwise

Return type

bool

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

the issue

Return type

Issue

issues(filter='', state='', labels='', sort='', direction='', 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 str) – (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

Return type

ShortIssue

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 str) – (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

Return type

ShortIssue

key(id_num)

Get the authenticated user’s key specified by id_num.

Parameters

id_num (int) – (required), unique id of the key

Returns

created key

Return type

Key

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

Return type

Key

license(name)

Retrieve the license specified by the name.

Parameters

name (string) – (required), name of license

Returns

the specified license

Return type

License

licenses(number=-1, etag=None)

Iterate over open source licenses.

Returns

generator of short license objects

Return type

ShortLicense

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

Log 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

login_as_app(private_key_pem, app_id, expire_in=600)

Login as a GitHub Application.

New in version 1.2.0.

See also

Authenticating as an App

GitHub’s documentation of authenticating as an application.

Parameters

  • private_key_pem (bytes) – The bytes of the private key for this GitHub Application.

  • app_id (int) – The integer identifier for this GitHub Application.

  • expire_in (int) – The length in seconds for this token to be valid for. Default: 600 seconds (10 minutes)

login_as_app_installation(private_key_pem, app_id, installation_id, expire_in=30)

Login using your GitHub App’s installation credentials.

New in version 1.2.0.

Changed in version 3.0.0: Added expire_in parameter.

See also

Authenticating as an Installation

GitHub’s documentation of authenticating as an installation.

Create a new installation token

API Documentation

Note

This method makes an API call to retrieve the token.

Warning

This method expires after 1 hour.

Parameters

  • private_key_pem (bytes) – The bytes of the private key for this GitHub Application.

  • app_id (int) – The integer identifier for this GitHub Application.

  • installation_id (int) – The integer identifier of your App’s installation.

  • expire_in (int) – (Optional) The number of seconds in the future that the underlying JWT expires. To prevent tokens from being valid for too long and creating a security risk, the library defaults to 30 seconds. In the event that clock drift is significant between your machine and GitHub’s servers, you can set this higher than 30. Default: 30

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

the HTML formatted markdown text

Return type

str

me()

Retrieve 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

AuthenticatedUser

membership_in(organization)

Retrieve the user’s membership in the specified organization.

Parameters

organization (Organization) – the organization or organization login to retrieve the authorized user’s membership in

Returns

the user’s membership

Return type

Membership

meta()

Retrieve a dictionary with arrays of addresses in CIDR format.

The addresses in CIDR format specify the addresses that the incoming service hooks will originate from.

New in version 0.5.

Returns

CIDR addresses

Return type

dict

new_session()

Generate a new session.

Returns

A brand new session

Return type

GitHubSession

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 threads

Return type

Thread

octocat(say=None)

Return 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

organization(username)

Return an Organization object for the login name.

Parameters

username (str) – (required), login name of the org

Returns

the organization

Return type

Organization

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

Iterate over the organization’s issues.

Note

This only works 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 str) – (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 issues

Return type

ShortIssue

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 memberships

Return type

Membership

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

Return type

ShortOrganization

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

Return type

ShortOrganization

project(number)

Return the Project with id number.

Parameters

number (int) – id of the project

Returns

the project

Return type

Project

project_card(number)

Return the ProjectCard with id number.

Parameters

number (int) – id of the project card

Returns

ProjectCard

project_column(number)

Return the ProjectColumn with id number.

Parameters

number (int) – id of the project column

Returns

ProjectColumn

public_gists(number=-1, etag=None, since=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

  • since (datetime or str) – (optional), filters out any gists updated before the given time. This can be a datetime or an ISO8601 formatted date string, e.g., 2012-05-20T23:10:27Z

Returns

generator of short gists

Return type

ShortGist

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

Create or 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

True if successful, False otherwise

Return type

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

PullRequest

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

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → GitHubCore

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

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 repositories

Return type

ShortRepository

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 repositories

Return type

ShortRepository

repository(owner, repository)

Retrieve the desired repository.

Parameters

  • owner (str) – (required)

  • repository (str) – (required)

Returns

the repository

Return type

Repository

repository_invitations(number=-1, etag=None)

Iterate over the repository invitations for the current user.

Parameters

  • number (int) – (optional), number of invitations to return. Default: -1 returns all available invitations

  • etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of repository invitation objects

Return type

Invitation

repository_with_id(number)

Retrieve the repository with the globally unique id.

Parameters

number (int) – id of the repository

Returns

the repository

Return type

Repository

revoke_authorization(access_token)

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

True if successful, False otherwise

Return type

bool

revoke_authorizations()

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

True if successful, False otherwise

Return type

bool

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 code search results

Return type

CodeSearchResult

search_commits(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)

Find commits via the commits search API.

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

  • author Matches commits authored by the given username. Example: author:defunkt.

  • committer Matches commits committed by the given username. Example: committer:defunkt.

  • author-name Matches commits authored by a user with the given name. Example: author-name:wanstrath.

  • committer-name Matches commits committed by a user with the given name. Example: committer-name:wanstrath.

  • author-email Matches commits authored by a user with the given email. Example: author-email:chris@github.com.

  • committer-email Matches commits committed by a user with the given email. Example: committer-email:chris@github.com.

  • author-date Matches commits authored within the specified date range. Example: author-date:<2016-01-01.

  • committer-date Matches commits committed within the specified date range. Example: committer-date:>2016-01-01.

  • merge Matches merge commits when set to to true, excludes them when set to false.

  • hash Matches commits with the specified hash. Example: hash:124a9a0ee1d8f1e15e833aff432fbb3b02632105.

  • parent Matches commits whose parent has the specified hash. Example: parent:124a9a0ee1d8f1e15e833aff432fbb3b02632105.

  • tree Matches commits with the specified tree hash. Example: tree:99ca967.

  • is Matches public repositories when set to public, private repositories when set to private.

  • user or org or repo Limits the search to a specific user, organization, or repository.

For more information about these qualifiers, see: https://git.io/vb7XQ

Parameters

  • query (str) – (required), a valid query as described above, e.g., css repo:octocat/Spoon-Knife

  • sort (str) – (optional), how the results should be sorted; options: author-date, committer-date; default: best match

  • order (str) – (optional), the direction of the sorted results, options: asc, desc; default: desc

  • per_page (int) – (optional)

  • number (int) – (optional), number of commits to return. Default: -1, returns all available commits

  • etag (str) – (optional), previous ETag header value

Returns

generator of commit search results

Return type

CommitSearchResult

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 issue search results

Return type

IssueSearchResult

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 search results

Return type

RepositorySearchResult

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 user search results

Return type

UserSearchResult

set_client_id(id, secret)

Allow the developer to set their OAuth application credentials.

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)

Allow the user to set their own user agent string.

Parameters

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

star(username, repo)

Star a repository.

Parameters

  • username (str) – (required), owner of the repo

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

Returns

True if successful, False otherwise

Return type

bool

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

Iterate over repositories starred by the authenticated user.

Changed in version 1.0.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 repositories

Return type

ShortRepository>

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 repositories

Return type

ShortRepository

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 repositories

Return type

ShortRepository

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 subscribed repositories

Return type

ShortRepository

unblock(username: Union[ShortUser, User, AuthenticatedUser, Collaborator, Contributor, str]) → bool

Unblock a specific user from an organization.

New in version 2.1.0.

Parameters

username (str) – Name (or user-like instance) of the user to unblock.

Returns

True if successful, Fales otherwise

Return type

bool

unfollow(username)

Make the authenticated user stop following username.

Parameters

username (str) – (required)

Returns

True if successful, False otherwise

Return type

bool

unstar(username, repo)

Unstar username/repo.

Parameters

  • username (str) – (required), owner of the repo

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

Returns

True if successful, False otherwise

Return type

bool

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

True if successful, False otherwise

Return type

bool

user(username)

Retrieve a User object for the specified user name.

Parameters

username (str) – name of the user

Returns

the user

Return type

User

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

List only the authenticated user’s issues.

Will not list organization’s issues. See organization_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 str) – (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

Return type

ShortIssue

user_teams(number=-1, etag=None)

Get 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 teams

Return type

ShortTeam

user_with_id(number)

Get the user’s information with id number.

Parameters

number (int) – the user’s id number

Returns

the user

Return type

User

zen()

Return a quote from the Zen of GitHub.

Yet another API Easter Egg

Returns

the zen of GitHub

Return type

str

Examples

There are some examples of how to get started with this object here.

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='', password='', token='', verify=True, session=None)

An interface to a specific GitHubEnterprise instance.

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)

Retrieve statistics about this GitHub Enterprise instance.

Parameters

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

Returns

the statistics

Return type

dict

create_user(login, email)

Create a new user.

Note

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

created user

Return type

ShortUser

GitHubSession Object

class github3.session.GitHubSession(default_connect_timeout=4, default_read_timeout=10)

Our slightly specialized Session object.

Normally this is created automatically by GitHub. To use alternate values for network timeouts, this class can be instantiated directly and passed to the GitHub object. For example:

gh = github.GitHub(session=session.GitHubSession(
    default_connect_timeout=T, default_read_timeout=N))
Parameters

  • default_connect_timeout (float) – the number of seconds to wait when establishing a connection to GitHub

  • default_read_timeout (float) – the number of seconds to wait for a response from GitHub