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(json, 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/

class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
Repository.add_collaborator(username)

Add username as a collaborator to a repository.

Parameters:username (str or User) – (required), username of the user
Returns:bool – True if successful, False otherwise
Repository.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

Repository.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
Repository.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
Repository.asset(id)

Return a single asset.

Parameters:id (int) – (required), id of the asset
Returns:Asset
Repository.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

Repository.blob(sha)

Get the blob indicated by sha.

Parameters:sha (str) – (required), sha of the blob
Returns:Blob if successful, otherwise None
Repository.branch(name)

Get the branch name of this repository.

Parameters:name (str) – (required), branch name
Returns:Branch
Repository.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

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

Repository.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 comments
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Users

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

Repository.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
Repository.commit_activity(number=-1, etag=None)

Iterate over last year of commit activity by week.

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.

New in version 0.7.

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

Repository.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
Repository.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 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.
  • per_page (int) – (optional), commits listing page size
Returns:

generator of RepoCommits

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

Repository.contributor_statistics(number=-1, etag=None)

Iterate over the contributors list.

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.

New in version 0.7.

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

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

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

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

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

Commit if successful, else None

Repository.create_deployment(ref, required_contexts=None, 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.
  • 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:

Deployment

Repository.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}

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

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

Issue if successful, otherwise None

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

Key if successful, else None

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

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

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

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

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

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

Repository.create_status(sha, state, target_url=None, description=None, context=u'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 status created if successful

Return type:

Status

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

  1. Creates the tag object
  2. 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 lightweight == False: Tag if successful, else None. If lightweight == True: Reference

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

Tree if successful, else None

Repository.delete()

Delete this repository.

Returns:bool – True if successful, False otherwise
Repository.delete_key(key_id)

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

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

Delete the user’s subscription to this repository.

Returns:bool
Repository.deployment(id)

Retrieve the deployment identified by id.

Parameters:id (int) – (required), id for deployments.
Returns:Deployment
Repository.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

Repository.directory_contents(directory_path, ref=None, return_as=<type '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:

list((str, Contents))

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

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

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

Contents

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

Repository.from_dict(json_dict)

Return an instance of this class formed from json_dict.

Repository.from_json(json)

Return an instance of this class formed from json.

Repository.git_commit(sha)

Get a single (git) commit.

Parameters:sha (str) – (required), sha of the commit
Returns:Commit if successful, otherwise None
Repository.hook(hook_id)

Get a single hook.

Parameters:hook_id (int) – (required), id of the hook
Returns:Hook if successful, otherwise None
Repository.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

Repository.ignore()

Ignore notifications from this repository for the user.

New in version 1.0.

This replaces Repository#set_subscription.

Returns:Subscription
Repository.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 (timestamp) – (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:

ImportedIssue

Repository.imported_issue(imported_issue_id)

Retrieve imported issue specified by imported issue id.

Parameters:imported_issue_id (int) – (required) id of imported issue
Returns:Imported Issue
Repository.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 ImportedIssue

Repository.is_assignee(username)

Check if the user can be assigned an issue on this repository.

Parameters:username (str or User) – name of the user to check
Returns:bool
Repository.is_collaborator(username)

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

Parameters:username (str or User) – (required), login for the user
Returns:bool – True if successful, False otherwise
Repository.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
Repository.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 IssueEvents

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

Repository.key(id_num)

Get the specified deploy key.

Parameters:id_num (int) – (required), id of the key
Returns:Key if successful, else None
Repository.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

Repository.label(name)

Get the label specified by name.

Parameters:name (str) – (required), name of the label
Returns:Label if successful, else None
Repository.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

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

Repository.latest_pages_build()

Get the build information for the most recent Pages build.

Returns:PagesBuild
Repository.latest_release()

Get the latest release.

Draft releases and prereleases are not returned by this endpoint.

Returns:Release
Repository.license()

Get the contents of a license for the repo

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

Repository.milestone(number)

Get the milestone indicated by number.

Parameters:number (int) – (required), unique id number of the milestone
Returns:Milestone
Repository.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

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

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

Repository.pages()

Get information about this repository’s pages site.

Returns:PagesInfo
Repository.pages_builds(number=-1, etag=None)

Iterate over pages builds of this repository.

Returns:generator of PagesBuild
Repository.pull_request(number)

Get the pull request indicated by number.

Parameters:number (int) – (required), number of the pull request.
Returns:PullRequest
Repository.pull_requests(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

Repository.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
Repository.readme()

Get the README for this repository.

Returns:Contents
Repository.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
Repository.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
Repository.refs(subspace=u'', 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

Repository.release(id)

Get a single release.

Parameters:id (int) – (required), id of release
Returns:Release
Repository.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:Release
Repository.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

Repository.remove_collaborator(username)

Remove collaborator username from the repository.

Parameters:username (str or User) – (required), login name of the collaborator
Returns:bool
Repository.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

Repository.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 Status

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

Subscription

Repository.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 User

Repository.subscription()

Return subscription for this Repository.

Returns:Subscription
Repository.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
Repository.tags(number=-1, etag=None)

Iterate over tags on this repository.

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

generator of RepoTags

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

Repository.tree(sha)

Get a tree.

Parameters:sha (str) – (required), sha of the object for this tree
Returns:Tree
Repository.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 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

class github3.repos.repo.StarredRepository(json, session=None)

The StarredRepository object.

It represents how GitHub sends back a repository a user has starred, e.g., from starred_repositories().

See also: https://developer.github.com/v3/activity/starring/#list-repositories-being-starred

class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
StarredRepository.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
StarredRepository.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
StarredRepository.from_dict(json_dict)

Return an instance of this class formed from json_dict.

StarredRepository.from_json(json)

Return an instance of this class formed from json.

StarredRepository.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
StarredRepository.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.branch.Branch(json, session=None)

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

latest_sha(differs_from=u'')

Check if SHA-1 is the same as remote branch

See: https://git.io/vaqIw

Parameters:differs_from (str) – (optional), sha to compare against
Returns:string of the SHA or None
protect(enforcement=None, status_checks=None)

Enable force push protection and configure status check enforcement.

See: http://git.io/v4Gvu

Parameters:
  • enforcement (str) – (optional), Specifies the enforcement level of the status checks. Must be one of ‘off’, ‘non_admins’, or ‘everyone’. Use None or omit to use the already associated value.
  • status_checks (list) – (optional), An list of strings naming status checks that must pass before merging. Use None or omit to use the already associated value.
unprotect()

Disable force push protection on this branch.


class github3.repos.contents.Contents(json, 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/

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:

Contents and Commit

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:

dictionary of Contents and Commit


class github3.repos.deployment.Deployment(json, session=None)
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, 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

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


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

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

The Release object.

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

archive(format, path=u'')

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:

bool – True if successful, False otherwise

asset(asset_id)

Retrieve the asset from this release with asset_id.

Parameters:asset_id (int) – ID of the Asset to retrieve
Returns: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

delete()

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

Returns:True if successful; False if not successful
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

upload_asset(content_type, name, asset, label=None)

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.
  • label – (optional), An alternate short description of the asset.
Returns:

Asset


class github3.repos.release.Asset(json, session=None)
delete()

Delete this asset if the user has push access.

Returns:True if successful; False if not successful
Return type:boolean
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: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:

boolean


class github3.repos.hook.Hook(json, 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/

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

bool

ping()

Ping this hook.

Returns:bool
test()

Test this hook

Returns:bool

class github3.repos.issue_import.ImportedIssue(json, session=None)

The ImportedIssue object. This represents information from the Import Issue API.

See also: https://gist.github.com/jonmagic/5282384165e0f86ef105


class github3.repos.pages.PagesInfo(json, session=None)

class github3.repos.pages.PagesBuild(json, session=None)

class github3.repos.tag.RepoTag(json, session=None)

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


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

class github3.repos.comment.RepoComment(json, 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
class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
RepoComment.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
RepoComment.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
RepoComment.delete()

Delete this comment.

Returns:bool
RepoComment.edit(body)

Edit this comment.

Parameters:body (str) – (required), new body of the comment, Markdown formatted
Returns:bool
RepoComment.from_dict(json_dict)

Return an instance of this class formed from json_dict.

RepoComment.from_json(json)

Return an instance of this class formed from json.

RepoComment.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
RepoComment.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
RepoComment.update(body)

Update this comment.

Parameters:body (str) – (required)
Returns:bool

class github3.repos.commit.RepoCommit(json, 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
comments(number=-1, etag=None)

Iterate over comments for this commit.

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

diff()

Retrieve the diff for this commit.

Returns:the diff as a bytes object
Return type:bytes
patch()

Retrieve the patch formatted diff for this commit.

Returns:the patch as a bytes object
Return type:bytes
statuses()

Retrieve the statuses for this commit.

Returns:the statuses for this commit
Return type:Status

class github3.repos.comparison.Comparison(json, session=None)

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

diff()

Retrieve the diff for this comparison.

Returns:the diff as a bytes object
Return type:bytes
patch()

Retrieve the patch formatted diff for this commit.

Returns:the patch as a bytes object
Return type:bytes

class github3.repos.status.Status(json, session=None)

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

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


class github3.repos.stats.ContributorStats(json, 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.