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:
- 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:
- 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:
- 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:
- 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 thenumber
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:
- 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_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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- authorization(id_num)
Get information about authorization
id
.- Parameters:
id_num (int) – (required), unique id of the authorization
- Returns:
- 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:
- 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:
- block(username: 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: str | None = None) Iterator[ShortUser]
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:
- 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:
- 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 usecreate_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 aMilestone
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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: 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:
- 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:27Znumber (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:27Znumber (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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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_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:27Znumber (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:
- 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:
- 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:
- project(number)
Return the Project with id
number
.- Parameters:
number (int) – id of the project
- Returns:
the project
- Return type:
- project_card(number)
Return the ProjectCard with id
number
.- Parameters:
number (int) – id of the project card
- Returns:
- project_column(number)
Return the ProjectColumn with id
number
.- Parameters:
number (int) – id of the project column
- Returns:
- 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:
- 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
andrate
. Inresources
you can access information aboutcore
orsearch
.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 usingcore
inresources
, 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:
- 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:
- repository(owner, repository)
Retrieve the desired repository.
- Parameters:
owner (str) – (required)
repository (str) – (required)
- Returns:
the repository
- Return type:
- 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:
- 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
orrepo
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 matchorder (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:
- 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 totrue
, excludes them when set tofalse
.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 topublic
, private repositories when set toprivate
.user
ororg
orrepo
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 matchorder (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
orupdated
Filters issues based on times of creation, or when they were last updated.comments
Filters issues based on the quantity of comments.user
orrepo
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 matchorder (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:
- 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
orpushed
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
orrepo
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 matchorder (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:
- 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
, orjoined
; default: best matchorder (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:
- 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:
- 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:
- 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:
- unblock(username: 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:
name (str) – e.g., ‘John Smith’, not login name
email (str) – e.g., ‘john.smith@example.com’
blog (str) – e.g., ‘http://www.example.com/jsmith/blog’
company (str) –
location (str) –
hireable (bool) – defaults to False
bio (str) – GitHub flavored markdown
- 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_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 beforenumber
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:27Znumber (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:
- 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:
- 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
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