Repository¶

This part of the documentation covers:

Repository
StarredRepository
Asset
Branch
Contents
Deployment
DeploymentStatus
Hook
ImportedIssue
PagesInfo
PagesBuild
Release
RepoTag
RepoComment
RepoCommit
Comparison
Status
CombinedStatus
ContributorStats

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)¶

This organizes the full representation of a single Repository.

The full representation of a Repository is not returned in collections but instead in individual requests, e.g., repository().

This object has all the same attributes as ShortRepository as well as:

archived¶: A boolean attribute that describes whether the current repository has been archived or not.

clone_url¶: This is the URL that can be used to clone the repository via HTTPS, e.g., https://github.com/sigmavirus24/github3.py.git.

created_at¶: A parsed datetime object representing the date the repository was created.

default_branch¶: This is the default branch of the repository as configured by its administrator(s).

forks_count¶: This is the number of forks of the repository.

git_url¶: This is the URL that can be used to clone the repository via the Git protocol, e.g., git://github.com/sigmavirus24/github3.py.

has_downloads¶: This is a boolean attribute that conveys whether or not the repository has downloads.

has_issues¶: This is a boolean attribute that conveys whether or not the repository has issues.

has_pages¶: This is a boolean attribute that conveys whether or not the repository has pages.

has_wiki¶: This is a boolean attribute that conveys whether or not the repository has a wiki.

homepage¶: This is the administrator set homepage URL for the project. This may not be provided.

language¶: This is the language GitHub has detected for the repository.

original_license¶: Note

When used with a Github Enterprise instance <= 2.12.7, this attribute will not be returned. To handle these situations sensitively, the attribute will be set to None. Repositories may still have a license associated with them in these cases.

This is the ShortLicense returned as part of the repository. To retrieve the most recent license, see the license() method.

mirror_url¶: The URL that GitHub is mirroring the repository from.

network_count¶: The size of the repository’s “network”.

open_issues_count¶: The number of issues currently open on the repository.

parent¶: A representation of the parent repository as ShortRepository. If this Repository has no parent then this will be None.

pushed_at¶: A parsed datetime object representing the date a push was last made to the repository.

size¶: The size of the repository.

source¶: A representation of the source repository as ShortRepository. If this Repository has no source then this will be None.

ssh_url¶: This is the URL that can be used to clone the repository via the SSH protocol, e.g., ssh@github.com:sigmavirus24/github3.py.git.

stargazers_count¶: The number of people who have starred this repository.

subscribers_count¶: The number of people watching (or who have subscribed to notifications about) this repository.

svn_url¶: This is the URL that can be used to clone the repository via SVN, e.g., ssh@github.com:sigmavirus24/github3.py.git.

updated_at¶: A parsed datetime object representing the date a the repository was last updated by its administrator(s).

watchers_count¶: The number of people watching this repository.

add_collaborator(username)¶

Add username as a collaborator to a repository.

Parameters:	username (str or `User`) – (required), username of the user
Returns:	True if successful, False otherwise
Return type:

archive(format, path='', ref='master')¶

Get the tarball or zipball archive for this repo at ref.

See: http://developer.github.com/v3/repos/contents/#get-archive-link

Parameters:	format (str) – (required), accepted values: (‘tarball’, ‘zipball’) path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. it can take a file-like object as well ref (str) – (optional)
Returns:	True if successful, False otherwise
Return type:	bool

as_dict()¶

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:	this object’s attributes serialized to a dictionary
Return type:	dict

as_json()¶

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:	this object’s attributes as a JSON string
Return type:	str

asset(id)¶

Return a single asset.

Parameters:	id (int) – (required), id of the asset
Returns:	the asset
Return type:	`Asset`

assignees(number=-1, etag=None)¶

Iterate over all assignees to which an issue may be assigned.

Parameters:	number (int) – (optional), number of assignees to return. Default: -1 returns all available assignees etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of users
Return type:	`ShortUser`

blob(sha)¶

Get the blob indicated by sha.

Parameters:	sha (str) – (required), sha of the blob
Returns:	the git blob
Return type:	`Blob`

branch(name)¶

Get the branch name of this repository.

Parameters:	name (str) – (required), branch name
Returns:	the branch
Return type:	`Branch`

branches(number=-1, protected=False, etag=None)¶

Iterate over the branches in this repository.

Parameters:	number (int) – (optional), number of branches to return. Default: -1 returns all branches protected (bool) – (optional), True lists only protected branches. Default: False etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of branches
Return type:	`Branch`

