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)¶ 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)¶ Add
username
as a collaborator to a repository.Parameters: username (str or User
) – (required), username of the userReturns: 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: Asset
-
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:
-
blob
(sha)¶ Get the blob indicated by
sha
.Parameters: sha (str) – (required), sha of the blob Returns: the git blob Return type: Blob
-
branch
(name)¶ Get the branch
name
of this repository.Parameters: name (str) – (required), branch name Returns: the branch Return type: Branch
-
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:
-
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: RepoCommit
-
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: RepoComment
-
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 comments to return. Default: -1 returns all comments
- 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 (on Python 3, unicode on Python 2)
-
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_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: Repository
-
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)¶ 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)
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: Project
-
create_pull
(title, base, head, body=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
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: - ref (str) – (required), fully qualified name of the reference,
e.g.
-
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 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: Deployment
-
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: Commit
-
hook
(hook_id)¶ Get a single hook.
Parameters: hook_id (int) – (required), id of the hook Returns: the hook Return type: Hook
-
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 timestamp - assignee (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: ImportedIssue
-
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:
-
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 checkReturns: bool
-
is_collaborator
(username)¶ Check to see if
username
is a collaborator on this repository.Parameters: username (str or User
) – (required), login for the userReturns: 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
-
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:27Z - number (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: Key
-
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: Label
-
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: PagesBuild
-
latest_release
()¶ Get the latest release.
Draft releases and prereleases are not returned by this endpoint.
Returns: the release Return type: Release
-
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: Milestone
-
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: GitHubSession
-
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:27Z - etag (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: PagesInfo
-
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: Project
-
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: Project
-
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: PullRequest
-
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:
-
ratelimit_remaining
¶ Number of requests before GitHub imposes a ratelimit.
Returns: int
-
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: Reference
-
refresh
(conditional=False)¶ 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
-
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: Release
-
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 collaboratorReturns: 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
Parameters: - subscribed (bool) – (required), determines if notifications should be received from this repository.
- ignored (bool) – (required), determines if notifications should be ignored from this repository.
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: RepositorySubscription
-
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: Tag
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)¶ Get a tree.
Parameters: sha (str) – (required), sha of the object for this tree Returns: the tree Return type: Tree
-
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)¶ 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()
.
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()
.
-
owner
¶ The owner of the repository, e.g.,
sigmavirus24
.
-
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.
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)¶ Add
username
as a collaborator to a repository.Parameters: username (str or User
) – (required), username of the userReturns: 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: Asset
-
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:
-
blob
(sha)¶ Get the blob indicated by
sha
.Parameters: sha (str) – (required), sha of the blob Returns: the git blob Return type: Blob
-
branch
(name)¶ Get the branch
name
of this repository.Parameters: name (str) – (required), branch name Returns: the branch Return type: Branch
-
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:
-
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: RepoCommit
-
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: RepoComment
-
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 comments to return. Default: -1 returns all comments
- 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 (on Python 3, unicode on Python 2)
-
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_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: Repository
-
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)¶ 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)
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: Project
-
create_pull
(title, base, head, body=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
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: - ref (str) – (required), fully qualified name of the reference,
e.g.
-
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 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: Deployment
-
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: Commit
-
hook
(hook_id)¶ Get a single hook.
Parameters: hook_id (int) – (required), id of the hook Returns: the hook Return type: Hook
-
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 timestamp - assignee (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: ImportedIssue
-
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:
-
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 checkReturns: bool
-
is_collaborator
(username)¶ Check to see if
username
is a collaborator on this repository.Parameters: username (str or User
) – (required), login for the userReturns: 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
-
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:27Z - number (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: Key
-
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: Label
-
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: PagesBuild
-
latest_release
()¶ Get the latest release.
Draft releases and prereleases are not returned by this endpoint.
Returns: the release Return type: Release
-
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: Milestone
-
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: GitHubSession
-
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:27Z - etag (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: PagesInfo
-
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: Project
-
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: Project
-
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: PullRequest
-
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:
-
ratelimit_remaining
¶ Number of requests before GitHub imposes a ratelimit.
Returns: int
-
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: Reference
-
refresh
(conditional=False)¶ 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
-
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: Release
-
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 collaboratorReturns: 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
Parameters: - subscribed (bool) – (required), determines if notifications should be received from this repository.
- ignored (bool) – (required), determines if notifications should be ignored from this repository.
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: RepositorySubscription
-
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: Tag
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)¶ Get a tree.
Parameters: sha (str) – (required), sha of the object for this tree Returns: the tree Return type: Tree
-
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)¶ 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: GitHubSession
-
ratelimit_remaining
¶ Number of requests before GitHub imposes a ratelimit.
Returns: int
-
refresh
(conditional=False)¶ 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)¶ 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)¶ 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)¶ 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)¶ 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)¶ 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.
A
ShortUser
representing the creator of this release.
-
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: Asset
-
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)¶ 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)¶ 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.
-
Comment Objects¶
More information about these classes can be found in the official documentation about comments.
-
class
github3.repos.comment.
ShortComment
(json, session)¶ 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.
-
body
¶ The Markdown formatted text of this comment.
-
commit_id
¶ The SHA1 associated with this comment.
-
created_at
¶ A
datetime
object representing the date and time when this comment was created.
-
html_url
¶ The URL to view this comment in a browser.
-
id
¶ The unique identifier of this comment.
-
line
¶ The line number where the comment is located.
-
path
¶ The path to the file where this comment was made.
-
position
¶ The position in the diff where the comment was left.
-
updated_at
¶ A
datetime
object representing the date and time when this comment was most recently updated.
-
class
github3.repos.comment.
RepoComment
(json, session)¶ 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:-
body_html
¶ The HTML formatted text of this comment.
-
body_text
¶ The plain-text formatted text of this comment.
-
Deployment and Status Objects¶
-
class
github3.repos.deployment.
Deployment
(json, session)¶ 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
, 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: - state (str) – (required), The state of the status. Can be one of
-
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)¶ 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)¶ 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)¶ 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)¶ 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)¶ 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:
A
ShortUser
representing the contributor whose stats this object represents.
-
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, }