Repository API Objects
This section of the documentation covers the representations of various objects related to the Repositories API.
Repository Objects
- class github3.repos.repo.Repository(json, session: GitHubSession)
This organizes the full representation of a single Repository.
The full representation of a Repository is not returned in collections but instead in individual requests, e.g.,
repository()
.This object has all the same attributes as
ShortRepository
as well as:- allow_merge_commit
Note
This attribute is not guaranteed to be present.
Whether the repository allows creating a merge commit when merging when a pull request.
- allow_rebase_merge
Note
This attribute is not guaranteed to be present.
Whether the repository allows rebasing when merging a pull request.
- allow_squash_merge
Note
This attribute is not guaranteed to be present.
Whether the repository allows squashing commits when merging a pull request.
- archived
A boolean attribute that describes whether the current repository has been archived or not.
- clone_url
This is the URL that can be used to clone the repository via HTTPS, e.g.,
https://github.com/sigmavirus24/github3.py.git
.
- created_at
A parsed
datetime
object representing the date the repository was created.
- default_branch
This is the default branch of the repository as configured by its administrator(s).
- forks_count
This is the number of forks of the repository.
- git_url
This is the URL that can be used to clone the repository via the Git protocol, e.g.,
git://github.com/sigmavirus24/github3.py
.
- has_downloads
This is a boolean attribute that conveys whether or not the repository has downloads.
- has_issues
This is a boolean attribute that conveys whether or not the repository has issues.
- has_pages
This is a boolean attribute that conveys whether or not the repository has pages.
- has_wiki
This is a boolean attribute that conveys whether or not the repository has a wiki.
- homepage
This is the administrator set homepage URL for the project. This may not be provided.
- language
This is the language GitHub has detected for the repository.
- original_license
Note
When used with a Github Enterprise instance <= 2.12.7, this attribute will not be returned. To handle these situations sensitively, the attribute will be set to
None
. Repositories may still have a license associated with them in these cases.This is the
ShortLicense
returned as part of the repository. To retrieve the most recent license, see thelicense()
method.
- mirror_url
The URL that GitHub is mirroring the repository from.
- network_count
The size of the repository’s “network”.
- open_issues_count
The number of issues currently open on the repository.
- parent
A representation of the parent repository as
ShortRepository
. If this Repository has no parent then this will beNone
.
- pushed_at
A parsed
datetime
object representing the date a push was last made to the repository.
- size
The size of the repository.
- source
A representation of the source repository as
ShortRepository
. If this Repository has no source then this will beNone
.
- ssh_url
This is the URL that can be used to clone the repository via the SSH protocol, e.g.,
ssh@github.com:sigmavirus24/github3.py.git
.
- stargazers_count
The number of people who have starred this repository.
- subscribers_count
The number of people watching (or who have subscribed to notifications about) this repository.
- svn_url
This is the URL that can be used to clone the repository via SVN, e.g.,
ssh@github.com:sigmavirus24/github3.py.git
.
- updated_at
A parsed
datetime
object representing the date a the repository was last updated by its administrator(s).
- watchers_count
The number of people watching this repository.
See also: http://developer.github.com/v3/repos/
- add_collaborator(username, permission=None)
Add
username
as a collaborator to a repository.- Parameters:
username (str or
User
) – (required), username of the userpermission (str) – (optional), permission to grant the collaborator, valid on organization repositories only. Can be ‘pull’, ‘triage’, ‘push’, ‘maintain’, ‘admin’ or an organization-defined custom role name.
- Returns:
True if successful, False otherwise
- Return type:
- archive(format, path='', ref='master')
Get the tarball or zipball archive for this repo at ref.
See: http://developer.github.com/v3/repos/contents/#get-archive-link
- Parameters:
format (str) – (required), accepted values: (‘tarball’, ‘zipball’)
path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. it can take a file-like object as well
ref (str) – (optional)
- Returns:
True if successful, False otherwise
- Return type:
bool
- 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
- asset(id)
Return a single asset.
- Parameters:
id (int) – (required), id of the asset
- Returns:
the asset
- Return type:
- assignees(number=-1, etag=None)
Iterate over all assignees to which an issue may be assigned.
- Parameters:
number (int) – (optional), number of assignees to return. Default: -1 returns all available assignees
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of users
- Return type:
- auto_trigger_checks(app_id, enabled=True)
Change preferences for automatic creation of check suites.
New in version 1.3.0.
Enable/disable the automatic flow when creating check suites. By default, the check suite is automatically created each time code is pushed. When the automatic creation is disable they can be created manually.
- Parameters:
app_id (int) – (required), the id of the GitHub App
enabled (bool) – (optional), enable automatic creation of check suites Default: True
- Returns:
the check suite settings for this repository
- Return type:
dict
- blob(sha)
Get the blob indicated by
sha
.- Parameters:
sha (str) – (required), sha of the blob
- Returns:
the git blob
- Return type:
- branch(name)
Get the branch
name
of this repository.- Parameters:
name (str) – (required), branch name
- Returns:
the branch
- Return type:
- branches(number=-1, protected=False, etag=None)
Iterate over the branches in this repository.
- Parameters:
number (int) – (optional), number of branches to return. Default: -1 returns all branches
protected (bool) – (optional), True lists only protected branches. Default: False
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of branches
- Return type:
- check_run(id)
Return a single check run.
New in version 1.3.0.
- Parameters:
id (int) – (required), id of the check run
- Returns:
the check run
- Return type:
CheckRun
- check_suite(id)
Return a single check suite.
New in version 1.3.0.
- Parameters:
id (int) – (required), id of the check suite
- Returns:
the check suite
- Return type:
CheckSuite
- clones(per='day')
Get the total number of repository clones and breakdown per day or week for the last 14 days.
New in version 1.4.0.
See also: https://developer.github.com/v3/repos/traffic/
- Parameters:
per (str) – (optional), (‘day’, ‘week’), clones reporting period. Default ‘day’ will return clones per day for the last 14 days.
- Returns:
clones data
- Return type:
ClonesStats
- Raises:
ValueError if per is not a valid choice
- code_frequency(number=-1, etag=None)
Iterate over the code frequency per week.
New in version 0.7.
Returns a weekly aggregate of the number of additions and deletions pushed to this repository.
Note
All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new
last_status
attribute. If it is a 202 you should wait before re-requesting.- Parameters:
number (int) – (optional), number of weeks to return. Default: -1 returns all weeks
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of lists
[seconds_from_epoch, additions, deletions]
- Return type:
list
- collaborators(affiliation='all', number=-1, etag=None)
Iterate over the collaborators of this repository.
- Parameters:
affiliation (str) – (optional), affiliation of the collaborator to the repository. Default: “all” returns contributors with all affiliations
number (int) – (optional), number of collaborators to return. Default: -1 returns all comments
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of collaborators
- Return type:
- comments(number=-1, etag=None)
Iterate over comments on all commits in the repository.
- Parameters:
number (int) – (optional), number of comments to return. Default: -1 returns all comments
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of comments on commits
- Return type:
- commit(sha)
Get a single (repo) commit.
See
git_commit()
for the Git Data Commit.- Parameters:
sha (str) – (required), sha of the commit
- Returns:
the commit
- Return type:
- commit_activity(number=-1, etag=None)
Iterate over last year of commit activity by week.
New in version 0.7.
See: http://developer.github.com/v3/repos/statistics/
Note
All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new
last_status
attribute. If it is a 202 you should wait before re-requesting.- Parameters:
number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of dictionaries
- Return type:
dict
- commit_comment(comment_id)
Get a single commit comment.
- Parameters:
comment_id (int) – (required), id of the comment used by GitHub
- Returns:
the comment on the commit
- Return type:
- commits(sha=None, path=None, author=None, number=-1, etag=None, since=None, until=None, per_page=None)
Iterate over commits in this repository.
- Parameters:
sha (str) – (optional), sha or branch to start listing commits from
path (str) – (optional), commits containing this path will be listed
author (str) – (optional), GitHub login, real name, or email to filter commits by (using commit author)
number (int) – (optional), number of commits to return. Default: -1 returns all commits
etag (str) – (optional), ETag from a previous request to the same endpoint
since (
datetime
or str) – (optional), Only commits after this date will be returned. This can be adatetime
or anISO8601
formatted date string.until (
datetime
or str) – (optional), Only commits before this date will be returned. This can be adatetime
or anISO8601
formatted date string.per_page (int) – (optional), commits listing page size
- Returns:
generator of commits
- Return type:
- compare_commits(base, head)
Compare two commits.
- Parameters:
base (str) – (required), base for the comparison
head (str) – (required), compare this against base
- Returns:
the comparison of the commits
- Return type:
- contributor_statistics(number=-1, etag=None)
Iterate over the contributors list.
New in version 0.7.
See also: http://developer.github.com/v3/repos/statistics/
Note
All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new
last_status
attribute. If it is a 202 you should wait before re-requesting.- Parameters:
number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of contributor statistics for each contributor
- Return type:
- contributors(anon=False, number=-1, etag=None)
Iterate over the contributors to this repository.
- Parameters:
anon (bool) – (optional), True lists anonymous contributors as well
number (int) – (optional), number of contributors to return. Default: -1 returns all contributors
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of contributor users
- Return type:
- create_blob(content, encoding)
Create a blob with
content
.- Parameters:
content (str) – (required), content of the blob
encoding (str) – (required), (‘base64’, ‘utf-8’)
- Returns:
string of the SHA returned
- Returns:
str
- create_branch_ref(name, sha=None)
Create a branch git reference.
This is a shortcut for calling
github3.repos.repo.Repository.create_ref()
.- Parameters:
branch (str) – (required), the branch to create
sha (str) – the commit to base the branch from
- Returns:
a reference object representing the branch
- Return type:
- create_check_run(name, head_sha, details_url=None, external_id=None, started_at=None, status=None, conclusion=None, completed_at=None, output=None, actions=None)
Create a check run object on a commit
New in version 1.3.0.
- Parameters:
name (str) – (required), The name of the check
head_sha (str) – (required), The SHA of the commit
details_url (str) – (optional), The URL of the integrator’s site that has the full details of the check
external_id (str) – (optional), A reference for the run on the integrator’s system
started_at (str) – (optional), ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ
status (str) – (optional), (‘queued’, ‘in_progress’, ‘completed’)
conclusion (str) – (optional), Required if you provide ‘completed_at’, or a ‘status’ of ‘completed’. The final conclusion of the check. (‘success’, ‘failure’, ‘neutral’, ‘cancelled’, ‘timed_out’, ‘action_required’)
completed_at (str) – (optional), Required if you provide ‘conclusion’. ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ
output (dict) – (optional), key-value pairs representing the output. Format:
{'title': 'string', 'summary': 'text, can be markdown', 'text': 'text, can be markdown', 'annotations': [{}], 'images': [{}]}
actions (list) – (optional), list of action objects. Format is:
[{'label': 'text', 'description', 'text', 'identifier', 'text'}, ...]
- Returns:
the created check run
- Return type:
CheckRun
- create_check_suite(head_sha)
Create a check suite object on a commit
New in version 1.3.0.
- Parameters:
head_sha (str) – The sha of the head commit.
- Returns:
the created check suite
- Return type:
CheckSuite
- create_comment(body, sha, path=None, position=None, line=1)
Create a comment on a commit.
- Parameters:
body (str) – (required), body of the message
sha (str) – (required), commit id
path (str) – (optional), relative path of the file to comment on
position (str) – (optional), line index in the diff to comment on
line (int) – (optional), line number of the file to comment on, default: 1
- Returns:
the created comment
- Return type:
- create_commit(message, tree, parents, author=None, committer=None)
Create a commit on this repository.
- Parameters:
message (str) – (required), commit message
tree (str) – (required), SHA of the tree object this commit points to
parents (list) – (required), SHAs of the commits that were parents of this commit. If empty, the commit will be written as the root commit. Even if there is only one parent, this should be an array.
author (dict) – (optional), if omitted, GitHub will use the authenticated user’s credentials and the current time. Format: {‘name’: ‘Committer Name’, ‘email’: ‘name@example.com’, ‘date’: ‘YYYY-MM-DDTHH:MM:SS+HH:00’}
committer (dict) – (optional), if ommitted, GitHub will use the author parameters. Should be the same format as the author parameter.
- Returns:
the created commit
- Return type:
- create_deployment(ref, required_contexts=None, payload='', auto_merge=False, description='', environment=None)
Create a deployment.
- Parameters:
ref (str) – (required), The ref to deploy. This can be a branch, tag, or sha.
required_contexts (list) – Optional array of status contexts verified against commit status checks. To bypass checking entirely pass an empty array. Default: []
payload (str) – Optional JSON payload with extra information about the deployment. Default: “”
auto_merge (bool) – Optional parameter to merge the default branch into the requested deployment branch if necessary. Default: False
description (str) – Optional short description. Default: “”
environment (str) – Optional name for the target deployment environment (e.g., production, staging, qa). Default: “production”
- Returns:
the created deployment
- Return type:
- create_file(path, message, content, branch=None, committer=None, author=None)
Create a file in this repository.
See also: http://developer.github.com/v3/repos/contents/#create-a-file
- Parameters:
path (str) – (required), path of the file in the repository
message (str) – (required), commit message
content (bytes) – (required), the actual data in the file
branch (str) – (optional), branch to create the commit on. Defaults to the default branch of the repository
committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email.
author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
- Returns:
dictionary of contents and commit for created file
- Return type:
- create_fork(organization=None)
Create a fork of this repository.
- Parameters:
organization (str) – (required), login for organization to create the fork under
- Returns:
the fork of this repository
- Return type:
- create_hook(name, config, events=['push'], active=True)
Create a hook on this repository.
- Parameters:
name (str) – (required), name of the hook
config (dict) – (required), key-value pairs which act as settings for this hook
events (list) – (optional), events the hook is triggered for
active (bool) – (optional), whether the hook is actually triggered
- Returns:
the created hook
- Return type:
- create_issue(title, body=None, assignee=None, milestone=None, labels=None, assignees=None)
Create an issue on this repository.
- Parameters:
title (str) – (required), title of the issue
body (str) – (optional), body of the issue
assignee (str) – (optional), login of the user to assign the issue to
milestone (int) – (optional), id number of the milestone to attribute this issue to (e.g.
m
is aMilestone
object,m.number
is what you pass here.)labels ([str]) – (optional), labels to apply to this issue
assignees ([str]) – (optional), login of the users to assign the issue to
- Returns:
the created issue
- Return type:
- create_key(title, key, read_only=False)
Create a deploy key.
- Parameters:
title (str) – (required), title of key
key (str) – (required), key text
read_only (bool) – (optional), restrict key access to read-only, default is False
- Returns:
the created key
- Return type:
- create_label(name, color, description=None)
Create a label for this repository.
- Parameters:
name (str) – (required), name to give to the label
color (str) – (required), value of the color to assign to the label, e.g., ‘#fafafa’ or ‘fafafa’ (the latter is what is sent)
description (str) – (optional), description to give to the label
- Returns:
the created label
- Return type:
- create_milestone(title, state=None, description=None, due_on=None)
Create a milestone for this repository.
- Parameters:
title (str) – (required), title of the milestone
state (str) – (optional), state of the milestone, accepted values: (‘open’, ‘closed’), default: ‘open’
description (str) – (optional), description of the milestone
due_on (str) – (optional), ISO 8601 formatted due date
- Returns:
the created milestone
- Return type:
- create_project(name, body=None)
Create a project for this repository.
- Parameters:
name (str) – (required), name of the project
body (str) – (optional), body of the project
- Returns:
the created project
- Return type:
- create_pull(title, base, head, body=None, maintainer_can_modify=None)
Create a pull request of
head
ontobase
branch in this repo.- Parameters:
title (str) – (required)
base (str) – (required), e.g., ‘master’
head (str) – (required), e.g., ‘username:branch’
body (str) – (optional), markdown formatted description
maintainer_can_modify (bool) – (optional), Indicates whether a maintainer is allowed to modify the pull request or not.
- Returns:
the created pull request
- Return type:
- create_pull_from_issue(issue, base, head)
Create a pull request from issue #``issue``.
- Parameters:
issue (int) – (required), issue number
base (str) – (required), e.g., ‘master’
head (str) – (required), e.g., ‘username:branch’
- Returns:
the created pull request
- Return type:
- create_ref(ref, sha)
Create a reference in this repository.
- Parameters:
ref (str) – (required), fully qualified name of the reference, e.g.
refs/heads/master
. If it doesn’t start withrefs
and contain at least two slashes, GitHub’s API will reject it.sha (str) – (required), SHA1 value to set the reference to
- Returns:
the created ref
- Return type:
- create_release(tag_name, target_commitish=None, name=None, body=None, draft=False, prerelease=False)
Create a release for this repository.
- Parameters:
tag_name (str) – (required), name to give to the tag
target_commitish (str) – (optional), vague concept of a target, either a SHA or a branch name.
name (str) – (optional), name of the release
body (str) – (optional), description of the release
draft (bool) – (optional), whether this release is a draft or not
prerelease (bool) – (optional), whether this is a prerelease or not
- Returns:
the created release
- Return type:
- create_status(sha, state, target_url=None, description=None, context='default')
Create a status object on a commit.
- Parameters:
sha (str) – (required), SHA of the commit to create the status on
state (str) – (required), state of the test; only the following are accepted: ‘pending’, ‘success’, ‘error’, ‘failure’
target_url (str) – (optional), URL to associate with this status.
description (str) – (optional), short description of the status
context (str) – (optional), A string label to differentiate this status from the status of other systems
- Returns:
the created status
- Return type:
- create_tag(tag, message, sha, obj_type, tagger, lightweight=False)
Create a tag in this repository.
By default, this method creates an annotated tag. If you wish to create a lightweight tag instead, pass
lightweight=True
.If you are creating an annotated tag, this method makes 2 calls to the API:
Creates the tag object
Creates the reference for the tag
This behaviour is required by the GitHub API.
- Parameters:
tag (str) – (required), name of the tag
message (str) – (required), tag message
sha (str) – (required), SHA of the git object this is tagging
obj_type (str) – (required), type of object being tagged, e.g., ‘commit’, ‘tree’, ‘blob’
tagger (dict) – (required), containing the name, email of the tagger and optionally the date it was tagged
lightweight (bool) – (optional), if False, create an annotated tag, otherwise create a lightweight tag (a Reference).
- Returns:
if creating a lightweight tag, this will return a
Reference
, otherwise it will return aTag
- Return type:
- create_tree(tree, base_tree=None)
Create a tree on this repository.
- Parameters:
tree (list) – (required), specifies the tree structure. Format: [{‘path’: ‘path/file’, ‘mode’: ‘filemode’, ‘type’: ‘blob or tree’, ‘sha’: ‘44bfc6d…’}]
base_tree (str) – (optional), SHA1 of the tree you want to update with new data
- Returns:
the created tree
- Return type:
- delete()
Delete this repository.
- Returns:
True if successful, False otherwise
- Return type:
bool
- delete_key(key_id)
Delete the key with the specified id from your deploy keys list.
- Returns:
True if successful, False otherwise
- Return type:
bool
- delete_subscription()
Delete the user’s subscription to this repository.
- Returns:
True if successful, False otherwise
- Return type:
bool
- deployment(id)
Retrieve the deployment identified by
id
.- Parameters:
id (int) – (required), id for deployments.
- Returns:
the deployment
- Return type:
- deployments(number=-1, etag=None)
Iterate over deployments for this repository.
- Parameters:
number (int) – (optional), number of deployments to return. Default: -1, returns all available deployments
etag (str) – (optional), ETag from a previous request for all deployments
- Returns:
generator of deployments
- Return type:
- directory_contents(directory_path, ref=None, return_as=<class 'list'>)
Get the contents of each file in
directory_path
.If the path provided is actually a directory, you will receive a list back of the form:
[('filename.md', Contents(...)), ('github.py', Contents(...)), # ... ('fiz.py', Contents(...))]
You can either then transform it into a dictionary:
contents = dict(repo.directory_contents('path/to/dir/'))
Or you can use the
return_as
parameter to have it return a dictionary for you:contents = repo.directory_contents('path/to/dir/', return_as=dict)
- Parameters:
path (str) – (required), path to file, e.g. github3/repos/repo.py
ref (str) – (optional), the string name of a commit/branch/tag. Default: master
return_as – (optional), how to return the directory’s contents. Default:
list
- Returns:
list of tuples of the filename and the Contents returned
- Return type:
[(str,
Contents
)]- Raises:
github3.exceptions.UnprocessableResponseBody – When the requested directory is not actually a directory
- edit(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, default_branch=None, archived=None, allow_merge_commit=None, allow_squash_merge=None, allow_rebase_merge=None, has_projects=None)
Edit this repository.
- Parameters:
name (str) – (required), name of the repository
description (str) – (optional), If not
None
, change the description for this repository. API default:None
- leave value unchanged.homepage (str) – (optional), If not
None
, change the homepage for this repository. API default:None
- leave value unchanged.private (bool) – (optional), If
True
, make the repository private. IfFalse
, make the repository public. API default:None
- leave value unchanged.has_issues (bool) – (optional), If
True
, enable issues for this repository. IfFalse
, disable issues for this repository. API default:None
- leave value unchanged.has_wiki (bool) – (optional), If
True
, enable the wiki for this repository. IfFalse
, disable the wiki for this repository. API default:None
- leave value unchanged.has_downloads (bool) – (optional), If
True
, enable downloads for this repository. IfFalse
, disable downloads for this repository. API default:None
- leave value unchanged.default_branch (str) – (optional), If not
None
, change the default branch for this repository. API default:None
- leave value unchanged.archived (bool) – (optional), If not
None
, toggle the archived attribute on the repository to control whether it is archived or not.allow_rebase_merge (bool) – (optional), If not
None
, change whether the merge strategy that allows adding all commits from the head branch onto the base branch individually is enabled for this repository. API default:None
- leave value unchanged.allow_squash_merge (bool) – (optional), If not
None
, change whether combining all commits from the head branch into a single commit in the base branch is allowed. API default:None
- leave value unchanged.allow_merge_commit (bool) – (optional), If not
None
, change whether adding all commits from the head branch to the base branch with a merge commit is allowed. API default:None
- leave value unchanged.has_projects (bool) – (optional), If
True
, enable projects for this repository. IfFalse
, disable projects projects for this repository. API default:None
- leave value unchanged.
- Returns:
True if successful, False otherwise
- Return type:
bool
- events(number=-1, etag=None)
Iterate over events on this repository.
- 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:
- file_contents(path, ref=None)
Get the contents of the file pointed to by
path
.- Parameters:
path (str) – (required), path to file, e.g. github3/repos/repo.py
ref (str) – (optional), the string name of a commit/branch/tag. Default: master
- Returns:
the contents of the file requested
- Return type:
- forks(sort='', number=-1, etag=None)
Iterate over forks of this repository.
- Parameters:
sort (str) – (optional), accepted values: (‘newest’, ‘oldest’, ‘stargazers’), API default: ‘newest’
number (int) – (optional), number of forks to return. Default: -1 returns all forks
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of forks of this repository
- 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
.
- git_commit(sha)
Get a single (git) commit.
- Parameters:
sha (str) – (required), sha of the commit
- Returns:
the single commit data from git
- Return type:
- hook(hook_id)
Get a single hook.
- Parameters:
hook_id (int) – (required), id of the hook
- Returns:
the hook
- Return type:
- hooks(number=-1, etag=None)
Iterate over hooks registered on this repository.
- Parameters:
number (int) – (optional), number of hoks to return. Default: -1 returns all hooks
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of hooks
- Return type:
- ignore()
Ignore notifications from this repository for the user.
New in version 1.0.
This replaces
Repository#set_subscription
.- Returns:
the new repository subscription
- Return type:
:class:~github3.notifications.RepositorySubscription`
- import_issue(title, body, created_at, assignee=None, milestone=None, closed=None, labels=None, comments=None)
Import an issue into the repository.
See also: https://gist.github.com/jonmagic/5282384165e0f86ef105
- Parameters:
title (string) – (required) Title of issue
body (string) – (required) Body of issue
created_at (
datetime
or str) – (required) Creation timestampassignee (string) – (optional) Username to assign issue to
milestone (int) – (optional) Milestone ID
closed (boolean) – (optional) Status of issue is Closed if True
labels (list) – (optional) List of labels containing string names
comments (list) – (optional) List of dictionaries which contain created_at and body attributes
- Returns:
the imported issue
- Return type:
- imported_issue(imported_issue_id)
Retrieve imported issue specified by imported issue id.
- Parameters:
imported_issue_id (int) – (required) id of imported issue
- Returns:
the imported issue
- Return type:
- imported_issues(number=-1, since=None, etag=None)
Retrieve the collection of imported issues via the API.
See also: https://gist.github.com/jonmagic/5282384165e0f86ef105
- Parameters:
number (int) – (optional), number of imported issues to return. Default: -1 returns all branches
since – (optional), Only imported issues after this date will be returned. This can be a
datetime
instance, ISO8601 formatted date string, or a string formatted like so:2016-02-04
i.e.%Y-%m-%d
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of imported issues
- Return type:
- invitations(number=-1, etag=None)
Iterate over the invitations to this repository.
- 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
- is_assignee(username)
Check if the user can be assigned an issue on this repository.
- Parameters:
username (str or
User
) – name of the user to check- Returns:
bool
- is_collaborator(username)
Check to see if
username
is a collaborator on this repository.- Parameters:
username (str or
User
) – (required), login for the user- Returns:
True if successful, False otherwise
- Return type:
bool
- issue(number)
Get the issue specified by
number
.- Parameters:
number (int) – (required), number of the issue on this repository
- Returns:
the issue
- Return type:
- issue_events(number=-1, etag=None)
Iterate over issue events on this repository.
- 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 on issues
- Return type:
- issues(milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None)
Iterate over issues on this repo based upon parameters passed.
Changed in version 0.9.0: The
state
parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.- Parameters:
milestone (int) – (optional), ‘none’, or ‘*’
state (str) – (optional), accepted values: (‘all’, ‘open’, ‘closed’)
assignee (str) – (optional), ‘none’, ‘*’, or login name
mentioned (str) – (optional), user’s login name
labels (str) – (optional), comma-separated list of labels, e.g. ‘bug,ui,@high’
sort – (optional), accepted values: (‘created’, ‘updated’, ‘comments’, ‘created’)
direction (str) – (optional), accepted values: (‘asc’, ‘desc’)
since (
datetime
or str) – (optional), Only issues after this date will be returned. This can be adatetime
or anISO8601
formatted date string, e.g., 2012-05-20T23:10:27Znumber (int) – (optional), Number of issues to return. By default all issues are returned
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of issues
- Return type:
ShortIssue
- key(id_num)
Get the specified deploy key.
- Parameters:
id_num (int) – (required), id of the key
- Returns:
the deploy key
- Return type:
- keys(number=-1, etag=None)
Iterate over deploy keys on this repository.
- Parameters:
number (int) – (optional), number of keys to return. Default: -1 returns all available keys
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of keys
- Return type:
- label(name)
Get the label specified by
name
.- Parameters:
name (str) – (required), name of the label
- Returns:
the label
- Return type:
- labels(number=-1, etag=None)
Iterate over labels on this repository.
- Parameters:
number (int) – (optional), number of labels to return. Default: -1 returns all available labels
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of labels
- Return type:
- languages(number=-1, etag=None)
Iterate over the programming languages used in the repository.
- Parameters:
number (int) – (optional), number of languages to return. Default: -1 returns all used languages
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of tuples
- Return type:
tuple
- latest_pages_build()
Get the build information for the most recent Pages build.
- Returns:
the information for the most recent build
- Return type:
- latest_release()
Get the latest release.
Draft releases and prereleases are not returned by this endpoint.
- Returns:
the release
- Return type:
- license()
Get the contents of a license for the repo.
- Returns:
the license
- Return type:
RepositoryLicense
- mark_notifications(last_read='')
Mark all notifications in this repository as read.
- Parameters:
last_read (str) – (optional), Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now. Expected in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
. Example: “2012-10-09T23:39:01Z”.- Returns:
True if successful, False otherwise
- Return type:
bool
- merge(base, head, message='')
Perform a merge from
head
intobase
.- Parameters:
base (str) – (required), where you’re merging into
head (str) – (required), where you’re merging from
message (str) – (optional), message to be used for the commit
- Returns:
the commit resulting from the merge
- Return type:
- milestone(number)
Get the milestone indicated by
number
.- Parameters:
number (int) – (required), unique id number of the milestone
- Returns:
the milestone
- Return type:
- milestones(state=None, sort=None, direction=None, number=-1, etag=None)
Iterate over the milestones on this repository.
- Parameters:
state (str) – (optional), state of the milestones, accepted values: (‘open’, ‘closed’)
sort (str) – (optional), how to sort the milestones, accepted values: (‘due_date’, ‘completeness’)
direction (str) – (optional), direction to sort the milestones, accepted values: (‘asc’, ‘desc’)
number (int) – (optional), number of milestones to return. Default: -1 returns all milestones
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of milestones
- Return type:
- network_events(number=-1, etag=None)
Iterate over events on a network of repositories.
- 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:
- new_session()
Generate a new session.
- Returns:
A brand new session
- Return type:
- notifications(all=False, participating=False, since=None, number=-1, etag=None)
Iterate over the notifications for this repository.
- Parameters:
all (bool) – (optional), show all notifications, including ones marked as read
participating (bool) – (optional), show only the notifications the user is participating in directly
since (
datetime
or str) – (optional), filters out any notifications updated before the given time. This can be a datetime or an ISO8601 formatted date string, e.g., 2012-05-20T23:10:27Zetag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of notification threads
- Return type:
- pages()
Get information about this repository’s pages site.
- Returns:
information about this repository’s GitHub pages site
- Return type:
- pages_builds(number=-1, etag=None)
Iterate over pages builds of this repository.
- Parameters:
number (int) – (optional) the number of builds to return
etag (str) – (optional), ETag value from a previous request
- Returns:
generator of builds
- Return type:
- project(id, etag=None)
Return the organization project with the given ID.
- Parameters:
id (int) – (required), ID number of the project
- Returns:
the project
- Return type:
- projects(number=-1, etag=None)
Iterate over projects for this organization.
- Parameters:
number (int) – (optional), number of members to return. Default: -1 will return all available.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of projects
- Return type:
- pull_request(number)
Get the pull request indicated by
number
.- Parameters:
number (int) – (required), number of the pull request.
- Returns:
the pull request
- Return type:
- pull_requests(state=None, head=None, base=None, sort='created', direction='desc', number=-1, etag=None)
List pull requests on repository.
Changed in version 0.9.0:
The
state
parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.The
sort
parameter was added.The
direction
parameter was added.
- Parameters:
state (str) – (optional), accepted values: (‘all’, ‘open’, ‘closed’)
head (str) – (optional), filters pulls by head user and branch name in the format
user:ref-name
, e.g.,seveas:debian
base (str) – (optional), filter pulls by base branch name. Example:
develop
.sort (str) – (optional), Sort pull requests by
created
,updated
,popularity
,long-running
. Default: ‘created’direction (str) – (optional), Choose the direction to list pull requests. Accepted values: (‘desc’, ‘asc’). Default: ‘desc’
number (int) – (optional), number of pulls to return. Default: -1 returns all available pull requests
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of pull requests
- Return type:
- property ratelimit_remaining
Number of requests before GitHub imposes a ratelimit.
- Returns:
int
- readme()
Get the README for this repository.
- Returns:
this repository’s readme
- Return type:
- ref(ref)
Get a reference pointed to by
ref
.The most common will be branches and tags. For a branch, you must specify ‘heads/branchname’ and for a tag, ‘tags/tagname’. Essentially, the system should return any reference you provide it in the namespace, including notes and stashes (provided they exist on the server).
- Parameters:
ref (str) – (required)
- Returns:
the reference
- Return type:
- 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
- refs(subspace='', number=-1, etag=None)
Iterate over references for this repository.
- Parameters:
subspace (str) – (optional), e.g. ‘tags’, ‘stashes’, ‘notes’
number (int) – (optional), number of refs to return. Default: -1 returns all available refs
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of references
- Return type:
- release(id)
Get a single release.
- Parameters:
id (int) – (required), id of release
- Returns:
the release
- Return type:
- release_from_tag(tag_name)
Get a release by tag name.
release_from_tag() returns a release with specified tag while release() returns a release with specified release id
- Parameters:
tag_name (str) – (required) name of tag
- Returns:
the release
- Return type:
- releases(number=-1, etag=None)
Iterate over releases for this repository.
- Parameters:
number (int) – (optional), number of refs to return. Default: -1 returns all available refs
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of releases
- Return type:
- remove_collaborator(username)
Remove collaborator
username
from the repository.- Parameters:
username (str or
User
) – (required), login name of the collaborator- Returns:
True if successful, False otherwise
- Return type:
bool
- replace_topics(new_topics)
Replace the repository topics with
new_topics
.- Parameters:
topics (list) – (required), new topics of the repository
- Returns:
new topics of the repository
- Return type:
Topics
- stargazers(number=-1, etag=None)
List users who have starred this repository.
- Parameters:
number (int) – (optional), number of stargazers to return. Default: -1 returns all subscribers available
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of users
- Return type:
- statuses(sha, number=-1, etag=None)
Iterate over the statuses for a specific SHA.
Warning
Deprecated in v1.0. Also deprecated upstream https://developer.github.com/v3/repos/statuses/
- Parameters:
sha (str) – SHA of the commit to list the statuses of
number (int) – (optional), return up to number statuses. Default: -1 returns all available statuses.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of statuses
- Return type:
- subscribe()
Subscribe the user to this repository’s notifications.
New in version 1.0.
This replaces
Repository#set_subscription
- Returns:
the new repository subscription
- Return type:
- subscribers(number=-1, etag=None)
Iterate over users subscribed to this repository.
- Parameters:
number (int) – (optional), number of subscribers to return. Default: -1 returns all subscribers available
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of users subscribed to this repository
- Return type:
- subscription()
Return subscription for this Repository.
- Returns:
the user’s subscription to this repository
- Return type:
- tag(sha)
Get an annotated tag.
http://learn.github.com/p/tagging.html
- Parameters:
sha (str) – (required), sha of the object for this tag
- Returns:
the annotated tag
- Return type:
- tags(number=-1, etag=None)
Iterate over tags on this repository.
- Parameters:
number (int) – (optional), return up to at most number tags. Default: -1 returns all available tags.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of tags with GitHub repository specific information
- Return type:
- teams(number=-1, etag=None)
Iterate over teams with access to this repository.
- Parameters:
number (int) – (optional), return up to number Teams. Default: -1 returns all Teams.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of teams
- Return type:
- topics()
Get the topics of this repository.
- Returns:
this repository’s topics
- Return type:
Topics
- tree(sha, recursive=False)
Get a tree.
- Parameters:
sha (str) – (required), sha of the object for this tree
recursive (bool) – (optional), whether to fetch the tree recursively
- Returns:
the tree
- Return type:
- unignore()
Unignore notifications from this repository for the user.
New in version 1.3.
This replaces
Repository#set_subscription
.- Returns:
the new repository subscription
- Return type:
:class:~github3.notifications.RepositorySubscription`
- unsubscribe()
Unsubscribe the user to this repository’s notifications.
New in version 1.3.
This replaces
Repository#set_subscription
- Returns:
the new repository subscription
- Return type:
- views(per='day')
Get the total number of repository views and breakdown per day or week for the last 14 days.
New in version 1.4.0.
See also: https://developer.github.com/v3/repos/traffic/
- Parameters:
per (str) – (optional), (‘day’, ‘week’), views reporting period. Default ‘day’ will return views per day for the last 14 days.
- Returns:
views data
- Return type:
ViewsStats
- Raises:
ValueError if per is not a valid choice
- weekly_commit_count()
Retrieve the total commit counts.
Note
All statistics methods may return a 202. If github3.py receives a 202 in this case, it will return an emtpy dictionary. You should give the API a moment to compose the data and then re -request it via this method.
..versionadded:: 0.7
The dictionary returned has two entries:
all
andowner
. Each has a fifty-two element long list of commit counts. (Note:all
includes the owner.)d['all'][0]
will be the oldest week,d['all'][51]
will be the most recent.- Returns:
the commit count as a dictionary
- Return type:
dict
- class github3.repos.repo.ShortRepository(json, session: GitHubSession)
This represents a Repository object returned in collections.
GitHub’s API returns different amounts of information about repositories based upon how that information is retrieved. This object exists to represent the full amount of information returned for a specific repository. For example, you would receive this class when calling
repository()
. To provide a clear distinction between the types of repositories, github3.py uses different classes with different sets of attributes.This object only has the following attributes:
- url
The GitHub API URL for this repository, e.g.,
https://api.github.com/repos/sigmavirus24/github3.py
.
- archive_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkarchive_urlt.variables
for the list of variables that can be passed toarchive_urlt.expand()
.
- assignees_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkassignees_urlt.variables
for the list of variables that can be passed toassignees_urlt.expand()
.
- blobs_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkblobs_urlt.variables
for the list of variables that can be passed toblobs_urlt.expand()
.
- branches_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkbranches_urlt.variables
for the list of variables that can be passed tobranches_urlt.expand()
.
- collaborators_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkcollaborators_urlt.variables
for the list of variables that can be passed tocollaborators_urlt.expand()
.
- comments_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkcomments_urlt.variables
for the list of variables that can be passed tocomments_urlt.expand()
.
- commits_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkcommits_urlt.variables
for the list of variables that can be passed tocommits_urlt.expand()
.
- compare_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkcompare_urlt.variables
for the list of variables that can be passed tocompare_urlt.expand()
.
- contents_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkcontents_urlt.variables
for the list of variables that can be passed tocontents_urlt.expand()
.
- contributors_url
The URL to retrieve this repository’s list of contributors.
- deployments_url
The URL to retrieve this repository’s list of deployments.
- description
The administrator created description of the repository.
- downloads_url
The URL to retrieve this repository’s list of downloads.
- events_url
The URL to retrieve this repository’s list of events.
- fork
Whether or not this repository is a fork of another.
- forks_url
The URL to retrieve this repository’s list of forks.
- full_name
The full name of this repository, e.g.,
sigmavirus24/github3.py
.
- git_commits_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkgit_commits_urlt.variables
for the list of variables that can be passed togit_commits_urlt.expand()
.
- git_refs_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkgit_refs_urlt.variables
for the list of variables that can be passed togit_refs_urlt.expand()
.
- git_tags_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkgit_tags_urlt.variables
for the list of variables that can be passed togit_tags_urlt.expand()
.
- hooks_url
The URL to retrieve this repository’s list of hooks.
- html_url
The HTML URL of this repository, e.g.,
https://github.com/sigmavirus24/github3.py
.
- id
The unique GitHub assigned numerical id of this repository.
- issue_comment_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkissue_comment_urlt.variables
for the list of variables that can be passed toissue_comment_urlt.expand()
.
- issue_events_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkissue_events_urlt.variables
for the list of variables that can be passed toissue_events_urlt.expand()
.
- issues_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkissues_urlt.variables
for the list of variables that can be passed toissues_urlt.expand()
.
- keys_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkkeys_urlt.variables
for the list of variables that can be passed tokeys_urlt.expand()
.
- labels_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checklabels_urlt.variables
for the list of variables that can be passed tolabels_urlt.expand()
.
- languages_url
The URL to retrieve this repository’s list of languages.
- merges_url
The URL to retrieve this repository’s list of merges.
- milestones_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkmilestones_urlt.variables
for the list of variables that can be passed tomilestones_urlt.expand()
.
- name
The name of the repository, e.g.,
github3.py
.
- notifications_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checknotifications_urlt.variables
for the list of variables that can be passed tonotifications_urlt.expand()
.
- private
Whether the repository is private or public.
- pulls_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkpulls_urlt.variables
for the list of variables that can be passed topulls_urlt.expand()
.
- releases_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkreleases_urlt.variables
for the list of variables that can be passed toreleases_urlt.expand()
.
- stargazers_url
The URL to retrieve this repository’s list of stargazers.
- statuses_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checkstatuses_urlt.variables
for the list of variables that can be passed tostatuses_urlt.expand()
.
- subscribers_url
The URL to retrieve this repository’s list of subscribers.
- subscription_url
The URL to modify subscription to this repository.
- tags_url
The URL to retrieve this repository’s list of tags.
- teams_url
The URL to retrieve this repository’s list of teams.
- trees_urlt
The
URITemplate
object representing the URI template returned by GitHub’s API. Checktrees_urlt.variables
for the list of variables that can be passed totrees_urlt.expand()
.
New in version 1.0.0.
- add_collaborator(username, permission=None)
Add
username
as a collaborator to a repository.- Parameters:
username (str or
User
) – (required), username of the userpermission (str) – (optional), permission to grant the collaborator, valid on organization repositories only. Can be ‘pull’, ‘triage’, ‘push’, ‘maintain’, ‘admin’ or an organization-defined custom role name.
- Returns:
True if successful, False otherwise
- Return type:
- archive(format, path='', ref='master')
Get the tarball or zipball archive for this repo at ref.
See: http://developer.github.com/v3/repos/contents/#get-archive-link
- Parameters:
format (str) – (required), accepted values: (‘tarball’, ‘zipball’)
path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. it can take a file-like object as well
ref (str) – (optional)
- Returns:
True if successful, False otherwise
- Return type:
bool
- 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
- asset(id)
Return a single asset.
- Parameters:
id (int) – (required), id of the asset
- Returns:
the asset
- Return type:
- assignees(number=-1, etag=None)
Iterate over all assignees to which an issue may be assigned.
- Parameters:
number (int) – (optional), number of assignees to return. Default: -1 returns all available assignees
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of users
- Return type:
- auto_trigger_checks(app_id, enabled=True)
Change preferences for automatic creation of check suites.
New in version 1.3.0.
Enable/disable the automatic flow when creating check suites. By default, the check suite is automatically created each time code is pushed. When the automatic creation is disable they can be created manually.
- Parameters:
app_id (int) – (required), the id of the GitHub App
enabled (bool) – (optional), enable automatic creation of check suites Default: True
- Returns:
the check suite settings for this repository
- Return type:
dict
- blob(sha)
Get the blob indicated by
sha
.- Parameters:
sha (str) – (required), sha of the blob
- Returns:
the git blob
- Return type:
- branch(name)
Get the branch
name
of this repository.- Parameters:
name (str) – (required), branch name
- Returns:
the branch
- Return type:
- branches(number=-1, protected=False, etag=None)
Iterate over the branches in this repository.
- Parameters:
number (int) – (optional), number of branches to return. Default: -1 returns all branches
protected (bool) – (optional), True lists only protected branches. Default: False
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of branches
- Return type:
- check_run(id)
Return a single check run.
New in version 1.3.0.
- Parameters:
id (int) – (required), id of the check run
- Returns:
the check run
- Return type:
CheckRun
- check_suite(id)
Return a single check suite.
New in version 1.3.0.
- Parameters:
id (int) – (required), id of the check suite
- Returns:
the check suite
- Return type:
CheckSuite
- clones(per='day')
Get the total number of repository clones and breakdown per day or week for the last 14 days.
New in version 1.4.0.
See also: https://developer.github.com/v3/repos/traffic/
- Parameters:
per (str) – (optional), (‘day’, ‘week’), clones reporting period. Default ‘day’ will return clones per day for the last 14 days.
- Returns:
clones data
- Return type:
ClonesStats
- Raises:
ValueError if per is not a valid choice
- code_frequency(number=-1, etag=None)
Iterate over the code frequency per week.
New in version 0.7.
Returns a weekly aggregate of the number of additions and deletions pushed to this repository.
Note
All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new
last_status
attribute. If it is a 202 you should wait before re-requesting.- Parameters:
number (int) – (optional), number of weeks to return. Default: -1 returns all weeks
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of lists
[seconds_from_epoch, additions, deletions]
- Return type:
list
- collaborators(affiliation='all', number=-1, etag=None)
Iterate over the collaborators of this repository.
- Parameters:
affiliation (str) – (optional), affiliation of the collaborator to the repository. Default: “all” returns contributors with all affiliations
number (int) – (optional), number of collaborators to return. Default: -1 returns all comments
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of collaborators
- Return type:
- comments(number=-1, etag=None)
Iterate over comments on all commits in the repository.
- Parameters:
number (int) – (optional), number of comments to return. Default: -1 returns all comments
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of comments on commits
- Return type:
- commit(sha)
Get a single (repo) commit.
See
git_commit()
for the Git Data Commit.- Parameters:
sha (str) – (required), sha of the commit
- Returns:
the commit
- Return type:
- commit_activity(number=-1, etag=None)
Iterate over last year of commit activity by week.
New in version 0.7.
See: http://developer.github.com/v3/repos/statistics/
Note
All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new
last_status
attribute. If it is a 202 you should wait before re-requesting.- Parameters:
number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of dictionaries
- Return type:
dict
- commit_comment(comment_id)
Get a single commit comment.
- Parameters:
comment_id (int) – (required), id of the comment used by GitHub
- Returns:
the comment on the commit
- Return type:
- commits(sha=None, path=None, author=None, number=-1, etag=None, since=None, until=None, per_page=None)
Iterate over commits in this repository.
- Parameters:
sha (str) – (optional), sha or branch to start listing commits from
path (str) – (optional), commits containing this path will be listed
author (str) – (optional), GitHub login, real name, or email to filter commits by (using commit author)
number (int) – (optional), number of commits to return. Default: -1 returns all commits
etag (str) – (optional), ETag from a previous request to the same endpoint
since (
datetime
or str) – (optional), Only commits after this date will be returned. This can be adatetime
or anISO8601
formatted date string.until (
datetime
or str) – (optional), Only commits before this date will be returned. This can be adatetime
or anISO8601
formatted date string.per_page (int) – (optional), commits listing page size
- Returns:
generator of commits
- Return type:
- compare_commits(base, head)
Compare two commits.
- Parameters:
base (str) – (required), base for the comparison
head (str) – (required), compare this against base
- Returns:
the comparison of the commits
- Return type:
- contributor_statistics(number=-1, etag=None)
Iterate over the contributors list.
New in version 0.7.
See also: http://developer.github.com/v3/repos/statistics/
Note
All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new
last_status
attribute. If it is a 202 you should wait before re-requesting.- Parameters:
number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of contributor statistics for each contributor
- Return type:
- contributors(anon=False, number=-1, etag=None)
Iterate over the contributors to this repository.
- Parameters:
anon (bool) – (optional), True lists anonymous contributors as well
number (int) – (optional), number of contributors to return. Default: -1 returns all contributors
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of contributor users
- Return type:
- create_blob(content, encoding)
Create a blob with
content
.- Parameters:
content (str) – (required), content of the blob
encoding (str) – (required), (‘base64’, ‘utf-8’)
- Returns:
string of the SHA returned
- Returns:
str
- create_branch_ref(name, sha=None)
Create a branch git reference.
This is a shortcut for calling
github3.repos.repo.Repository.create_ref()
.- Parameters:
branch (str) – (required), the branch to create
sha (str) – the commit to base the branch from
- Returns:
a reference object representing the branch
- Return type:
- create_check_run(name, head_sha, details_url=None, external_id=None, started_at=None, status=None, conclusion=None, completed_at=None, output=None, actions=None)
Create a check run object on a commit
New in version 1.3.0.
- Parameters:
name (str) – (required), The name of the check
head_sha (str) – (required), The SHA of the commit
details_url (str) – (optional), The URL of the integrator’s site that has the full details of the check
external_id (str) – (optional), A reference for the run on the integrator’s system
started_at (str) – (optional), ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ
status (str) – (optional), (‘queued’, ‘in_progress’, ‘completed’)
conclusion (str) – (optional), Required if you provide ‘completed_at’, or a ‘status’ of ‘completed’. The final conclusion of the check. (‘success’, ‘failure’, ‘neutral’, ‘cancelled’, ‘timed_out’, ‘action_required’)
completed_at (str) – (optional), Required if you provide ‘conclusion’. ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ
output (dict) – (optional), key-value pairs representing the output. Format:
{'title': 'string', 'summary': 'text, can be markdown', 'text': 'text, can be markdown', 'annotations': [{}], 'images': [{}]}
actions (list) – (optional), list of action objects. Format is:
[{'label': 'text', 'description', 'text', 'identifier', 'text'}, ...]
- Returns:
the created check run
- Return type:
CheckRun
- create_check_suite(head_sha)
Create a check suite object on a commit
New in version 1.3.0.
- Parameters:
head_sha (str) – The sha of the head commit.
- Returns:
the created check suite
- Return type:
CheckSuite
- create_comment(body, sha, path=None, position=None, line=1)
Create a comment on a commit.
- Parameters:
body (str) – (required), body of the message
sha (str) – (required), commit id
path (str) – (optional), relative path of the file to comment on
position (str) – (optional), line index in the diff to comment on
line (int) – (optional), line number of the file to comment on, default: 1
- Returns:
the created comment
- Return type:
- create_commit(message, tree, parents, author=None, committer=None)
Create a commit on this repository.
- Parameters:
message (str) – (required), commit message
tree (str) – (required), SHA of the tree object this commit points to
parents (list) – (required), SHAs of the commits that were parents of this commit. If empty, the commit will be written as the root commit. Even if there is only one parent, this should be an array.
author (dict) – (optional), if omitted, GitHub will use the authenticated user’s credentials and the current time. Format: {‘name’: ‘Committer Name’, ‘email’: ‘name@example.com’, ‘date’: ‘YYYY-MM-DDTHH:MM:SS+HH:00’}
committer (dict) – (optional), if ommitted, GitHub will use the author parameters. Should be the same format as the author parameter.
- Returns:
the created commit
- Return type:
- create_deployment(ref, required_contexts=None, payload='', auto_merge=False, description='', environment=None)
Create a deployment.
- Parameters:
ref (str) – (required), The ref to deploy. This can be a branch, tag, or sha.
required_contexts (list) – Optional array of status contexts verified against commit status checks. To bypass checking entirely pass an empty array. Default: []
payload (str) – Optional JSON payload with extra information about the deployment. Default: “”
auto_merge (bool) – Optional parameter to merge the default branch into the requested deployment branch if necessary. Default: False
description (str) – Optional short description. Default: “”
environment (str) – Optional name for the target deployment environment (e.g., production, staging, qa). Default: “production”
- Returns:
the created deployment
- Return type:
- create_file(path, message, content, branch=None, committer=None, author=None)
Create a file in this repository.
See also: http://developer.github.com/v3/repos/contents/#create-a-file
- Parameters:
path (str) – (required), path of the file in the repository
message (str) – (required), commit message
content (bytes) – (required), the actual data in the file
branch (str) – (optional), branch to create the commit on. Defaults to the default branch of the repository
committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email.
author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
- Returns:
dictionary of contents and commit for created file
- Return type:
- create_fork(organization=None)
Create a fork of this repository.
- Parameters:
organization (str) – (required), login for organization to create the fork under
- Returns:
the fork of this repository
- Return type:
- create_hook(name, config, events=['push'], active=True)
Create a hook on this repository.
- Parameters:
name (str) – (required), name of the hook
config (dict) – (required), key-value pairs which act as settings for this hook
events (list) – (optional), events the hook is triggered for
active (bool) – (optional), whether the hook is actually triggered
- Returns:
the created hook
- Return type:
- create_issue(title, body=None, assignee=None, milestone=None, labels=None, assignees=None)
Create an issue on this repository.
- Parameters:
title (str) – (required), title of the issue
body (str) – (optional), body of the issue
assignee (str) – (optional), login of the user to assign the issue to
milestone (int) – (optional), id number of the milestone to attribute this issue to (e.g.
m
is aMilestone
object,m.number
is what you pass here.)labels ([str]) – (optional), labels to apply to this issue
assignees ([str]) – (optional), login of the users to assign the issue to
- Returns:
the created issue
- Return type:
- create_key(title, key, read_only=False)
Create a deploy key.
- Parameters:
title (str) – (required), title of key
key (str) – (required), key text
read_only (bool) – (optional), restrict key access to read-only, default is False
- Returns:
the created key
- Return type:
- create_label(name, color, description=None)
Create a label for this repository.
- Parameters:
name (str) – (required), name to give to the label
color (str) – (required), value of the color to assign to the label, e.g., ‘#fafafa’ or ‘fafafa’ (the latter is what is sent)
description (str) – (optional), description to give to the label
- Returns:
the created label
- Return type:
- create_milestone(title, state=None, description=None, due_on=None)
Create a milestone for this repository.
- Parameters:
title (str) – (required), title of the milestone
state (str) – (optional), state of the milestone, accepted values: (‘open’, ‘closed’), default: ‘open’
description (str) – (optional), description of the milestone
due_on (str) – (optional), ISO 8601 formatted due date
- Returns:
the created milestone
- Return type:
- create_project(name, body=None)
Create a project for this repository.
- Parameters:
name (str) – (required), name of the project
body (str) – (optional), body of the project
- Returns:
the created project
- Return type:
- create_pull(title, base, head, body=None, maintainer_can_modify=None)
Create a pull request of
head
ontobase
branch in this repo.- Parameters:
title (str) – (required)
base (str) – (required), e.g., ‘master’
head (str) – (required), e.g., ‘username:branch’
body (str) – (optional), markdown formatted description
maintainer_can_modify (bool) – (optional), Indicates whether a maintainer is allowed to modify the pull request or not.
- Returns:
the created pull request
- Return type:
- create_pull_from_issue(issue, base, head)
Create a pull request from issue #``issue``.
- Parameters:
issue (int) – (required), issue number
base (str) – (required), e.g., ‘master’
head (str) – (required), e.g., ‘username:branch’
- Returns:
the created pull request
- Return type:
- create_ref(ref, sha)
Create a reference in this repository.
- Parameters:
ref (str) – (required), fully qualified name of the reference, e.g.
refs/heads/master
. If it doesn’t start withrefs
and contain at least two slashes, GitHub’s API will reject it.sha (str) – (required), SHA1 value to set the reference to
- Returns:
the created ref
- Return type:
- create_release(tag_name, target_commitish=None, name=None, body=None, draft=False, prerelease=False)
Create a release for this repository.
- Parameters:
tag_name (str) – (required), name to give to the tag
target_commitish (str) – (optional), vague concept of a target, either a SHA or a branch name.
name (str) – (optional), name of the release
body (str) – (optional), description of the release
draft (bool) – (optional), whether this release is a draft or not
prerelease (bool) – (optional), whether this is a prerelease or not
- Returns:
the created release
- Return type:
- create_status(sha, state, target_url=None, description=None, context='default')
Create a status object on a commit.
- Parameters:
sha (str) – (required), SHA of the commit to create the status on
state (str) – (required), state of the test; only the following are accepted: ‘pending’, ‘success’, ‘error’, ‘failure’
target_url (str) – (optional), URL to associate with this status.
description (str) – (optional), short description of the status
context (str) – (optional), A string label to differentiate this status from the status of other systems
- Returns:
the created status
- Return type:
- create_tag(tag, message, sha, obj_type, tagger, lightweight=False)
Create a tag in this repository.
By default, this method creates an annotated tag. If you wish to create a lightweight tag instead, pass
lightweight=True
.If you are creating an annotated tag, this method makes 2 calls to the API:
Creates the tag object
Creates the reference for the tag
This behaviour is required by the GitHub API.
- Parameters:
tag (str) – (required), name of the tag
message (str) – (required), tag message
sha (str) – (required), SHA of the git object this is tagging
obj_type (str) – (required), type of object being tagged, e.g., ‘commit’, ‘tree’, ‘blob’
tagger (dict) – (required), containing the name, email of the tagger and optionally the date it was tagged
lightweight (bool) – (optional), if False, create an annotated tag, otherwise create a lightweight tag (a Reference).
- Returns:
if creating a lightweight tag, this will return a
Reference
, otherwise it will return aTag
- Return type:
- create_tree(tree, base_tree=None)
Create a tree on this repository.
- Parameters:
tree (list) – (required), specifies the tree structure. Format: [{‘path’: ‘path/file’, ‘mode’: ‘filemode’, ‘type’: ‘blob or tree’, ‘sha’: ‘44bfc6d…’}]
base_tree (str) – (optional), SHA1 of the tree you want to update with new data
- Returns:
the created tree
- Return type:
- delete()
Delete this repository.
- Returns:
True if successful, False otherwise
- Return type:
bool
- delete_key(key_id)
Delete the key with the specified id from your deploy keys list.
- Returns:
True if successful, False otherwise
- Return type:
bool
- delete_subscription()
Delete the user’s subscription to this repository.
- Returns:
True if successful, False otherwise
- Return type:
bool
- deployment(id)
Retrieve the deployment identified by
id
.- Parameters:
id (int) – (required), id for deployments.
- Returns:
the deployment
- Return type:
- deployments(number=-1, etag=None)
Iterate over deployments for this repository.
- Parameters:
number (int) – (optional), number of deployments to return. Default: -1, returns all available deployments
etag (str) – (optional), ETag from a previous request for all deployments
- Returns:
generator of deployments
- Return type:
- directory_contents(directory_path, ref=None, return_as=<class 'list'>)
Get the contents of each file in
directory_path
.If the path provided is actually a directory, you will receive a list back of the form:
[('filename.md', Contents(...)), ('github.py', Contents(...)), # ... ('fiz.py', Contents(...))]
You can either then transform it into a dictionary:
contents = dict(repo.directory_contents('path/to/dir/'))
Or you can use the
return_as
parameter to have it return a dictionary for you:contents = repo.directory_contents('path/to/dir/', return_as=dict)
- Parameters:
path (str) – (required), path to file, e.g. github3/repos/repo.py
ref (str) – (optional), the string name of a commit/branch/tag. Default: master
return_as – (optional), how to return the directory’s contents. Default:
list
- Returns:
list of tuples of the filename and the Contents returned
- Return type:
[(str,
Contents
)]- Raises:
github3.exceptions.UnprocessableResponseBody – When the requested directory is not actually a directory
- edit(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, default_branch=None, archived=None, allow_merge_commit=None, allow_squash_merge=None, allow_rebase_merge=None, has_projects=None)
Edit this repository.
- Parameters:
name (str) – (required), name of the repository
description (str) – (optional), If not
None
, change the description for this repository. API default:None
- leave value unchanged.homepage (str) – (optional), If not
None
, change the homepage for this repository. API default:None
- leave value unchanged.private (bool) – (optional), If
True
, make the repository private. IfFalse
, make the repository public. API default:None
- leave value unchanged.has_issues (bool) – (optional), If
True
, enable issues for this repository. IfFalse
, disable issues for this repository. API default:None
- leave value unchanged.has_wiki (bool) – (optional), If
True
, enable the wiki for this repository. IfFalse
, disable the wiki for this repository. API default:None
- leave value unchanged.has_downloads (bool) – (optional), If
True
, enable downloads for this repository. IfFalse
, disable downloads for this repository. API default:None
- leave value unchanged.default_branch (str) – (optional), If not
None
, change the default branch for this repository. API default:None
- leave value unchanged.archived (bool) – (optional), If not
None
, toggle the archived attribute on the repository to control whether it is archived or not.allow_rebase_merge (bool) – (optional), If not
None
, change whether the merge strategy that allows adding all commits from the head branch onto the base branch individually is enabled for this repository. API default:None
- leave value unchanged.allow_squash_merge (bool) – (optional), If not
None
, change whether combining all commits from the head branch into a single commit in the base branch is allowed. API default:None
- leave value unchanged.allow_merge_commit (bool) – (optional), If not
None
, change whether adding all commits from the head branch to the base branch with a merge commit is allowed. API default:None
- leave value unchanged.has_projects (bool) – (optional), If
True
, enable projects for this repository. IfFalse
, disable projects projects for this repository. API default:None
- leave value unchanged.
- Returns:
True if successful, False otherwise
- Return type:
bool
- events(number=-1, etag=None)
Iterate over events on this repository.
- 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:
- file_contents(path, ref=None)
Get the contents of the file pointed to by
path
.- Parameters:
path (str) – (required), path to file, e.g. github3/repos/repo.py
ref (str) – (optional), the string name of a commit/branch/tag. Default: master
- Returns:
the contents of the file requested
- Return type:
- forks(sort='', number=-1, etag=None)
Iterate over forks of this repository.
- Parameters:
sort (str) – (optional), accepted values: (‘newest’, ‘oldest’, ‘stargazers’), API default: ‘newest’
number (int) – (optional), number of forks to return. Default: -1 returns all forks
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of forks of this repository
- 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
.
- git_commit(sha)
Get a single (git) commit.
- Parameters:
sha (str) – (required), sha of the commit
- Returns:
the single commit data from git
- Return type:
- hook(hook_id)
Get a single hook.
- Parameters:
hook_id (int) – (required), id of the hook
- Returns:
the hook
- Return type:
- hooks(number=-1, etag=None)
Iterate over hooks registered on this repository.
- Parameters:
number (int) – (optional), number of hoks to return. Default: -1 returns all hooks
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of hooks
- Return type:
- ignore()
Ignore notifications from this repository for the user.
New in version 1.0.
This replaces
Repository#set_subscription
.- Returns:
the new repository subscription
- Return type:
:class:~github3.notifications.RepositorySubscription`
- import_issue(title, body, created_at, assignee=None, milestone=None, closed=None, labels=None, comments=None)
Import an issue into the repository.
See also: https://gist.github.com/jonmagic/5282384165e0f86ef105
- Parameters:
title (string) – (required) Title of issue
body (string) – (required) Body of issue
created_at (
datetime
or str) – (required) Creation timestampassignee (string) – (optional) Username to assign issue to
milestone (int) – (optional) Milestone ID
closed (boolean) – (optional) Status of issue is Closed if True
labels (list) – (optional) List of labels containing string names
comments (list) – (optional) List of dictionaries which contain created_at and body attributes
- Returns:
the imported issue
- Return type:
- imported_issue(imported_issue_id)
Retrieve imported issue specified by imported issue id.
- Parameters:
imported_issue_id (int) – (required) id of imported issue
- Returns:
the imported issue
- Return type:
- imported_issues(number=-1, since=None, etag=None)
Retrieve the collection of imported issues via the API.
See also: https://gist.github.com/jonmagic/5282384165e0f86ef105
- Parameters:
number (int) – (optional), number of imported issues to return. Default: -1 returns all branches
since – (optional), Only imported issues after this date will be returned. This can be a
datetime
instance, ISO8601 formatted date string, or a string formatted like so:2016-02-04
i.e.%Y-%m-%d
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of imported issues
- Return type:
- invitations(number=-1, etag=None)
Iterate over the invitations to this repository.
- 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
- is_assignee(username)
Check if the user can be assigned an issue on this repository.
- Parameters:
username (str or
User
) – name of the user to check- Returns:
bool
- is_collaborator(username)
Check to see if
username
is a collaborator on this repository.- Parameters:
username (str or
User
) – (required), login for the user- Returns:
True if successful, False otherwise
- Return type:
bool
- issue(number)
Get the issue specified by
number
.- Parameters:
number (int) – (required), number of the issue on this repository
- Returns:
the issue
- Return type:
- issue_events(number=-1, etag=None)
Iterate over issue events on this repository.
- 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 on issues
- Return type:
- issues(milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None)
Iterate over issues on this repo based upon parameters passed.
Changed in version 0.9.0: The
state
parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.- Parameters:
milestone (int) – (optional), ‘none’, or ‘*’
state (str) – (optional), accepted values: (‘all’, ‘open’, ‘closed’)
assignee (str) – (optional), ‘none’, ‘*’, or login name
mentioned (str) – (optional), user’s login name
labels (str) – (optional), comma-separated list of labels, e.g. ‘bug,ui,@high’
sort – (optional), accepted values: (‘created’, ‘updated’, ‘comments’, ‘created’)
direction (str) – (optional), accepted values: (‘asc’, ‘desc’)
since (
datetime
or str) – (optional), Only issues after this date will be returned. This can be adatetime
or anISO8601
formatted date string, e.g., 2012-05-20T23:10:27Znumber (int) – (optional), Number of issues to return. By default all issues are returned
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of issues
- Return type:
ShortIssue
- key(id_num)
Get the specified deploy key.
- Parameters:
id_num (int) – (required), id of the key
- Returns:
the deploy key
- Return type:
- keys(number=-1, etag=None)
Iterate over deploy keys on this repository.
- Parameters:
number (int) – (optional), number of keys to return. Default: -1 returns all available keys
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of keys
- Return type:
- label(name)
Get the label specified by
name
.- Parameters:
name (str) – (required), name of the label
- Returns:
the label
- Return type:
- labels(number=-1, etag=None)
Iterate over labels on this repository.
- Parameters:
number (int) – (optional), number of labels to return. Default: -1 returns all available labels
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of labels
- Return type:
- languages(number=-1, etag=None)
Iterate over the programming languages used in the repository.
- Parameters:
number (int) – (optional), number of languages to return. Default: -1 returns all used languages
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of tuples
- Return type:
tuple
- latest_pages_build()
Get the build information for the most recent Pages build.
- Returns:
the information for the most recent build
- Return type:
- latest_release()
Get the latest release.
Draft releases and prereleases are not returned by this endpoint.
- Returns:
the release
- Return type:
- license()
Get the contents of a license for the repo.
- Returns:
the license
- Return type:
RepositoryLicense
- mark_notifications(last_read='')
Mark all notifications in this repository as read.
- Parameters:
last_read (str) – (optional), Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now. Expected in ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZ
. Example: “2012-10-09T23:39:01Z”.- Returns:
True if successful, False otherwise
- Return type:
bool
- merge(base, head, message='')
Perform a merge from
head
intobase
.- Parameters:
base (str) – (required), where you’re merging into
head (str) – (required), where you’re merging from
message (str) – (optional), message to be used for the commit
- Returns:
the commit resulting from the merge
- Return type:
- milestone(number)
Get the milestone indicated by
number
.- Parameters:
number (int) – (required), unique id number of the milestone
- Returns:
the milestone
- Return type:
- milestones(state=None, sort=None, direction=None, number=-1, etag=None)
Iterate over the milestones on this repository.
- Parameters:
state (str) – (optional), state of the milestones, accepted values: (‘open’, ‘closed’)
sort (str) – (optional), how to sort the milestones, accepted values: (‘due_date’, ‘completeness’)
direction (str) – (optional), direction to sort the milestones, accepted values: (‘asc’, ‘desc’)
number (int) – (optional), number of milestones to return. Default: -1 returns all milestones
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of milestones
- Return type:
- network_events(number=-1, etag=None)
Iterate over events on a network of repositories.
- 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:
- new_session()
Generate a new session.
- Returns:
A brand new session
- Return type:
- notifications(all=False, participating=False, since=None, number=-1, etag=None)
Iterate over the notifications for this repository.
- Parameters:
all (bool) – (optional), show all notifications, including ones marked as read
participating (bool) – (optional), show only the notifications the user is participating in directly
since (
datetime
or str) – (optional), filters out any notifications updated before the given time. This can be a datetime or an ISO8601 formatted date string, e.g., 2012-05-20T23:10:27Zetag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of notification threads
- Return type:
- pages()
Get information about this repository’s pages site.
- Returns:
information about this repository’s GitHub pages site
- Return type:
- pages_builds(number=-1, etag=None)
Iterate over pages builds of this repository.
- Parameters:
number (int) – (optional) the number of builds to return
etag (str) – (optional), ETag value from a previous request
- Returns:
generator of builds
- Return type:
- project(id, etag=None)
Return the organization project with the given ID.
- Parameters:
id (int) – (required), ID number of the project
- Returns:
the project
- Return type:
- projects(number=-1, etag=None)
Iterate over projects for this organization.
- Parameters:
number (int) – (optional), number of members to return. Default: -1 will return all available.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of projects
- Return type:
- pull_request(number)
Get the pull request indicated by
number
.- Parameters:
number (int) – (required), number of the pull request.
- Returns:
the pull request
- Return type:
- pull_requests(state=None, head=None, base=None, sort='created', direction='desc', number=-1, etag=None)
List pull requests on repository.
Changed in version 0.9.0:
The
state
parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.The
sort
parameter was added.The
direction
parameter was added.
- Parameters:
state (str) – (optional), accepted values: (‘all’, ‘open’, ‘closed’)
head (str) – (optional), filters pulls by head user and branch name in the format
user:ref-name
, e.g.,seveas:debian
base (str) – (optional), filter pulls by base branch name. Example:
develop
.sort (str) – (optional), Sort pull requests by
created
,updated
,popularity
,long-running
. Default: ‘created’direction (str) – (optional), Choose the direction to list pull requests. Accepted values: (‘desc’, ‘asc’). Default: ‘desc’
number (int) – (optional), number of pulls to return. Default: -1 returns all available pull requests
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of pull requests
- Return type:
- property ratelimit_remaining
Number of requests before GitHub imposes a ratelimit.
- Returns:
int
- readme()
Get the README for this repository.
- Returns:
this repository’s readme
- Return type:
- ref(ref)
Get a reference pointed to by
ref
.The most common will be branches and tags. For a branch, you must specify ‘heads/branchname’ and for a tag, ‘tags/tagname’. Essentially, the system should return any reference you provide it in the namespace, including notes and stashes (provided they exist on the server).
- Parameters:
ref (str) – (required)
- Returns:
the reference
- Return type:
- 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
- refs(subspace='', number=-1, etag=None)
Iterate over references for this repository.
- Parameters:
subspace (str) – (optional), e.g. ‘tags’, ‘stashes’, ‘notes’
number (int) – (optional), number of refs to return. Default: -1 returns all available refs
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of references
- Return type:
- release(id)
Get a single release.
- Parameters:
id (int) – (required), id of release
- Returns:
the release
- Return type:
- release_from_tag(tag_name)
Get a release by tag name.
release_from_tag() returns a release with specified tag while release() returns a release with specified release id
- Parameters:
tag_name (str) – (required) name of tag
- Returns:
the release
- Return type:
- releases(number=-1, etag=None)
Iterate over releases for this repository.
- Parameters:
number (int) – (optional), number of refs to return. Default: -1 returns all available refs
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of releases
- Return type:
- remove_collaborator(username)
Remove collaborator
username
from the repository.- Parameters:
username (str or
User
) – (required), login name of the collaborator- Returns:
True if successful, False otherwise
- Return type:
bool
- replace_topics(new_topics)
Replace the repository topics with
new_topics
.- Parameters:
topics (list) – (required), new topics of the repository
- Returns:
new topics of the repository
- Return type:
Topics
- stargazers(number=-1, etag=None)
List users who have starred this repository.
- Parameters:
number (int) – (optional), number of stargazers to return. Default: -1 returns all subscribers available
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of users
- Return type:
- statuses(sha, number=-1, etag=None)
Iterate over the statuses for a specific SHA.
Warning
Deprecated in v1.0. Also deprecated upstream https://developer.github.com/v3/repos/statuses/
- Parameters:
sha (str) – SHA of the commit to list the statuses of
number (int) – (optional), return up to number statuses. Default: -1 returns all available statuses.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of statuses
- Return type:
- subscribe()
Subscribe the user to this repository’s notifications.
New in version 1.0.
This replaces
Repository#set_subscription
- Returns:
the new repository subscription
- Return type:
- subscribers(number=-1, etag=None)
Iterate over users subscribed to this repository.
- Parameters:
number (int) – (optional), number of subscribers to return. Default: -1 returns all subscribers available
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of users subscribed to this repository
- Return type:
- subscription()
Return subscription for this Repository.
- Returns:
the user’s subscription to this repository
- Return type:
- tag(sha)
Get an annotated tag.
http://learn.github.com/p/tagging.html
- Parameters:
sha (str) – (required), sha of the object for this tag
- Returns:
the annotated tag
- Return type:
- tags(number=-1, etag=None)
Iterate over tags on this repository.
- Parameters:
number (int) – (optional), return up to at most number tags. Default: -1 returns all available tags.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of tags with GitHub repository specific information
- Return type:
- teams(number=-1, etag=None)
Iterate over teams with access to this repository.
- Parameters:
number (int) – (optional), return up to number Teams. Default: -1 returns all Teams.
etag (str) – (optional), ETag from a previous request to the same endpoint
- Returns:
generator of teams
- Return type:
- topics()
Get the topics of this repository.
- Returns:
this repository’s topics
- Return type:
Topics
- tree(sha, recursive=False)
Get a tree.
- Parameters:
sha (str) – (required), sha of the object for this tree
recursive (bool) – (optional), whether to fetch the tree recursively
- Returns:
the tree
- Return type:
- unignore()
Unignore notifications from this repository for the user.
New in version 1.3.
This replaces
Repository#set_subscription
.- Returns:
the new repository subscription
- Return type:
:class:~github3.notifications.RepositorySubscription`
- unsubscribe()
Unsubscribe the user to this repository’s notifications.
New in version 1.3.
This replaces
Repository#set_subscription
- Returns:
the new repository subscription
- Return type:
- views(per='day')
Get the total number of repository views and breakdown per day or week for the last 14 days.
New in version 1.4.0.
See also: https://developer.github.com/v3/repos/traffic/
- Parameters:
per (str) – (optional), (‘day’, ‘week’), views reporting period. Default ‘day’ will return views per day for the last 14 days.
- Returns:
views data
- Return type:
ViewsStats
- Raises:
ValueError if per is not a valid choice
- weekly_commit_count()
Retrieve the total commit counts.
Note
All statistics methods may return a 202. If github3.py receives a 202 in this case, it will return an emtpy dictionary. You should give the API a moment to compose the data and then re -request it via this method.
..versionadded:: 0.7
The dictionary returned has two entries:
all
andowner
. Each has a fifty-two element long list of commit counts. (Note:all
includes the owner.)d['all'][0]
will be the oldest week,d['all'][51]
will be the most recent.- Returns:
the commit count as a dictionary
- Return type:
dict
- class github3.repos.repo.StarredRepository(json, session: GitHubSession)
This object represents the data returned about a user’s starred repos.
GitHub used to send back the
starred_at
attribute on Repositories but then changed the structure to a new object that separates that from the Repository representation. This consolidates the two.Attributes:
- starred_at
A parsed
datetime
object representing the date a the repository was starred.
- repository
The
Repository
that was starred by the user.
See also: https://developer.github.com/v3/activity/starring/#list-repositories-being-starred
- 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
- 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
.
- new_session()
Generate a new session.
- Returns:
A brand new session
- Return type:
- 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
- class github3.repos.contents.Contents(json, session: GitHubSession)
A representation of file contents returned via the API.
See also: http://developer.github.com/v3/repos/contents/
This object has the following attributes:
- content
The body of the file. If this is present, it may be base64 encoded.
- encoding
The encoding used on the
content
when returning the data from the API, e.g.,base64
. Ifcontent
is not present this will not be present either.
- decoded
Note
This is a computed attribute which isn’t returned by the API.
Changed in version 0.5.2.
Decoded content of the file as a bytes object. If we try to decode to character set for you, we might encounter an exception which will prevent the object from being created. On python2 this is the same as a string, but on python3 you should call the decode method with the character set you wish to use, e.g.,
content.decoded.decode('utf-8')
.
- git_url
The URL for the Git API pertaining to this file.
- html_url
The URL to open this file in a browser.
- links
A dictionary of links returned about the contents and related resources.
- name
The name of the file.
- path
The path to this file.
- sha
The SHA1 of the contents of this file.
- size
The size of file in bytes.
- submodule_git_url
The URL of the git submodule (if this is a git submodule).
- target
If the file is a symlink, this will be present and provides the type of file that the symlink points to.
- type
Type of content, e.g.,
'file'
,'symlink'
, or'submodule'
.
- delete(message, branch=None, committer=None, author=None)
Delete this file.
- Parameters:
message (str) – (required), commit message to describe the removal
branch (str) – (optional), branch where the file exists. Defaults to the default branch of the repository.
committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email.
author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
- Returns:
dictionary of new content and associated commit
- Return type:
- update(message, content, branch=None, committer=None, author=None)
Update this file.
- Parameters:
message (str) – (required), commit message to describe the update
content (str) – (required), content to update the file with
branch (str) – (optional), branch where the file exists. Defaults to the default branch of the repository.
committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email.
author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
- Returns:
dictionary containing the updated contents object and the commit in which it was changed.
- Return type:
- class github3.repos.hook.Hook(json, session: GitHubSession)
The representation of a hook on a repository.
See also: http://developer.github.com/v3/repos/hooks/
This object has the following attributes:
- active
A boolean attribute describing whether the hook is active or not.
- config
A dictionary containing the configuration for this hook.
- created_at
A
datetime
object representing the date and time when this hook was created.
- events
The list of events which trigger this hook.
- id
The unique identifier for this hook.
- name
The name provided to this hook.
- updated_at
A
datetime
object representing the date and time when this hook was updated.
- delete()
Delete this hook.
- Returns:
True if successful, False otherwise
- Return type:
bool
- edit(config={}, events=[], add_events=[], rm_events=[], active=True)
Edit this hook.
- Parameters:
config (dict) – (optional), key-value pairs of settings for this hook
events (list) – (optional), which events should this be triggered for
add_events (list) – (optional), events to be added to the list of events that this hook triggers for
rm_events (list) – (optional), events to be removed from the list of events that this hook triggers for
active (bool) – (optional), should this event be active
- Returns:
True if successful, False otherwise
- Return type:
bool
- ping()
Ping this hook.
- Returns:
True if successful, False otherwise
- Return type:
bool
- test()
Test this hook.
- Returns:
True if successful, False otherwise
- Return type:
bool
- class github3.repos.issue_import.ImportedIssue(json, session: GitHubSession)
Represents an issue imported via the unofficial API.
See also: https://gist.github.com/jonmagic/5282384165e0f86ef105
This object has the following attributes:
- created_at
A
datetime
object representing the date and time when this imported issue was created.
- id
The globally unique identifier for this imported issue.
- import_issues_url
The URL used to import more issues via the API.
- repository_url
The URL used to retrieve the repository via the API.
- status
The status of this imported issue.
- updated_at
A
datetime
object representing te date and time when this imported issue was last updated.
Release Objects
- class github3.repos.release.Asset(json, session: GitHubSession)
Representation of an asset in a release.
See also
- List Assets,
assets()
Documentation around listing assets of a release
- Upload Assets,
upload_asset()
Documentation around uploading assets to a release
- Get a Single Asset,
asset()
Documentation around retrieving an asset
- Edit an Asset,
edit()
Documentation around editing an asset
- Delete an Asset,
delete()
Documentation around deleting an asset
This object has the following attributes:
- browser_download_url
The user-friendly URL to download this asset via a browser.
- content_type
The Content-Type provided by the uploader when this asset was created.
- created_at
A
datetime
object representing the date and time when this asset was created.
- download_count
The number of times this asset has been downloaded.
- download_url
The URL to retrieve this uploaded asset via the API, e.g., tarball, zipball, etc.
- id
The unique identifier of this asset.
- label
The short description of this asset.
- name
The name provided to this asset.
- size
The file size of this asset.
- state
The state of this asset, e.g.,
'uploaded'
.
- updated_at
A
datetime
object representing the date and time when this asset was most recently updated.
- delete()
Delete this asset if the user has push access.
- Returns:
True if successful; False if not successful
- Return type:
bool
- download(path='')
Download the data for this asset.
- Parameters:
path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. It can take a file-like object as well
- Returns:
name of the file, if successful otherwise
None
- Return type:
str
- edit(name, label=None)
Edit this asset.
- Parameters:
name (str) – (required), The file name of the asset
label (str) – (optional), An alternate description of the asset
- Returns:
True if successful, False otherwise
- Return type:
bool
- List Assets,
- class github3.repos.release.Release(json, session: GitHubSession)
Representation of a GitHub release.
It holds the information GitHub returns about a release from a
Repository
.Please see GitHub’s Releases Documentation for more information.
This object has the following attributes:
- assets_url
The URL to retrieve the assets from the API.
- body
The description of this release as written by the release creator.
- created_at
A
datetime
object representing the date and time when this release was created.
- draft
A boolean attribute describing whether this release is a draft.
- html_url
The URL to view this release in a browser.
- id
The unique identifier of this release.
- prerelease
A boolean attribute indicating whether the release is a pre-release.
- published_at
A
datetime
object representing the date and time when this release was publisehd.
- tag_name
The name of the tag associated with this release.
- tarball_url
The URL to retrieve a GitHub generated tarball for this release from the API.
- target_commitish
The reference (usually a commit) that is targetted by this release.
- upload_urlt
A
URITemplate
object that expands to form the URL to upload assets to.
- zipball_url
The URL to retrieve a GitHub generated zipball for this release from the API.
- archive(format, path='')
Get the tarball or zipball archive for this release.
- Parameters:
format (str) – (required), accepted values: (‘tarball’, ‘zipball’)
path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. It can take a file-like object as well
- Returns:
True if successful, False otherwise
- Return type:
bool
- asset(asset_id)
Retrieve the asset from this release with
asset_id
.- Parameters:
asset_id (int) – ID of the Asset to retrieve
- Returns:
the specified asset, if it exists
- Return type:
- assets(number=-1, etag=None)
Iterate over the assets available for this release.
- Parameters:
number (int) – (optional), Number of assets to return
etag (str) – (optional), last ETag header sent
- Returns:
generator of asset objects
- Return type:
- delete()
Delete this release.
Only users with push access to the repository can delete a release.
- Returns:
True if successful; False if not successful
- Return type:
bool
- edit(tag_name=None, target_commitish=None, name=None, body=None, draft=None, prerelease=None)
Edit this release.
Only users with push access to the repository can edit a release.
If the edit is successful, this object will update itself.
- Parameters:
tag_name (str) – (optional), Name of the tag to use
target_commitish (str) – (optional), The “commitish” value that determines where the Git tag is created from. Defaults to the repository’s default branch.
name (str) – (optional), Name of the release
body (str) – (optional), Description of the release
draft (boolean) – (optional), True => Release is a draft
prerelease (boolean) – (optional), True => Release is a prerelease
- Returns:
True if successful; False if not successful
- Return type:
bool
- upload_asset(content_type, name, asset, label=None)
Upload an asset to this release.
Note
All parameters are required.
- Parameters:
content_type (str) – The content type of the asset. Wikipedia has a list of common media types
name (str) – The name of the file
asset – The file or bytes object to upload.
label – (optional), An alternate short description of the asset.
- Returns:
the created asset
- Return type:
Pages Objects
- class github3.repos.pages.PagesInfo(json, session: GitHubSession)
Representation of the information about a GitHub pages website.
- cname
The cname in use for the pages site, if one is set.
- custom_404
A boolean attribute indicating whether the user configured a custom 404 page for this site.
- status
The current status of the pages site, e.g.,
built
.
- class github3.repos.pages.PagesBuild(json, session: GitHubSession)
Representation of a single build of a GitHub pages website.
- commit
The SHA of the commit that triggered this build.
- created_at
A
datetime
object representing the date and time when this build was created.
- duration
The time it spent processing this build.
- error
If this build errored, a dictionary containing the error message and details about the error.
- status
The current statues of the build, e.g.,
building
.
- updated_at
A
datetime
object representing the date and time when this build was last updated.
Deployment and Status Objects
- class github3.repos.deployment.Deployment(json, session: GitHubSession)
Representation of a deployment of a repository at a point in time.
See also: https://developer.github.com/v3/repos/deployments/
This object has the following attributes:
- created_at
A
datetime
representing the date and time when this deployment was created.
- environment
The environment targeted for this deployment, e.g.,
'production'
,'staging'
.
- id
The unique identifier of this deployment.
- payload
The JSON payload string sent as part to trigger this deployment.
- ref
The reference used to create this deployment, e.g.,
'deploy-20140526'
.
- sha
The SHA1 of the branch on GitHub when it was deployed.
- statuses_url
The URL to retrieve the statuses of this deployment from the API.
- updated_at
A
datetime
object representing the date and time when this deployment was most recently updated.
- create_status(state, target_url=None, description=None)
Create a new deployment status for this deployment.
- Parameters:
state (str) – (required), The state of the status. Can be one of
pending
,success
,error
,inactive
,in_progress
,queued
, orfailure
.target_url (str) – The target URL to associate with this status. This URL should contain output to keep the user updated while the task is running or serve as historical information for what happened in the deployment. Default: ‘’.
description (str) – A short description of the status. Default: ‘’.
- Returns:
the incomplete deployment status
- Return type:
- statuses(number=-1, etag=None)
Iterate over the deployment statuses for this deployment.
- Parameters:
number (int) – (optional), the number of statuses to return. Default: -1, returns all statuses.
etag (str) – (optional), the ETag header value from the last time you iterated over the statuses.
- Returns:
generator of the statuses of this deployment
- Return type:
- class github3.repos.deployment.DeploymentStatus(json, session: GitHubSession)
Representation of the status of a deployment of a repository.
See also https://developer.github.com/v3/repos/deployments/#get-a-single-deployment-status
This object has the following attributes:
- created_at
A
datetime
representing the date and time when this deployment status was created.
- deployment_url
The URL to retrieve the information about the deployment from the API.
- id
The unique identifier of this deployment.
- state
The state of the deployment, e.g.,
'success'
.
- target_url
The URL to associate with this status. This should link to the output of the deployment.
- class github3.repos.status.ShortStatus(json, session: GitHubSession)
Representation of a short status on a repository.
New in version 1.0.0.
This is the representation found in a
CombinedStatus
object.See also: http://developer.github.com/v3/repos/statuses/
This object has the following attributes:
- context
This is a string that explains the context of this status object. For example,
'continuous-integration/travis-ci/pr'
.
- created_at
A
datetime
object representing the date and time when this status was created.
- description
A short description of the status.
- id
The unique identifier of this status object.
- state
The state of this status, e.g.,
'success'
,'pending'
,'failure'
.
- target_url
The URL to retrieve more information about this status.
- updated_at
A
datetime
object representing the date and time when this status was most recently updated.
- class github3.repos.status.CombinedStatus(json, session: GitHubSession)
A representation of the combined statuses in a repository.
See also: http://developer.github.com/v3/repos/statuses/
This object has the following attributes:
- commit_url
The URL of the commit this combined status is present on.
- repository
A
ShortRepository
representing the repository on which this combined status exists.
- sha
The SHA1 of the commit this status exists on.
- state
The state of the combined status, e.g.,
'success'
,'pending'
,'failure'
.
- statuses
The list of
ShortStatus
objects representing the individual statuses that is combined in this object.
- total_count
The total number of sub-statuses.
- class github3.repos.status.Status(json, session: GitHubSession)
Representation of a full status on a repository.
See also: http://developer.github.com/v3/repos/statuses/
This object has the same attributes as a
ShortStatus
as well as the following attributes:
Contributor Statistics Objects
- class github3.repos.stats.ContributorStats(json, session: GitHubSession)
Representation of a user’s contributor statistics to a repository.
See also http://developer.github.com/v3/repos/statistics/
This object has the following attributes:
- weeks
A list of dictionaries containing weekly statistical data.
- alternate_weeks
-
A list of dictionaries that provide an easier to remember set of keys as well as a
datetime
object representing the start of the week. The dictionary looks vaguely like:{ 'start of week': datetime(2013, 5, 5, 5, 0, tzinfo=tzutc()) 'additions': 100, 'deletions': 150, 'commits': 5, }
Comment Objects
More information about these classes can be found in the official documentation about comments.
The representation of an abridged comment on an object in a repo.
This object has the following attributes:
The affiliation the author of this comment has with the repository.
The Markdown formatted text of this comment.
The SHA1 associated with this comment.
A
datetime
object representing the date and time when this comment was created.The URL to view this comment in a browser.
The unique identifier of this comment.
The line number where the comment is located.
The path to the file where this comment was made.
The position in the diff where the comment was left.
A
datetime
object representing the date and time when this comment was most recently updated.A
ShortUser
representing the author of this comment.The representation of the full comment on an object in a repository.
This object has the same attributes as a
ShortComment
as well as the following:The HTML formatted text of this comment.
The plain-text formatted text of this comment.