code_frequency(number=-1, etag=None)¶

Iterate over the code frequency per week.

New in version 0.7.

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

Note

All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new last_status attribute. If it is a 202 you should wait before re-requesting.

Parameters:	number (int) – (optional), number of weeks to return. Default: -1 returns all weeks etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of lists `[seconds_from_epoch, additions, deletions]`
Return type:	list

collaborators(affiliation='all', number=-1, etag=None)¶

Iterate over the collaborators of this repository.

Parameters:	affiliation (str) – (optional), affiliation of the collaborator to the repository. Default: “all” returns contributors with all affiliations number (int) – (optional), number of collaborators to return. Default: -1 returns all comments etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of collaborators
Return type:	`Collaborator`

comments(number=-1, etag=None)¶

Iterate over comments on all commits in the repository.

Parameters:	number (int) – (optional), number of comments to return. Default: -1 returns all comments etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of comments on commits
Return type:	`RepoComment`

commit(sha)¶

Get a single (repo) commit.

See git_commit() for the Git Data Commit.

Parameters:	sha (str) – (required), sha of the commit
Returns:	the commit
Return type:	`RepoCommit`

commit_activity(number=-1, etag=None)¶

Iterate over last year of commit activity by week.

New in version 0.7.

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

Note

All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new last_status attribute. If it is a 202 you should wait before re-requesting.

Parameters:	number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks. etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of dictionaries
Return type:	dict

commit_comment(comment_id)¶

Get a single commit comment.

Parameters:	comment_id (int) – (required), id of the comment used by GitHub
Returns:	the comment on the commit
Return type:	`RepoComment`

commits(sha=None, path=None, author=None, number=-1, etag=None, since=None, until=None, per_page=None)¶

Iterate over commits in this repository.

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

compare_commits(base, head)¶

Compare two commits.

Parameters:	base (str) – (required), base for the comparison head (str) – (required), compare this against base
Returns:	the comparison of the commits
Return type:	`Comparison`

contributor_statistics(number=-1, etag=None)¶

Iterate over the contributors list.

New in version 0.7.

Note

All statistics methods may return a 202. On those occasions, you will not receive any objects. You should store your iterator and check the new last_status attribute. If it is a 202 you should wait before re-requesting.

Parameters:	number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks. etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of contributor statistics for each contributor
Return type:	`ContributorStats`

contributors(anon=False, number=-1, etag=None)¶

Iterate over the contributors to this repository.

Parameters:	anon (bool) – (optional), True lists anonymous contributors as well number (int) – (optional), number of contributors to return. Default: -1 returns all contributors etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of contributor users
Return type:	`Contributor`

create_blob(content, encoding)¶

Create a blob with content.

Parameters:	content (str) – (required), content of the blob encoding (str) – (required), (‘base64’, ‘utf-8’)
Returns:	string of the SHA returned
Returns:	str (on Python 3, unicode on Python 2)

create_comment(body, sha, path=None, position=None, line=1)¶

Create a comment on a commit.

Parameters:	body (str) – (required), body of the message sha (str) – (required), commit id path (str) – (optional), relative path of the file to comment on position (str) – (optional), line index in the diff to comment on line (int) – (optional), line number of the file to comment on, default: 1
Returns:	the created comment
Return type:	`RepoComment`

create_commit(message, tree, parents, author=None, committer=None)¶

Create a commit on this repository.

Parameters:	message (str) – (required), commit message tree (str) – (required), SHA of the tree object this commit points to parents (list) – (required), SHAs of the commits that were parents of this commit. If empty, the commit will be written as the root commit. Even if there is only one parent, this should be an array. author (dict) – (optional), if omitted, GitHub will use the authenticated user’s credentials and the current time. Format: {‘name’: ‘Committer Name’, ‘email’: ‘name@example.com’, ‘date’: ‘YYYY-MM-DDTHH:MM:SS+HH:00’} committer (dict) – (optional), if ommitted, GitHub will use the author parameters. Should be the same format as the author parameter.
Returns:	the created commit
Return type:	`Commit`

create_deployment(ref, required_contexts=None, payload='', auto_merge=False, description='', environment=None)¶

Create a deployment.

Parameters:	ref (str) – (required), The ref to deploy. This can be a branch, tag, or sha. required_contexts (list) – Optional array of status contexts verified against commit status checks. To bypass checking entirely pass an empty array. Default: [] payload (str) – Optional JSON payload with extra information about the deployment. Default: “” auto_merge (bool) – Optional parameter to merge the default branch into the requested deployment branch if necessary. Default: False description (str) – Optional short description. Default: “” environment (str) – Optional name for the target deployment environment (e.g., production, staging, qa). Default: “production”
Returns:	the created deployment
Return type:	`Deployment`

