GitHub Object

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

GitHub.com Object

classgithub3.github.GitHub(username='',password='',token='',session=None,api_version='')

Stores all the session information.

There are two ways to log into the GitHub API

fromgithub3importloging=login(user,password)g=login(token=token)g=login(user,token=token)

fromgithub3importGitHubg=GitHub(user,password)g=GitHub(token=token)g=GitHub(user,token=token)

This is simple backward compatibility since originally there was no way tocall 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 themembership
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: -1returns 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 aniteration)
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 aniteration)
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 thesince parameter after thenumber parameter.

Parameters:

number (int) – (optional), number of users to return. Default: -1, returns all ofthem
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 authorizationid.

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

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 withouta 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 atoken
client_secret (str) – (optional), 40 character OAuth client secret for which to createthe token

Returns:

created authorization

Return type:

Authorization

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 iteratesover 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 validitywithout hitting normal rate limits because of failed login attempts.If the token is valid, it will return True, otherwise it will returnFalse.

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:PerGitHub’s recent announcement authentication is now requiredfor creating gists.

Parameters:

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

Returns:

the created gist if successful, otherwiseNone

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, otherwiseNone
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,labelsare all optional.

Warning

This method retrieves the repository first and then uses it tocreate an issue. If you’re making several issues, you should userepository and thenusecreate_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. ifm 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 pathas 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), IfTrue, create a private repository. API default:False
has_issues (bool) – (optional), IfTrue, enable issues for this repository. APIdefault:True
has_wiki (bool) – (optional), IfTrue, enable the wiki for this repository. APIdefault: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), IfTrue, enable projects for this repository. APIdefault: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 thecolons 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 byusername.

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 allpeople 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 allfollowers
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 ofusername.

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 allfollowers
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 allpeople you follow
etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of users

Return type:

ShortUser

classmethodfrom_dict(json_dict,session): Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session): Return an instance of this class formed fromjson.

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 byid_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 allavailable 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 allavailable 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 sameendpoint

Returns:

generator of the GPG keys belonging to the authenticated user

Return type:

GPGKey

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 theauthenticated 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:

Thestate 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 willbe returned. This can be adatetime or an ISO8601 formatteddate 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:

Thestate 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 willbe returned. This can be adatetime or an ISO8601 formatteddate 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: -1returns 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-factorAuthentication code to GitHub when necessary

login_as_app(private_key_pem,app_id,expire_in=600)

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)

New in version 1.2.0.

Changed in version 3.0.0:Addedexpire_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 underlyingJWT expires. To prevent tokens from being valid for too long andcreating a security risk, the library defaults to 30 seconds. Inthe event that clock drift is significant between your machine andGitHub’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 therepository 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 theuser 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 authorizeduser’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 incomingservice 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 isparticipating
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 willbe returned. This can be adatetime or an ISO8601 formatteddate 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 publicizedmemberships.

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 sameendpoint

Returns:

generator of organizations

Return type:

ShortOrganization

organizations_with(username,number=-1,etag=None)

Iterate over organizations withusername as a public member.

New in version 1.0.0:Replacesiter_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 idnumber.

Parameters:: number (int) – id of the project
Returns:: the project
Return type:: Project

project_card(number)

Return the ProjectCard with idnumber.

Parameters:: number (int) – id of the project card
Returns:: ProjectCard

project_column(number)

Return the ProjectColumn with idnumber.

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: -1returns 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 thegiven time. This can be adatetime or anISO8601formatted 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 aSHA1 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: therate key will be deprecated before version 3 of theGitHub API is finalized. Do not rely on that key. Instead, make yourcode future-proof by usingcore inresources, e.g.,

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

New in version 0.8.

Returns:: ratelimit mapping
Return type:: dict

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:: conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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 bytype.

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

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

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 returnsall 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 willonly work if you have already calledset_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 willonly work if you have already calledset_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 supportedqualifiers:

