Repository

This part of the documentation covers:

None of these objects should be instantiated directly by the user (developer). These are here for reference only.

When listing repositories in any context, GitHub refuses to return a number of attributes, e.g., source and parent. If you require these, call the refresh method on the repository object to make a second call to the API and retrieve those attributes.

More information for about this class can be found in the official documentation and in various other sections of the GitHub documentation.

Repository Objects

class github3.repos.repo.Repository(repo, session=None)

The Repository object. It represents how GitHub sends information about repositories.

Two repository instances can be checked like so:

r1 == r2
r1 != r2

And is equivalent to:

r1.id == r2.id
r1.id != r2.id

See also: http://developer.github.com/v3/repos/

add_collaborator(login)

Add login as a collaborator to a repository.

Parameters:login (str) – (required), login of the user
Returns:bool – True if successful, False otherwise
archive(format, path=u'', ref=u'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:

bool – True if successful, False otherwise

archive_urlt = None

Archive URL Template. Expand with archive_format and ref

asset(id)

Returns a single Asset.

Parameters:id (int) – (required), id of the asset
Returns:Asset
assignees_urlt = None

Assignees URL Template. Expand with user

blob(sha)

Get the blob indicated by sha.

Parameters:sha (str) – (required), sha of the blob
Returns:Blob if successful, otherwise None
blobs_urlt = None

Blobs URL Template. Expand with sha

branch(name)

Get the branch name of this repository.

Parameters:name (str) – (required), branch name
Returns:Branch
branches_urlt = None

Branches URL Template. Expand with branch

clone_url = None

URL used to clone via HTTPS.

comments_urlt = None

Comments URL Template. Expand with number

commit(sha)

Get a single (repo) commit. See git_commit() for the Git Data Commit.

Parameters:sha (str) – (required), sha of the commit
Returns:RepoCommit if successful, otherwise None
commit_comment(comment_id)

Get a single commit comment.

Parameters:comment_id (int) – (required), id of the comment used by GitHub
Returns:RepoComment if successful, otherwise None
commits_urlt = None

Commits URL Template. Expand with sha

compare_commits(base, head)

Compare two commits.

Parameters:
  • base (str) – (required), base for the comparison
  • head (str) – (required), compare this against base
Returns:

Comparison if successful, else None

compare_urlt = None

Comparison URL Template. Expand with base and head

contents(path, ref=None)

Get the contents of the file pointed to by path.

If the path provided is actually a directory, you will receive a dictionary back of the form:

{
    'filename.md': Contents(),  # Where Contents an instance
    'github.py': Contents(),
}
Parameters:
  • path (str) – (required), path to file, e.g. github3/repo.py
  • ref (str) – (optional), the string name of a commit/branch/tag. Default: master
Returns:

Contents or dict if successful, else None

contents_urlt = None

Contents URL Template. Expand with path

contributors_url = None

Contributors url (not a template)

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

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:

RepoComment if successful, otherwise None

create_commit(message, tree, parents, author={}, committer={})

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:

Commit if successful, else None

create_deployment(ref, force=False, payload=u'', auto_merge=False, description=u'', environment=None)

Create a deployment.

Parameters:
  • ref (str) – (required), The ref to deploy. This can be a branch, tag, or sha.
  • force (bool) – Optional parameter to bypass any ahead/behind checks or commit status checks. Default: False
  • 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:

Deployment

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:

{ ‘content’: Contents:, ‘commit’: Commit}

create_fork(organization=None)

Create a fork of this repository.

Parameters:organization (str) – (required), login for organization to create the fork under
Returns:Repository if successful, else None
create_hook(name, config, events=[u'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:

Hook if successful, otherwise None

create_issue(title, body=None, assignee=None, milestone=None, labels=None)

Creates 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 a Milestone object, m.number is what you pass here.)
  • labels (list of strings) – (optional), labels to apply to this issue
Returns:

Issue if successful, otherwise None

create_key(title, key)

Create a deploy key.

Parameters:
  • title (str) – (required), title of key
  • key (str) – (required), key text
Returns:

Key if successful, else None

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:

Label if successful, else None

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:

Milestone if successful, otherwise None

create_pull(title, base, head, body=None)

Create a pull request of head onto base 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:

PullRequest if successful, else None

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:

PullRequest if successful, else None

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 with refs and contain at least two slashes, GitHub’s API will reject it.
  • sha (str) – (required), SHA1 value to set the reference to
Returns:

Reference if successful else None

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:

Release

create_status(sha, state, target_url=u'', description=u'')

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
create_tag(tag, message, sha, obj_type, tagger, lightweight=False)

Create a tag in this repository.

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 lightweight == False: Tag if successful, else None. If lightweight == True: Reference

create_tree(tree, base_tree=u'')

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:

Tree if successful, else None

created_at = None

datetime object representing when the Repository was created.

default_branch = None

default branch for the repository

delete()

Delete this repository.

Returns:bool – True if successful, False otherwise
delete_file(path, message, sha, branch=None, committer=None, author=None)

Delete the file located at path.

This is part of the Contents CrUD (Create Update Delete) API. See http://developer.github.com/v3/repos/contents/#delete-a-file for more information.

Parameters:
  • path (str) – (required), path to the file being removed
  • message (str) – (required), commit message for the deletion
  • sha (str) – (required), blob sha of the file being removed
  • branch (str) – (optional), if not provided, uses the repository’s default branch
  • 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:

Commit if successful

delete_key(key_id)

Delete the key with the specified id from your deploy keys list.

Returns:bool – True if successful, False otherwise
delete_subscription()

Delete the user’s subscription to this repository.

Returns:bool
description = None

Description of the repository.

download_url = None

Downloads url (not a template)

edit(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, default_branch=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. If False, make the repository public. API default: None - leave value unchanged.
  • has_issues (bool) – (optional), If True, enable issues for this repository. If False, disable issues for this repository. API default: None - leave value unchanged.
  • has_wiki (bool) – (optional), If True, enable the wiki for this repository. If False, disable the wiki for this repository. API default: None - leave value unchanged.
  • has_downloads (bool) – (optional), If True, enable downloads for this repository. If False, 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.
Returns:

bool – True if successful, False otherwise

events_url = None

Events url (not a template)

fork = None

Is this repository a fork?

forks = None

The number of forks made of this repository. DEPRECATED

forks_count = None

The number of forks of this repository.

from_json(json)

Return an instance of cls formed from json.

full_name = None

Full name as login/name

git_commit(sha)

Get a single (git) commit.

Parameters:sha (str) – (required), sha of the commit
Returns:Commit if successful, otherwise None
git_commits_urlt = None

Git commits URL Template. Expand with sha

git_refs_urlt = None

Git refs URL Template. Expand with sha

git_tags_urlt = None

Git tags URL Template. Expand with sha

git_url = None

Plain git url for an anonymous clone.

has_downloads = None

Whether or not this repository has downloads enabled

has_issues = None

Whether or not this repository has an issue tracker

has_wiki = None

Whether or not this repository has the wiki enabled

homepage = None

URL of the home page for the project.

hook(id_num)

Get a single hook.

Parameters:id_num (int) – (required), id of the hook
Returns:Hook if successful, otherwise None
hooks_url = None

Hooks url (not a template)

html_url = None

URL of the project at GitHub.

id = None

Unique id of the repository.

is_assignee(login)

Check if the user is a possible assignee for an issue on this repository.

Returns:bool
is_collaborator(login)

Check to see if login is a collaborator on this repository.

Parameters:login (str) – (required), login for the user
Returns:bool – True if successful, False otherwise
issue(number)

Get the issue specified by number.

Parameters:number (int) – (required), number of the issue on this repository
Returns:Issue if successful, otherwise None
issue_comment_urlt = None

Issue comment URL Template. Expand with number

issue_events_urlt = None

Issue events URL Template. Expand with number

issues_urlt = None

Issues URL Template. Expand with number

iter_assignees(number=-1, etag=None)

Iterate over all available 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

iter_branches(number=-1, etag=None)

Iterate over the branches in this repository.

Parameters:
  • number (int) – (optional), number of branches to return. Default: -1 returns all branches
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Branches

iter_code_frequency(number=-1, etag=None)

Iterate over the code frequency per week.

Returns a weekly aggregate of the number of additions and deletions pushed to this repository.

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]

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.

New in version 0.7.

iter_collaborators(number=-1, etag=None)

Iterate over the collaborators of this repository.

Parameters:
  • number (int) – (optional), number of collaborators to return. Default: -1 returns all collaborators
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Users

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

iter_comments_on_commit(sha, number=1, etag=None)

Iterate over comments for a single commit.

Parameters:
  • sha (str) – (required), sha of the commit to list comments on
  • 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 RepoComments

iter_commit_activity(number=-1, etag=None)

Iterate over last year of commit activity by week.

See: http://developer.github.com/v3/repos/statistics/

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

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.

New in version 0.7.

iter_commits(sha=None, path=None, author=None, number=-1, etag=None, since=None, until=None)

Iterate over commits in this repository.

Parameters:
  • sha (str) – (optional), sha or branch to start listing commits from
  • path (str) – (optional), commits containing this path will be listed
  • author (str) – (optional), GitHub login, real name, or email to filter commits by (using commit author)
  • number (int) – (optional), number of commits to return. Default: -1 returns all commits
  • etag (str) – (optional), ETag from a previous request to the same endpoint
  • since (datetime or string) – (optional), Only commits after this date will be returned. This can be a datetime or an ISO8601 formatted date string.
  • until (datetime or string) – (optional), Only commits before this date will be returned. This can be a datetime or an ISO8601 formatted date string.
Returns:

generator of RepoCommits

iter_contributor_statistics(number=-1, etag=None)

Iterate over the contributors list.

See also: http://developer.github.com/v3/repos/statistics/

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 ContributorStats

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.

New in version 0.7.

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

iter_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

iter_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

iter_forks(sort=u'', number=-1, etag=None)

Iterate over forks of this repository.

Parameters:
  • sort (str) – (optional), accepted values: (‘newest’, ‘oldest’, ‘watchers’), 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 Repository

iter_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

iter_issue_events(number=-1, etag=None)

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

iter_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 string) – (optional), Only issues after this date will be returned. This can be a datetime or an ISO8601 formatted date string, e.g., 2012-05-20T23:10:27Z
  • number (int) – (optional), Number of issues to return. By default all issues are returned
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Issues

iter_keys(number=-1, etag=None)

Iterates 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

iter_labels(number=-1, etag=None)

Iterates 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

iter_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

iter_milestones(state=None, sort=None, direction=None, number=-1, etag=None)

Iterates 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

iter_network_events(number=-1, etag=None)

Iterates 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

iter_notifications(all=False, participating=False, since=None, number=-1, etag=None)

Iterates 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 string) – (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 Thread

iter_pages_builds(number=-1, etag=None)

Iterate over pages builds of this repository.

Returns:generator of PagesBuild
iter_pulls(state=None, head=None, base=None, sort=u'created', direction=u'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 PullRequests

iter_refs(subspace=u'', number=-1, etag=None)

Iterates 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

iter_releases(number=-1, etag=None)

Iterates 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

iter_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

iter_statuses(sha, number=-1, etag=None)

Iterates over the statuses for a specific SHA.

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 Status

iter_subscribers(number=-1, etag=None)

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

iter_tags(number=-1, etag=None)

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

iter_teams(number=-1, etag=None)

Iterates 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

key(id_num)

Get the specified deploy key.

Parameters:id_num (int) – (required), id of the key
Returns:Key if successful, else None
label(name)

Get the label specified by name

Parameters:name (str) – (required), name of the label
Returns:Label if successful, else None
labels_urlt = None

Labels URL Template. Expand with name

language = None

Language property.

languages_url = None

Languages url (not a template)

latest_pages_build()

Get the build information for the most recent Pages build.

Returns:PagesBuild
mark_notifications(last_read=u'')

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:bool
master_branch = None

master (default) branch for the repository

merge(base, head, message=u'')

Perform a merge from head into base.

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:

RepoCommit

merges_url = None

Merges url (not a template)

milestone(number)

Get the milestone indicated by number.

Parameters:number (int) – (required), unique id number of the milestone
Returns:Milestone
milestones_urlt = None

Milestones URL Template. Expand with number

mirror_url = None

Mirror property.

name = None

Name of the repository.

notifications_urlt = None

Notifications URL Template. Expand with since, all, participating

open_issues = None

Number of open issues on the repository. DEPRECATED

open_issues_count = None

Number of open issues on the repository

owner = None

User object representing the repository owner.

pages()

Get information about this repository’s pages site.

Returns:PagesInfo
parent = None

Parent of this fork, if it exists Repository

private = None

Is this repository private?

pull_request(number)

Get the pull request indicated by number.

Parameters:number (int) – (required), number of the pull request.
Returns:PullRequest
pulls_urlt = None

Pull Requests URL Template. Expand with number

pushed_at = None

datetime object representing the last time commits were pushed to the repository.

ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
readme()

Get the README for this repository.

Returns:Contents
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:Reference
refresh(conditional=False)

Re-retrieve the information for this object and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

release(id)

Get a single release.

Parameters:id (int) – (required), id of release
Returns:Release
remove_collaborator(login)

Remove collaborator login from the repository.

Parameters:login (str) – (required), login name of the collaborator
Returns:bool
set_subscription(subscribed, ignored)

Set the user’s subscription for this repository

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:

Subscription

size = None

Size of the repository.

source = None

Parent of this fork, if it exists Repository

ssh_url = None

URL to clone the repository via SSH.

stargazers = None

Number of users who starred the repository

stargazers_url = None

Stargazers url (not a template)

statuses_urlt = None

Statuses URL Template. Expand with sha

subscribers_url = None

Subscribers url (not a template)

subscription()

Return subscription for this Repository.

Returns:Subscription
subscription_url = None

Subscription url (not a template)

svn_url = None

If it exists, url to clone the repository via SVN.

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:Tag
tags_url = None

Tags url (not a template)

teams_url = None

Teams url (not a template)

to_json()

Return the json representing this object.

tree(sha)

Get a tree.

Parameters:sha (str) – (required), sha of the object for this tree
Returns:Tree
trees_urlt = None

Trres URL Template. Expand with sha

update_file(path, message, content, sha, branch=None, author=None, committer=None)

Update the file path with content.

This is part of the Contents CrUD (Create Update Delete) API. See http://developer.github.com/v3/repos/contents/#update-a-file for more information.

Parameters:
  • path (str) – (required), path to the file being updated
  • message (str) – (required), commit message
  • content (str) – (required), updated contents of the file
  • sha (str) – (required), blob sha of the file being updated
  • branch (str) – (optional), uses the default branch on the repository if not provided.
  • author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
Returns:

{‘commit’: Commit, ‘content’: Contents}

update_label(name, color, new_name=u'')

Update the label name.

Parameters:
  • name (str) – (required), name of the label
  • color (str) – (required), color code
  • new_name (str) – (optional), new name of the label
Returns:

bool

updated_at = None

datetime object representing the last time the repository was updated.

watchers = None

Number of users watching the repository.

weekly_commit_count()

Returns the total commit counts.

The dictionary returned has two entries: all and owner. 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:dict

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


class github3.repos.branch.Branch(branch, session=None)

The Branch object. It holds the information GitHub returns about a branch on a Repository.

commit = None

Returns the branch’s RepoCommit or None.

Returns ‘_links’ attribute.

name = None

Name of the branch.


class github3.repos.contents.Contents(content, session=None)

The Contents object. It holds the information concerning any content in a repository requested via the API.

Two content instances can be checked like so:

c1 == c2
c1 != c2

And is equivalent to:

c1.sha == c2.sha
c1.sha != c2.sha

See also: http://developer.github.com/v3/repos/contents/

content = None

Base64-encoded content of the file.

decoded = None

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'). .. versionchanged:: 0.5.2

delete(message, committer=None, author=None)

Delete this file.

Parameters:
  • message (str) – (required), commit message to describe the removal
  • 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:

Commit

encoding = None

Returns encoding used on the content.

git_url = None

URL for the git api pertaining to the README

html_url = None

URL of the README on github.com

Dictionary of links

name = None

Name of the content.

path = None

Path to the content.

sha = None

SHA string.

size = None

Size of the content

submodule_git_url = None

git:// URL of the content if it is a submodule

target = None

Target will only be set of type is a symlink. This is what the link points to

type = None

Type of content. (‘file’, ‘symlink’, ‘submodule’)

update(message, content, 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
  • 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:

Commit


class github3.repos.deployment.Deployment(deployment, session=None)
create_status(state, target_url=u'', description=u'')

Create a new deployment status for this deployment.

Parameters:
  • state (str) – (required), The state of the status. Can be one of pending, success, error, or failure.
  • 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:

partial DeploymentStatus

created_at = None

Date the Deployment was created

creator = None

User object representing the creator of the deployment

description = None

Description of the deployment

environment = None

Target for the deployment, e.g., ‘production’, ‘staging’

id = None

GitHub’s id of this deployment

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

payload = None

JSON string payload of the Deployment

ref = None

The reference used to create the Deployment, e.g., deploy-20140526

sha = None

SHA of the branch on GitHub

statuses_url = None

URL to get the statuses of this deployment

updated_at = None

Date the Deployment was updated


class github3.repos.deployment.DeploymentStatus(status, session=None)
created_at = None

Date the deployment status was created

creator = None

Creater of the deployment status

deployment = None

Deployment representing the deployment this status is associated with

deployment_url = None

URL for the deployment this status is associated with

description = None

Description of the deployment

id = None

GitHub’s id for this deployment status

payload = None

JSON payload as a string

state = None

State of the deployment status

target_url = None

Target URL of the deployment

updated_at = None

Date the deployment status was updated


class github3.repos.release.Release(release, session=None)

The Release object.

It holds the information GitHub returns about a release from a Repository.

assets = None

List of Asset objects for this release

assets_url = None

URL for uploaded assets

body = None

Body of the release (the description)

created_at = None

Date the release was created

delete()

Users with push access to the repository can delete a release.

Returns:True if successful; False if not successful
draft = None

Boolean whether value is True or False

edit(tag_name=None, target_commitish=None, name=None, body=None, draft=None, prerelease=None)

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

html_url = None

HTML URL of the release

id = None

GitHub id

iter_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

name = None

Name given to the release

published_at = None

Date the release was published

tag_name = None

Name of the tag

target_commitish = None

“Commit” that this release targets

upload_asset(content_type, name, asset)

Upload an asset to this release.

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.
Returns:

Asset

upload_urlt = None

URITemplate to upload an asset with


class github3.repos.release.Asset(asset, session=None)
content_type = None

Content-Type provided when the asset was created

created_at = None

Date the asset was created

download(path=u'')

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:bool – True if successful, False otherwise
download_count = None

Number of times the asset was downloaded

download_url = None

URL to download the asset. Request headers must include Accept: application/octet-stream.

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:

boolean

id = None

GitHub id of the asset

label = None

Short description of the asset

name = None

Name of the asset

size = None

Size of the asset

state = None

State of the asset, e.g., “uploaded”

updated_at = None

Date the asset was updated


class github3.repos.hook.Hook(hook, session=None)

The Hook object. This handles the information returned by GitHub about hooks set on a repository.

Two hook instances can be checked like so:

h1 == h2
h1 != h2

And is equivalent to:

h1.id == h2.id
h1.id != h2.id

See also: http://developer.github.com/v3/repos/hooks/

active = None

Whether or not this Hook is marked as active on GitHub

config = None

Dictionary containing the configuration for the Hook.

created_at = None

datetime object representing the date the hook was created.

delete()

Delete this hook.

Returns: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 remvoed from the list of events that this hook triggers for
  • active (bool) – (optional), should this event be active
Returns:

bool

events = None

Events which trigger the hook.

id = None

Unique id of the hook.

name = None

The name of the hook.

ping()

Ping this hook.

Returns:bool
test()

Test this hook

Returns:bool
updated_at = None

datetime object representing when this hook was last updated.


class github3.repos.pages.PagesInfo(info)
cname = None

CName used for the pages site

custom_404 = None

Boolean indicating whether there is a custom 404 for the pages site

status = None

Status of the pages site, e.g., built


class github3.repos.pages.PagesBuild(build)
commit = None

SHA of the commit that triggered the build

created_at = None

Datetime the build was created

duration = None

Time the build took to finish

error = None

Error dictionary containing the error message

pusher = None

User representing who pushed the commit

status = None

Status of the pages build, e.g., building

updated_at = None

Datetime the build was updated


class github3.repos.tag.RepoTag(tag)

The RepoTag object. This stores the information representing a tag that was created on a repository.

See also: http://developer.github.com/v3/repos/#list-tags

commit = None

Dictionary containing the SHA and URL of the commit.

name = None

Name of the tag.

tarball_url = None

URL for the GitHub generated tarball associated with the tag.

zipball_url = None

URL for the GitHub generated zipball associated with the tag.


More information about this class can be found in the official documentation about comments.

class github3.repos.comment.RepoComment(comment, session=None)

The RepoComment object. This stores the information about a comment on a file in a repository.

Two comment instances can be checked like so:

c1 == c2
c1 != c2

And is equivalent to:

c1.id == c2.id
c1.id != c2.id
commit_id = None

Commit id on which the comment was made.

delete()

Delete this comment.

Returns:bool
edit(body)

Edit this comment.

Parameters:body (str) – (required), new body of the comment, Markdown formatted
Returns:bool
from_json(json)

Return an instance of cls formed from json.

html_url = None

URL of the comment on GitHub.

line = None

The line number where the comment is located.

path = None

The path to the file where the comment was made.

position = None

The position in the diff where the comment was made.

ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

to_json()

Return the json representing this object.

update(body)

Update this comment.

Parameters:body (str) – (required)
Returns:bool
updated_at = None

datetime object representing when the comment was updated.

user = None

Login of the user who left the comment.


class github3.repos.commit.RepoCommit(commit, session=None)

The RepoCommit object. This represents a commit as viewed by a Repository. This is different from a Commit object returned from the git data section.

Two commit instances can be checked like so:

c1 == c2
c1 != c2

And is equivalent to:

c1.sha == c2.sha
c1.sha != c2.sha
additions = None

The number of additions made in the commit.

author = None

User who authored the commit.

commit = None

Commit.

committer = None

User who committed the commit.

deletions = None

The number of deletions made in the commit.

diff()

Return the diff

files = None

The files that were modified by this commit.

patch()

Return the patch

total = None

Total number of changes in the files.


class github3.repos.comparison.Comparison(compare)

The Comparison object. This encapsulates the information returned by GitHub comparing two commit objects in a repository.

Two comparison instances can be checked like so:

c1 == c2
c1 != c2

And is equivalent to:

c1.commits == c2.commits
c1.commits != c2.commits

See also: http://developer.github.com/v3/repos/commits/#compare-two-commits

ahead_by = None

Number of commits ahead by.

base_commit = None

RepoCommit object representing the base of comparison.

behind_by = None

Number of commits behind by.

commits = None

List of RepoCommit objects.

diff()

Return the diff

diff_url = None

URL to see the diff between the two commits.

files = None

List of dicts describing the files modified.

html_url = None

URL to view the comparison at GitHub

patch()

Return the patch

patch_url = None

Patch URL at GitHub for the comparison.

Permanent link to this comparison.

status = None

Behind or ahead.

total_commits = None

Number of commits difference in the comparison.


class github3.repos.status.Status(status)

The Status object. This represents information from the Repo Status API.

See also: http://developer.github.com/v3/repos/statuses/

created_at = None

datetime object representing the creation of the status object

creator = None

User who created the object

description = None

Short description of the Status

id = None

GitHub ID for the status object

state = None

State of the status, e.g., ‘success’, ‘pending’, ‘failed’, ‘error’

target_url = None

URL to view more information about the status

updated_at = None

datetime object representing the last time the status was updated


class github3.repos.stats.ContributorStats(stats_object, session=None)

This object provides easy access to information returned by the statistics section of the API.

See http://developer.github.com/v3/repos/statistics/ for specifics.

alt_weeks = None

Alternative collection of weekly dictionaries This provides a datetime object and easy to remember keys for each element in the list. ‘w’ -> ‘start of week’, ‘a’ -> ‘Number of additions’, ‘d’ -> ‘Number of deletions’, ‘c’ -> ‘Number of commits’

author = None

Contributor in particular that this relates to

total = None

Total number of commits authored by author.

weeks = None

List of weekly dictionaries.