create_file(path, message, content, branch=None, committer=None, author=None)¶

Create a file in this repository.

Parameters:	path (str) – (required), path of the file in the repository message (str) – (required), commit message content (bytes) – (required), the actual data in the file branch (str) – (optional), branch to create the commit on. Defaults to the default branch of the repository committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email. author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
Returns:	dictionary of contents and commit for created file
Return type:	`Contents`, `Commit`

create_fork(organization=None)¶

Create a fork of this repository.

Parameters:	organization (str) – (required), login for organization to create the fork under
Returns:	the fork of this repository
Return type:	`Repository`

create_hook(name, config, events=['push'], active=True)¶

Create a hook on this repository.

Parameters:	name (str) – (required), name of the hook config (dict) – (required), key-value pairs which act as settings for this hook events (list) – (optional), events the hook is triggered for active (bool) – (optional), whether the hook is actually triggered
Returns:	the created hook
Return type:	`Hook`

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 ([str]) – (optional), labels to apply to this issue assignees ([str]) – (optional), login of the users to assign the issue to
Returns:	the created issue
Return type:	`ShortIssue`

create_key(title, key, read_only=False)¶

Create a deploy key.

Parameters:	title (str) – (required), title of key key (str) – (required), key text read_only (bool) – (optional), restrict key access to read-only, default is False
Returns:	the created key
Return type:	`Key`

create_label(name, color)¶

Create a label for this repository.

Parameters:	name (str) – (required), name to give to the label color (str) – (required), value of the color to assign to the label, e.g., ‘#fafafa’ or ‘fafafa’ (the latter is what is sent)
Returns:	the created label
Return type:	`Label`

create_milestone(title, state=None, description=None, due_on=None)¶

Create a milestone for this repository.

Parameters:	title (str) – (required), title of the milestone state (str) – (optional), state of the milestone, accepted values: (‘open’, ‘closed’), default: ‘open’ description (str) – (optional), description of the milestone due_on (str) – (optional), ISO 8601 formatted due date
Returns:	the created milestone
Return type:	`Milestone`

create_project(name, body=None)¶

Create a project for this repository.

Parameters:	name (str) – (required), name of the project body (str) – (optional), body of the project
Returns:	the created project
Return type:	`Project`

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

Create a pull request of head 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:	the created pull request
Return type:	`ShortPullRequest`

create_pull_from_issue(issue, base, head)¶

Create a pull request from issue #``issue``.

Parameters:	issue (int) – (required), issue number base (str) – (required), e.g., ‘master’ head (str) – (required), e.g., ‘username:branch’
Returns:	the created pull request
Return type:	`ShortPullRequest`

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:	the created ref
Return type:	`Reference`

create_release(tag_name, target_commitish=None, name=None, body=None, draft=False, prerelease=False)¶

Create a release for this repository.

Parameters:	tag_name (str) – (required), name to give to the tag target_commitish (str) – (optional), vague concept of a target, either a SHA or a branch name. name (str) – (optional), name of the release body (str) – (optional), description of the release draft (bool) – (optional), whether this release is a draft or not prerelease (bool) – (optional), whether this is a prerelease or not
Returns:	the created release
Return type:	`Release`

create_status(sha, state, target_url=None, description=None, context='default')¶

Create a status object on a commit.

Parameters:	sha (str) – (required), SHA of the commit to create the status on state (str) – (required), state of the test; only the following are accepted: ‘pending’, ‘success’, ‘error’, ‘failure’ target_url (str) – (optional), URL to associate with this status. description (str) – (optional), short description of the status context (str) – (optional), A string label to differentiate this status from the status of other systems
Returns:	the created status
Return type:	`Status`

create_tag(tag, message, sha, obj_type, tagger, lightweight=False)¶

Create a tag in this repository.

By default, this method creates an annotated tag. If you wish to create a lightweight tag instead, pass lightweight=True.

If you are creating an annotated tag, this method makes 2 calls to the API:

Creates the tag object
Creates the reference for the tag

This behaviour is required by the GitHub API.

Parameters:	tag (str) – (required), name of the tag message (str) – (required), tag message sha (str) – (required), SHA of the git object this is tagging obj_type (str) – (required), type of object being tagged, e.g., ‘commit’, ‘tree’, ‘blob’ tagger (dict) – (required), containing the name, email of the tagger and the date it was tagged lightweight (bool) – (optional), if False, create an annotated tag, otherwise create a lightweight tag (a Reference).
Returns:	if creating a lightweight tag, this will return a `Reference`, otherwise it will return a `Tag`
Return type:	`Tag` or `Reference`