in Qualifies which fields are searched. With this qualifier youcan restrict the search to just the file contents, the file path, orboth.
language Searches code based on the language it’s written in.
fork Specifies that code from forked repositories should besearched. Repository forks will not be searchable unless the forkhas 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 orrepository.

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

Parameters:

query (str) – (required), a valid query as described above, e.g.,addClassin:filelanguage:jsrepo: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 searchterms. Seehttp://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 supportedqualifiers:

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 givenname. Example:author-name:wanstrath.
committer-name Matches commits committed by a user with the givenname. Example:committer-name:wanstrath.
author-email Matches commits authored by a user with the givenemail. Example:author-email:chris@github.com.
committer-email Matches commits committed by a user with thegiven email. Example:committer-email:chris@github.com.
author-date Matches commits authored within the specified daterange. Example:author-date:<2016-01-01.
committer-date Matches commits committed within the specifieddate range. Example:committer-date:>2016-01-01.
merge Matches merge commits when set to totrue, excludesthem 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, privaterepositories 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.,cssrepo: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 supportedqualifers:

type With this qualifier you can restrict the search to issuesor pull request only.
in Qualifies which fields are searched. With this qualifier youcan restrict the search to just the title, body, comments, or anycombination 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 bythat 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 acertain 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 orrepository.

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

Parameters:

query (str) – (required), a valid query as described above, e.g.,windowslabel: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.Seehttp://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 supportedqualifers:

in Qualifies which fields are searched. With this qualifier youcan restrict the search to just the repository name, description,readme, or any combination of these.
size Finds repositories that match a certain size (inkilobytes).
forks Filters repositories based on the number of forks, and/orwhether forked repositories should be included in the results atall.
created orpushed Filters repositories based on times ofcreation, 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 orrepository.
language Searches repositories based on the language they’rewritten 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.,tetrislanguage: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 searchterms. Seehttp://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 supportedqualifers:

type With this qualifier you can restrict the search to justpersonal accounts or just organization accounts.
in Qualifies which fields are searched. With this qualifier youcan restrict the search to just the username, public email, fullname, or any combination of these.
repos Filters users based on the number of repositories theyhave.
location Filter users by the location indicated in theirprofile.
language Search for users that have repositories that match acertain language.
created Filter users based on when they joined.
followers Filter users based on the number of followers theyhave.

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

Parameters:

query (str) – (required), a valid query as described above, e.g.,tomrepos:>42followers:>1000
sort (str) – (optional), how the results should be sorted;options:followers,repositories, orjoined; 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 searchterms. Seehttp://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 fromiter_starred and requires authentication.

Parameters:

sort (str) – (optional), either ‘created’ (when the star wascreated) 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 byusername.

New in version 1.0:This was split fromiter_starred and requires the loginparameter.

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

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

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. Seeorganization_issues().

Changed in version 1.0:per_page parameter added beforenumber

Changed in version 0.9.0:

Thestate 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 willbe returned. This can be adatetime or an ISO8601 formatteddate 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 sameendpoint

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 theauthenticated user belongs. This method requires user or repo scopewhen authenticating via OAuth.

Returns:: generator of teams
Return type:: ShortTeam

user_with_id(number)

Get the user’s information with idnumber.

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

GitHubEnterprise Object

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

classgithub3.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 toyour instance. You must provide the URL to your instance uponinitialization and can provide the rest of the login details just like intheGitHub object.

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

If you have a self signed SSL for your local github enterprise you canoverride the validation by passingverify=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

classgithub3.session.GitHubSession(default_connect_timeout=4,default_read_timeout=10)

Our slightly specialized Session object.

Normally this is created automatically byGitHub. To use alternate values fornetwork timeouts, this class can be instantiated directly andpassed 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 toGitHub
default_read_timeout (float) – the number of seconds to wait for a response from GitHub

Movatterモバイル変換

GitHub Object

GitHub.com Object

Examples

GitHubEnterprise Object

GitHubSession Object