API¶
This part of the documentation covers the API. This is intended to be a
beautifully written module which allows the user (developer) to interact with
github3.py
elegantly and easily.
Module Contents¶
To interact with the GitHub API you can either authenticate to access protected functionality or you can interact with it anonymously. Authenticating provides more functionality to the the user (developer).
To authenticate, you simply use github3.login()
.
-
github3.
login
(username=None, password=None, token=None, two_factor_callback=None)¶ Construct and return an authenticated GitHub session.
Note
To allow you to specify either a username and password combination or a token, none of the parameters are required. If you provide none of them, you will receive
None
.Parameters: - username (str) – login name
- password (str) – password for the login
- token (str) – OAuth token
- two_factor_callback (func) – (optional), function you implement to provide the Two Factor Authentication code to GitHub when necessary
Returns:
With the GitHub
object that is returned you have access
to more functionality. See that object’s documentation for more information.
To use the API anonymously, you can create a new
GitHub
object, e.g.,
from github3 import GitHub
gh = GitHub()
Or you can simply use the following functions
Obtain an authorization token for the GitHub API.
Parameters: - username (str) – (required)
- password (str) – (required)
- scopes (list) – (required), areas you want this token to apply to, i.e., ‘gist’, ‘user’
- note (str) – (optional), note about the authorization
- note_url (str) – (optional), url for the application
- client_id (str) – (optional), 20 character OAuth client key for which to create a token
- client_secret (str) – (optional), 40 character OAuth client secret for which to create the token
- two_factor_callback (func) – (optional), function to call when a Two-Factor Authentication code needs to be provided by the user.
- github (GitHub) – (optional), GitHub (or GitHubEnterprise) object for login.
Returns: Authorization
-
github3.
create_gist
(description, files)¶ Create an anonymous public gist.
Parameters: - description (str) – (required), short description of the gist
- files (dict) – (required), file names with associated dictionaries for content, e.g. {‘spam.txt’: {‘content’: ‘File contents …’}}
Returns: Gist
-
github3.
gist
(id_num)¶ Retrieve the gist identified by
id_num
.Parameters: id_num (int) – (required), unique id of the gist Returns: Gist
-
github3.
gitignore_template
(language)¶ Return the template for language.
Returns: str
-
github3.
gitignore_templates
()¶ Return the list of available templates.
Returns: list of template names
-
github3.
issue
(owner, repository, number)¶ Anonymously gets issue :number on :owner/:repository.
Parameters: - owner (str) – (required), repository owner
- repository (str) – (required), repository name
- number (int) – (required), issue number
Returns: Issue
-
github3.
issues_on
(owner, repository, milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None)¶ Iterate over issues on owner/repository.
-
Changed in version 0.9.0:
The
state
parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.
Parameters: - owner (str) – login of the owner of the repository
- repository (str) – name of the repository
- milestone (int) – None, ‘*’, or ID of milestone
- state (str) – accepted values: (‘all’, ‘open’, ‘closed’) api-default: ‘open’
- assignee (str) – ‘*’ or login of the user
- mentioned (str) – login of the user
- labels (str) – comma-separated list of label names, e.g., ‘bug,ui,@high’
- sort (str) – accepted values: (‘created’, ‘updated’, ‘comments’) api-default: created
- direction (str) – accepted values: (‘asc’, ‘desc’) api-default: desc
- since (datetime or string) – (optional), Only issues after this date will be returned. This can be a datetime or an ISO8601 formatted date string, e.g., 2012-05-20T23:10:27Z
- number (int) – (optional), number of issues to return. Default: -1 returns all issues
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
ShortIssue
s
-
github3.
all_repositories
(number=-1, etag=None)¶ Iterate over every repository in the order they were created.
Parameters: - number (int) – (optional), number of repositories to return. Default: -1, returns all of them
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Repository
-
github3.
all_users
(number=-1, etag=None)¶ Iterate over every user in the order they signed up for GitHub.
Parameters: - number (int) – (optional), number of users to return. Default: -1, returns all of them
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
User
-
github3.
all_events
(number=-1, etag=None)¶ Iterate over public events.
Parameters: - number (int) – (optional), number of events to return. Default: -1 returns all available events
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Event
-
github3.
followers_of
(username, number=-1, etag=None)¶ List the followers of
username
.Parameters: - username (str) – (required), login of the person to list the followers of
- number (int) – (optional), number of followers to return, Default: -1, return all of them
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
User
-
github3.
followed_by
(username, number=-1, etag=None)¶ List the people
username
follows.Parameters: - username (str) – (required), login of the user
- number (int) – (optional), number of users being followed by username to return. Default: -1, return all of them
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
User
-
github3.
public_gists
(number=-1, etag=None)¶ Iterate over all public gists.
New in version 1.0: This was split from
github3.iter_gists
before 1.0.Parameters: - number (int) – (optional), number of gists to return. Default: -1, return all of them
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Gist
-
github3.
gists_by
(username, number=-1, etag=None)¶ Iterate over gists created by the provided username.
Parameters: - username (str) – (required), if provided, get the gists for this user instead of the authenticated user.
- number (int) – (optional), number of gists to return. Default: -1, return all of them
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Gist
-
github3.
organizations_with
(username, number=-1, etag=None)¶ List the organizations with
username
as a member.Parameters: - username (str) – (required), login of the user
- number (int) – (optional), number of orgs to return. Default: -1, return all of the issues
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
ShortOrganization
-
github3.
repositories_by
(username, type=None, sort=None, direction=None, number=-1, etag=None)¶ List public repositories for the specified
username
.New in version 0.6.
Note
This replaces github3.iter_repos
Parameters: - username (str) – (required)
- type (str) – (optional), accepted values: (‘all’, ‘owner’, ‘member’) API default: ‘all’
- sort (str) – (optional), accepted values: (‘created’, ‘updated’, ‘pushed’, ‘full_name’) API default: ‘created’
- direction (str) – (optional), accepted values: (‘asc’, ‘desc’), API default: ‘asc’ when using ‘full_name’, ‘desc’ otherwise
- number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Repository
objects
-
github3.
starred_by
(username, number=-1, etag=None)¶ Iterate over repositories starred by
username
.Parameters: - username (str) – (optional), name of user whose stars you want to see
- number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Repository
-
github3.
subscriptions_for
(username, number=-1, etag=None)¶ Iterate over repositories subscribed to by
username
.Parameters: - username (str) – name of user whose subscriptions you want to see
- number (int) – (optional), number of repositories to return. Default: -1 returns all repositories
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
Repository
-
github3.
markdown
(text, mode='', context='', raw=False)¶ Render an arbitrary markdown document.
Parameters: - text (str) – (required), the text of the document to render
- mode (str) – (optional), ‘markdown’ or ‘gfm’
- context (str) – (optional), only important when using mode ‘gfm’, this is the repository to use as the context for the rendering
- raw (bool) – (optional), renders a document like a README.md, no gfm, no context
Returns: str – HTML formatted text
-
github3.
octocat
(say=None)¶ Return an easter egg from the API.
Params str say: (optional), pass in what you’d like Octocat to say Returns: ascii art of Octocat
-
github3.
organization
(name)¶ Return an Organization object for the login name.
Parameters: username (str) – (required), login name of the org Returns: the organization Return type: Organization
-
github3.
pull_request
(owner, repository, number)¶ Anonymously retrieve pull request :number on :owner/:repository.
Parameters: - owner (str) – (required), repository owner
- repository (str) – (required), repository name
- number (int) – (required), pull request number
Returns:
-
github3.
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
-
github3.
repository
(owner, repository)¶ Retrieve the desired repository.
Parameters: - owner (str) – (required)
- repository (str) – (required)
Returns: the repository
Return type:
-
github3.
search_code
(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)¶ Find code via the code search API.
Warning
You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated
GitHub
Session withlogin
.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 match - order (str) – (optional), the direction of the sorted results,
options:
asc
,desc
; default:desc
- per_page (int) – (optional)
- text_match (bool) – (optional), if True, return matching search terms. See http://git.io/4ct1eQ for more information
- number (int) – (optional), number of repositories to return. Default: -1, returns all available repositories
- etag (str) – (optional), previous ETag header value
Returns: generator of
CodeSearchResult
-
github3.
search_issues
(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)¶ Find issues by state and keyword
Warning
You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated
GitHub
Session withlogin
.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 match - order (str) – (optional), the direction of the sorted results,
options:
asc
,desc
; default:desc
- per_page (int) – (optional)
- text_match (bool) – (optional), if True, return matching search terms. See http://git.io/QLQuSQ for more information
- number (int) – (optional), number of issues to return. Default: -1, returns all available issues
- etag (str) – (optional), previous ETag header value
Returns: generator of
IssueSearchResult
-
github3.
search_repositories
(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)¶ Find repositories via various criteria.
Warning
You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated
GitHub
Session withlogin
.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 match - order (str) – (optional), the direction of the sorted results,
options:
asc
,desc
; default:desc
- per_page (int) – (optional)
- text_match (bool) – (optional), if True, return matching search terms. See http://git.io/4ct1eQ for more information
- number (int) – (optional), number of repositories to return. Default: -1, returns all available repositories
- etag (str) – (optional), previous ETag header value
Returns: generator of
Repository
-
github3.
search_users
(query, sort=None, order=None, per_page=None, text_match=False, number=-1, etag=None)¶ Find users via the Search API.
Warning
You will only be able to make 5 calls with this or other search functions. To raise the rate-limit on this set of endpoints, create an authenticated
GitHub
Session withlogin
.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 match - order (str) – (optional), the direction of the sorted results,
options:
asc
,desc
; default:desc
- per_page (int) – (optional)
- text_match (bool) – (optional), if True, return matching search terms. See http://git.io/_V1zRwa for more information
- number (int) – (optional), number of search results to return; Default: -1 returns all available
- etag (str) – (optional), ETag header value of the last request.
Returns: generator of
UserSearchResult
-
github3.
user
(username)¶ Retrieve a User object for the specified user name.
Parameters: username (str) – name of the user Returns: the user Return type: User
-
github3.
zen
()¶ Return a quote from the Zen of GitHub. Yet another API Easter Egg.
Returns: str
Enterprise Use¶
If you’re using github3.py to interact with an enterprise installation of
GitHub, you must use the
GitHubEnterprise
object. Upon
initialization, the only parameter you must supply is the URL of your
enterprise installation, e.g.
from github3 import GitHubEnterprise
g = GitHubEnterprise('https://github.examplesintl.com')
stats = g.admin_stats('all')
assert 'issues' in stats, ('Key issues is not included in the admin'
'statistics')