create_tree(tree, base_tree=None)¶

Create a tree on this repository.

Parameters:	tree (list) – (required), specifies the tree structure. Format: [{‘path’: ‘path/file’, ‘mode’: ‘filemode’, ‘type’: ‘blob or tree’, ‘sha’: ‘44bfc6d…’}] base_tree (str) – (optional), SHA1 of the tree you want to update with new data
Returns:	the created tree
Return type:	`Tree`

delete()¶

Delete this repository.

Returns:	True if successful, False otherwise
Return type:	bool

delete_key(key_id)¶

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

Returns:	True if successful, False otherwise
Return type:	bool

delete_subscription()¶

Delete the user’s subscription to this repository.

Returns:	True if successful, False otherwise
Return type:	bool

deployment(id)¶

Retrieve the deployment identified by id.

Parameters:	id (int) – (required), id for deployments.
Returns:	the deployment
Return type:	`Deployment`

deployments(number=-1, etag=None)¶

Iterate over deployments for this repository.

Parameters:	number (int) – (optional), number of deployments to return. Default: -1, returns all available deployments etag (str) – (optional), ETag from a previous request for all deployments
Returns:	generator of deployments
Return type:	`Deployment`

directory_contents(directory_path, ref=None, return_as=<class 'list'>)¶

Get the contents of each file in directory_path.

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

[('filename.md', Contents(...)),
 ('github.py', Contents(...)),
 # ...
 ('fiz.py', Contents(...))]

You can either then transform it into a dictionary:

contents = dict(repo.directory_contents('path/to/dir/'))

Or you can use the return_as parameter to have it return a dictionary for you:

contents = repo.directory_contents('path/to/dir/', return_as=dict)

Parameters:	path (str) – (required), path to file, e.g. github3/repos/repo.py ref (str) – (optional), the string name of a commit/branch/tag. Default: master return_as – (optional), how to return the directory’s contents. Default: `list`
Returns:	list of tuples of the filename and the Contents returned
Return type:	[(str, `Contents`)]

edit(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, default_branch=None, archived=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. archived (bool) – (optional), If not `None`, toggle the archived attribute on the repository to control whether it is archived or not.
Returns:	True if successful, False otherwise
Return type:	bool

events(number=-1, etag=None)¶

Iterate over events on this repository.

Parameters:	number (int) – (optional), number of events to return. Default: -1 returns all available events etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of events
Return type:	`Event`

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`

forks(sort='', 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 forks of this repository
Return type:	`ShortRepository`

from_dict(json_dict, session)¶: Return an instance of this class formed from json_dict.

from_json(json, session)¶: Return an instance of this class formed from json.

git_commit(sha)¶

Get a single (git) commit.

Parameters:	sha (str) – (required), sha of the commit
Returns:	the single commit data from git
Return type:	`Commit`

hook(hook_id)¶

Get a single hook.

Parameters:	hook_id (int) – (required), id of the hook
Returns:	the hook
Return type:	`Hook`

hooks(number=-1, etag=None)¶

Iterate over hooks registered on this repository.

Parameters:	number (int) – (optional), number of hoks to return. Default: -1 returns all hooks etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of hooks
Return type:	`Hook`

ignore()¶

Ignore notifications from this repository for the user.

New in version 1.0.

This replaces Repository#set_subscription.

Returns:	the new repository subscription
Return type:	:class:~github3.notifications.RepositorySubscription`

import_issue(title, body, created_at, assignee=None, milestone=None, closed=None, labels=None, comments=None)¶

Import an issue into the repository.

Parameters:	title (string) – (required) Title of issue body (string) – (required) Body of issue created_at (`datetime` or str) – (required) Creation timestamp assignee (string) – (optional) Username to assign issue to milestone (int) – (optional) Milestone ID closed (boolean) – (optional) Status of issue is Closed if True labels (list) – (optional) List of labels containing string names comments (list) – (optional) List of dictionaries which contain created_at and body attributes
Returns:	the imported issue
Return type:	`ImportedIssue`

imported_issue(imported_issue_id)¶

Retrieve imported issue specified by imported issue id.

Parameters:	imported_issue_id (int) – (required) id of imported issue
Returns:	the imported issue
Return type:	`ImportedIssue`

imported_issues(number=-1, since=None, etag=None)¶

Retrieve the collection of imported issues via the API.

Parameters:	number (int) – (optional), number of imported issues to return. Default: -1 returns all branches since – (optional), Only imported issues after this date will be returned. This can be a `datetime` instance, ISO8601 formatted date string, or a string formatted like so: `2016-02-04` i.e. `%Y-%m-%d` etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of imported issues
Return type:	`ImportedIssue`

is_assignee(username)¶

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

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

is_collaborator(username)¶

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

Parameters:	username (str or `User`) – (required), login for the user
Returns:	True if successful, False otherwise
Return type:	bool

issue(number)¶

Get the issue specified by number.

Parameters:	number (int) – (required), number of the issue on this repository
Returns:	the issue
Return type:	`Issue`

issue_events(number=-1, etag=None)¶

Iterate over issue events on this repository.

Parameters:	number (int) – (optional), number of events to return. Default: -1 returns all available events etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of events on issues
Return type:	`IssueEvent`

issues(milestone=None, state=None, assignee=None, mentioned=None, labels=None, sort=None, direction=None, since=None, number=-1, etag=None)¶

Iterate over issues on this repo based upon parameters passed.

Changed in version 0.9.0: The state parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.

Parameters:	milestone (int) – (optional), ‘none’, or ‘’ state* (str) – (optional), accepted values: (‘all’, ‘open’, ‘closed’) assignee (str) – (optional), ‘none’, ‘’, or login name mentioned* (str) – (optional), user’s login name labels (str) – (optional), comma-separated list of labels, e.g. ‘bug,ui,@high’ sort – (optional), accepted values: (‘created’, ‘updated’, ‘comments’, ‘created’) direction (str) – (optional), accepted values: (‘asc’, ‘desc’) since (`datetime` or str) – (optional), Only issues after this date will be returned. This can be 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
Return type:	`ShortIssue`

key(id_num)¶

Get the specified deploy key.

Parameters:	id_num (int) – (required), id of the key
Returns:	the deploy key
Return type:	`Key`

keys(number=-1, etag=None)¶

Iterate over deploy keys on this repository.

Parameters:	number (int) – (optional), number of keys to return. Default: -1 returns all available keys etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of keys
Return type:	`Key`

label(name)¶

Get the label specified by name.

Parameters:	name (str) – (required), name of the label
Returns:	the label
Return type:	`Label`

labels(number=-1, etag=None)¶

Iterate over labels on this repository.

Parameters:	number (int) – (optional), number of labels to return. Default: -1 returns all available labels etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of labels
Return type:	`Label`

languages(number=-1, etag=None)¶

Iterate over the programming languages used in the repository.

Parameters:	number (int) – (optional), number of languages to return. Default: -1 returns all used languages etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of tuples
Return type:	tuple

latest_pages_build()¶

Get the build information for the most recent Pages build.

Returns:	the information for the most recent build
Return type:	`PagesBuild`

latest_release()¶

Get the latest release.

Draft releases and prereleases are not returned by this endpoint.

Returns:	the release
Return type:	`Release`

license()¶

Get the contents of a license for the repo.

Returns:	the license
Return type:	`RepositoryLicense`

mark_notifications(last_read='')¶

Mark all notifications in this repository as read.

Parameters:	last_read (str) – (optional), Describes the last point that notifications were checked. Anything updated since this time will not be updated. Default: Now. Expected in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Example: “2012-10-09T23:39:01Z”.
Returns:	True if successful, False otherwise
Return type:	bool

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

Perform a merge from head 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:	the commit resulting from the merge
Return type:	`RepoCommit`

milestone(number)¶

Get the milestone indicated by number.

Parameters:	number (int) – (required), unique id number of the milestone
Returns:	the milestone
Return type:	`Milestone`

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

Iterate over the milestones on this repository.

Parameters:	state (str) – (optional), state of the milestones, accepted values: (‘open’, ‘closed’) sort (str) – (optional), how to sort the milestones, accepted values: (‘due_date’, ‘completeness’) direction (str) – (optional), direction to sort the milestones, accepted values: (‘asc’, ‘desc’) number (int) – (optional), number of milestones to return. Default: -1 returns all milestones etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of milestones
Return type:	`Milestone`

network_events(number=-1, etag=None)¶

Iterate over events on a network of repositories.

Parameters:	number (int) – (optional), number of events to return. Default: -1 returns all available events etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of events
Return type:	`Event`

new_session()¶

Generate a new session.

Returns:	A brand new session
Return type:	`GitHubSession`

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

Iterate over the notifications for this repository.

Parameters:	all (bool) – (optional), show all notifications, including ones marked as read participating (bool) – (optional), show only the notifications the user is participating in directly since (`datetime` or str) – (optional), filters out any notifications updated before the given time. This can be a datetime or an ISO8601 formatted date string, e.g., 2012-05-20T23:10:27Z etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of notification threads
Return type:	`Thread`

pages()¶

Get information about this repository’s pages site.

Returns:	information about this repository’s GitHub pages site
Return type:	`PagesInfo`

pages_builds(number=-1, etag=None)¶

Iterate over pages builds of this repository.

Parameters:	number (int) – (optional) the number of builds to return etag (str) – (optional), ETag value from a previous request
Returns:	generator of builds
Return type:	`PagesBuild`

project(id, etag=None)¶

Return the organization project with the given ID.

Parameters:	id (int) – (required), ID number of the project
Returns:	the project
Return type:	`Project`

projects(number=-1, etag=None)¶

Iterate over projects for this organization.

Parameters:	number (int) – (optional), number of members to return. Default: -1 will return all available. etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of projects
Return type:	`Project`

pull_request(number)¶

Get the pull request indicated by number.

Parameters:	number (int) – (required), number of the pull request.
Returns:	the pull request
Return type:	`PullRequest`

pull_requests(state=None, head=None, base=None, sort='created', direction='desc', number=-1, etag=None)¶

List pull requests on repository.

Changed in version 0.9.0:

The state parameter now accepts ‘all’ in addition to ‘open’ and ‘closed’.
The sort parameter was added.
The direction parameter was added.

Parameters:	state (str) – (optional), accepted values: (‘all’, ‘open’, ‘closed’) head (str) – (optional), filters pulls by head user and branch name in the format `user:ref-name`, e.g., `seveas:debian` base (str) – (optional), filter pulls by base branch name. Example: `develop`. sort (str) – (optional), Sort pull requests by `created`, `updated`, `popularity`, `long-running`. Default: ‘created’ direction (str) – (optional), Choose the direction to list pull requests. Accepted values: (‘desc’, ‘asc’). Default: ‘desc’ number (int) – (optional), number of pulls to return. Default: -1 returns all available pull requests etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of pull requests
Return type:	`ShortPullRequest`

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

readme()¶

Get the README for this repository.

Returns:	this repository’s readme
Return type:	`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:	the reference
Return type:	`Reference`

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:	conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:	self

refs(subspace='', number=-1, etag=None)¶

Iterate over references for this repository.

Parameters:	subspace (str) – (optional), e.g. ‘tags’, ‘stashes’, ‘notes’ number (int) – (optional), number of refs to return. Default: -1 returns all available refs etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of references
Return type:	`Reference`

release(id)¶

Get a single release.

Parameters:	id (int) – (required), id of release
Returns:	the release
Return type:	`Release`

release_from_tag(tag_name)¶

Get a release by tag name.

release_from_tag() returns a release with specified tag while release() returns a release with specified release id

Parameters:	tag_name (str) – (required) name of tag
Returns:	the release
Return type:	`Release`

releases(number=-1, etag=None)¶

Iterate over releases for this repository.

Parameters:	number (int) – (optional), number of refs to return. Default: -1 returns all available refs etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of releases
Return type:	`Release`

remove_collaborator(username)¶

Remove collaborator username from the repository.

Parameters:	username (str or `User`) – (required), login name of the collaborator
Returns:	True if successful, False otherwise
Return type:	bool

stargazers(number=-1, etag=None)¶

List users who have starred this repository.

Parameters:	number (int) – (optional), number of stargazers to return. Default: -1 returns all subscribers available etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of users
Return type:	`ShortUser`

statuses(sha, number=-1, etag=None)¶

Iterate over the statuses for a specific SHA.

Warning

Deprecated in v1.0. Also deprecated upstream https://developer.github.com/v3/repos/statuses/

Parameters:	sha (str) – SHA of the commit to list the statuses of number (int) – (optional), return up to number statuses. Default: -1 returns all available statuses. etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of statuses
Return type:	`Status`

subscribe()¶

Subscribe the user to this repository’s notifications.

New in version 1.0.

This replaces Repository#set_subscription

Parameters:	subscribed (bool) – (required), determines if notifications should be received from this repository. ignored (bool) – (required), determines if notifications should be ignored from this repository.
Returns:	the new repository subscription
Return type:	`RepositorySubscription`

subscribers(number=-1, etag=None)¶

Iterate over users subscribed to this repository.

Parameters:	number (int) – (optional), number of subscribers to return. Default: -1 returns all subscribers available etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of users subscribed to this repository
Return type:	`ShortUser`

subscription()¶

Return subscription for this Repository.

Returns:	the user’s subscription to this repository
Return type:	`RepositorySubscription`

tag(sha)¶

Get an annotated tag.

http://learn.github.com/p/tagging.html

Parameters:	sha (str) – (required), sha of the object for this tag
Returns:	the annotated tag
Return type:	`Tag`

tags(number=-1, etag=None)¶

Iterate over tags on this repository.

Parameters:	number (int) – (optional), return up to at most number tags. Default: -1 returns all available tags. etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of tags with GitHub repository specific information
Return type:	`RepoTag`

teams(number=-1, etag=None)¶

Iterate over teams with access to this repository.

Parameters:	number (int) – (optional), return up to number Teams. Default: -1 returns all Teams. etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:	generator of teams
Return type:	`Team`

tree(sha)¶

Get a tree.

Parameters:	sha (str) – (required), sha of the object for this tree
Returns:	the tree
Return type:	`Tree`

weekly_commit_count()¶

Retrieve the total commit counts.

Note

All statistics methods may return a 202. If github3.py receives a 202 in this case, it will return an emtpy dictionary. You should give the API a moment to compose the data and then re -request it via this method.

..versionadded:: 0.7

The dictionary returned has two entries: all 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:	the commit count as a dictionary
Return type:	dict

class github3.repos.repo.StarredRepository(json, session)¶

This object represents the data returned about a user’s starred repos.

GitHub used to send back the starred_at attribute on Repositories but then changed the structure to a new object that separates that from the Repository representation. This consolidates the two.

Attributes:

starred_at¶: A parsed datetime object representing the date a the repository was starred.

repository¶: The Repository that was starred by the user.

as_dict()¶

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:	this object’s attributes serialized to a dictionary
Return type:	dict

as_json()¶

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:	this object’s attributes as a JSON string
Return type:	str

from_dict(json_dict, session)¶: Return an instance of this class formed from json_dict.

from_json(json, session)¶: Return an instance of this class formed from json.

new_session()¶

Generate a new session.

Returns:	A brand new session
Return type:	`GitHubSession`

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:	conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:	self

class github3.repos.branch.Branch(json, session)¶

The representation of a branch returned in a collection.

GitHub’s API returns different amounts of information about repositories based upon how that information is retrieved. This object exists to represent the limited amount of information returned for a specific branch in a collection. For example, you would receive this class when calling branches(). To provide a clear distinction between the types of branches, github3.py uses different classes with different sets of attributes.

This object has the same attributes as a ShortBranch as well as the following:

links¶: The dictionary of URLs returned by the API as _links.

protected¶: A boolean attribute that describes whether this branch is protected or not.

original_protection¶: Changed in version 1.1.0: To support a richer branch protection API, this is the new name for the information formerly stored under the attribute protection.

A dictionary with details about the protection configuration of this branch.

protection_url¶: The URL to access and manage details about this branch’s protection.

class github3.repos.contents.Contents(json, session)¶

A representation of file contents returned via the API.

This object has the following attributes:

content¶: The body of the file. If this is present, it may be base64 encoded.

encoding¶: The encoding used on the content when returning the data from the API, e.g., base64. If content is not present this will not be present either.

decoded¶: Note

This is a computed attribute which isn’t returned by the API.

Changed in version 0.5.2.

Decoded content of the file as a bytes object. If we try to decode to character set for you, we might encounter an exception which will prevent the object from being created. On python2 this is the same as a string, but on python3 you should call the decode method with the character set you wish to use, e.g., content.decoded.decode('utf-8').

git_url¶: The URL for the Git API pertaining to this file.

html_url¶: The URL to open this file in a browser.

links¶: A dictionary of links returned about the contents and related resources.

name¶: The name of the file.

path¶: The path to this file.

sha¶: The SHA1 of the contents of this file.

size¶: The size of file in bytes.

submodule_git_url¶: The URL of the git submodule (if this is a git submodule).

target¶: If the file is a symlink, this will be present and provides the type of file that the symlink points to.

type¶: Type of content, e.g., 'file', 'symlink', or 'submodule'.

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

Delete this file.

Parameters:	message (str) – (required), commit message to describe the removal branch (str) – (optional), branch where the file exists. Defaults to the default branch of the repository. committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email. author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.
Returns:	dictionary of new content and associated commit
Return type:	`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)¶

Representation of a deployment of a repository at a point in time.

This object has the following attributes:

created_at¶: A datetime representing the date and time when this deployment was created.

creator¶: A ShortUser representing the user who created this deployment.

description¶: The description of this deployment as provided by the creator.

environment¶: The environment targeted for this deployment, e.g., 'production', 'staging'.

id¶: The unique identifier of this deployment.

payload¶: The JSON payload string sent as part to trigger this deployment.

ref¶: The reference used to create this deployment, e.g., 'deploy-20140526'.

sha¶: The SHA1 of the branch on GitHub when it was deployed.

statuses_url¶: The URL to retrieve the statuses of this deployment from the API.

updated_at¶: A datetime object representing the date and time when this deployment was most recently updated.

create_status(state, target_url=None, description=None)¶

Create a new deployment status for this deployment.

Parameters:	state (str) – (required), The state of the status. Can be one of `pending`, `success`, `error`, 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:	the incomplete deployment status
Return type:	`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 the statuses of this deployment
Return type:	`DeploymentStatus`

class github3.repos.deployment.DeploymentStatus(json, session)¶

Representation of the status of a deployment of a repository.

This object has the following attributes:

created_at¶: A datetime representing the date and time when this deployment status was created.

creator¶: A ShortUser representing the user who created this deployment status.

deployment_url¶: The URL to retrieve the information about the deployment from the API.

description¶: The description of this status as provided by the creator.

id¶: The unique identifier of this deployment.

state¶: The state of the deployment, e.g., 'success'.

target_url¶: The URL to associate with this status. This should link to the output of the deployment.

class github3.repos.release.Release(json, session)¶

Representation of a GitHub release.

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

Please see GitHub’s Releases Documentation for more information.

This object has the following attributes:

original_assets¶: A list of Asset objects representing the assets uploaded for this relesae.

assets_url¶: The URL to retrieve the assets from the API.

author¶: A ShortUser representing the creator of this release.

body¶: The description of this release as written by the release creator.

created_at¶: A datetime object representing the date and time when this release was created.

draft¶: A boolean attribute describing whether this release is a draft.

html_url¶: The URL to view this release in a browser.

id¶: The unique identifier of this release.

name¶: The name given to this release by the author.

prerelease¶: A boolean attribute indicating whether the release is a pre-release.

published_at¶: A datetime object representing the date and time when this release was publisehd.

tag_name¶: The name of the tag associated with this release.

tarball_url¶: The URL to retrieve a GitHub generated tarball for this release from the API.

target_commitish¶: The reference (usually a commit) that is targetted by this release.

upload_urlt¶: A URITemplate object that expands to form the URL to upload assets to.

zipball_url¶: The URL to retrieve a GitHub generated zipball for this release from the API.

archive(format, path='')¶

Get the tarball or zipball archive for this release.

Parameters:	format (str) – (required), accepted values: (‘tarball’, ‘zipball’) path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. It can take a file-like object as well
Returns:	True if successful, False otherwise
Return type:	bool

asset(asset_id)¶

Retrieve the asset from this release with asset_id.

Parameters:	asset_id (int) – ID of the Asset to retrieve
Returns:	the specified asset, if it exists
Return type:	`Asset`

assets(number=-1, etag=None)¶

Iterate over the assets available for this release.

Parameters:	number (int) – (optional), Number of assets to return etag (str) – (optional), last ETag header sent
Returns:	generator of asset objects
Return type:	`Asset`

delete()¶

Delete this release.

Only users with push access to the repository can delete a release.

Returns:	True if successful; False if not successful
Return type:	bool

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

Edit this release.

Only users with push access to the repository can edit a release.

If the edit is successful, this object will update itself.

Parameters:	tag_name (str) – (optional), Name of the tag to use target_commitish (str) – (optional), The “commitish” value that determines where the Git tag is created from. Defaults to the repository’s default branch. name (str) – (optional), Name of the release body (str) – (optional), Description of the release draft (boolean) – (optional), True => Release is a draft prerelease (boolean) – (optional), True => Release is a prerelease
Returns:	True if successful; False if not successful
Return type:	bool

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

Upload an asset to this release.

Note

All parameters are required.

Parameters:	content_type (str) – The content type of the asset. Wikipedia has a list of common media types name (str) – The name of the file asset – The file or bytes object to upload. label – (optional), An alternate short description of the asset.
Returns:	the created asset
Return type:	`Asset`

class github3.repos.release.Asset(json, session)¶

Representation of an asset in a release.