Repository API Objects

This section of the documentation covers the representations of various objects related to the Repositories API.

Repository Objects

class github3.repos.repo.Repository(json, session: GitHubSession)

This organizes the full representation of a single Repository.

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

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

allow_merge_commit

Note

This attribute is not guaranteed to be present.

Whether the repository allows creating a merge commit when merging when a pull request.

allow_rebase_merge

Note

This attribute is not guaranteed to be present.

Whether the repository allows rebasing when merging a pull request.

allow_squash_merge

Note

This attribute is not guaranteed to be present.

Whether the repository allows squashing commits when merging a pull request.

archived

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

clone_url

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

created_at

A parsed datetime object representing the date the repository was created.

default_branch

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

forks_count

This is the number of forks of the repository.

git_url

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

has_downloads

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

has_issues

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

has_pages

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

has_wiki

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

homepage

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

language

This is the language GitHub has detected for the repository.

original_license

Note

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

This is the ShortLicense returned as part of the repository. To retrieve the most recent license, see 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.

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

add_collaborator(username, permission=None)

Add username as a collaborator to a repository.

Parameters

• username (str or User) – (required), username of the user

• permission (str) – (optional), permission to grant the collaborator, valid on organization repositories only. Can be ‘pull’, ‘triage’, ‘push’, ‘maintain’, ‘admin’ or an organization-defined custom role name.

Returns

True if successful, False otherwise

Return type

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

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

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

Parameters

• format (str) – (required), accepted values: (‘tarball’, ‘zipball’)

• path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. it can take a file-like object as well

• ref (str) – (optional)

Returns

True if successful, False otherwise

Return type

bool

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns

this object’s attributes serialized to a dictionary

Return type

dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns

this object’s attributes as a JSON string

Return type

str

asset(id)

Return a single asset.

Parameters

id (int) – (required), id of the asset

Returns

the asset

Return type

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

auto_trigger_checks(app_id, enabled=True)

Change preferences for automatic creation of check suites.

New in version 1.3.0.

Enable/disable the automatic flow when creating check suites. By default, the check suite is automatically created each time code is pushed. When the automatic creation is disable they can be created manually.

Parameters

• app_id (int) – (required), the id of the GitHub App

• enabled (bool) – (optional), enable automatic creation of check suites Default: True

Returns

the check suite settings for this repository

Return type

dict

blob(sha)

Get the blob indicated by sha.

Parameters

sha (str) – (required), sha of the blob

Returns

the git blob

Return type

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

check_run(id)

Return a single check run.

New in version 1.3.0.

Parameters

id (int) – (required), id of the check run

Returns

the check run

Return type

CheckRun

check_suite(id)

Return a single check suite.

New in version 1.3.0.

Parameters

id (int) – (required), id of the check suite

Returns

the check suite

Return type

CheckSuite

clones(per='day')

Get the total number of repository clones and breakdown per day or week for the last 14 days.

New in version 1.4.0.

See also: https://developer.github.com/v3/repos/traffic/

Parameters

per (str) – (optional), (‘day’, ‘week’), clones reporting period. Default ‘day’ will return clones per day for the last 14 days.

Returns

clones data

Return type

ClonesStats

Raises

ValueError if per is not a valid choice

code_frequency(number=-1, etag=None)

Iterate over the code frequency per week.

New in version 0.7.

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

Note

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

Parameters

• number (int) – (optional), number of weeks to return. Default: -1 returns all weeks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of lists [seconds_from_epoch, additions, deletions]

Return type

list

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

Iterate over the collaborators of this repository.

Parameters

• affiliation (str) – (optional), affiliation of the collaborator to the repository. Default: “all” returns contributors with all affiliations

• number (int) – (optional), number of collaborators to return. Default: -1 returns all comments

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of collaborators

Return type

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 commits to return. Default: -1 returns all commits

• etag (str) – (optional), ETag from a previous request to the same endpoint

• since (datetime or str) – (optional), Only commits after this date will be returned. This can be 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.

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

Note

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

Parameters

• number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of contributor statistics for each contributor

Return type

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

create_branch_ref(name, sha=None)

Create a branch git reference.

This is a shortcut for calling github3.repos.repo.Repository.create_ref().

Parameters

• branch (str) – (required), the branch to create

• sha (str) – the commit to base the branch from

Returns

a reference object representing the branch

Return type

Reference

create_check_run(name, head_sha, details_url=None, external_id=None, started_at=None, status=None, conclusion=None, completed_at=None, output=None, actions=None)

Create a check run object on a commit

New in version 1.3.0.

Parameters

• name (str) – (required), The name of the check

• head_sha (str) – (required), The SHA of the commit

• details_url (str) – (optional), The URL of the integrator’s site that has the full details of the check

• external_id (str) – (optional), A reference for the run on the integrator’s system

• started_at (str) – (optional), ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ

• status (str) – (optional), (‘queued’, ‘in_progress’, ‘completed’)

• conclusion (str) – (optional), Required if you provide ‘completed_at’, or a ‘status’ of ‘completed’. The final conclusion of the check. (‘success’, ‘failure’, ‘neutral’, ‘cancelled’, ‘timed_out’, ‘action_required’)

• completed_at (str) – (optional), Required if you provide ‘conclusion’. ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ

• output (dict) – (optional), key-value pairs representing the output. Format: {'title': 'string', 'summary': 'text, can be markdown', 'text': 'text, can be markdown', 'annotations': [{}], 'images': [{}]}

• actions (list) – (optional), list of action objects. Format is: [{'label': 'text', 'description', 'text', 'identifier', 'text'}, ...]

Returns

the created check run

Return type

CheckRun

create_check_suite(head_sha)

Create a check suite object on a commit

New in version 1.3.0.

Parameters

head_sha (str) – The sha of the head commit.

Returns

the created check suite

Return type

CheckSuite

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

Create a comment on a commit.

Parameters

• body (str) – (required), body of the message

• sha (str) – (required), commit id

• path (str) – (optional), relative path of the file to comment on

• position (str) – (optional), line index in the diff to comment on

• line (int) – (optional), line number of the file to comment on, default: 1

Returns

the created comment

Return type

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.

See also: http://developer.github.com/v3/repos/contents/#create-a-file

Parameters

• path (str) – (required), path of the file in the repository

• message (str) – (required), commit message

• content (bytes) – (required), the actual data in the file

• branch (str) – (optional), branch to create the commit on. Defaults to the default branch of the repository

• committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email.

• author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.

Returns

dictionary of contents and commit for created file

Return type

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, description=None)

Create a label for this repository.

Parameters

• name (str) – (required), name to give to the label

• color (str) – (required), value of the color to assign to the label, e.g., ‘#fafafa’ or ‘fafafa’ (the latter is what is sent)

• description (str) – (optional), description to give to the label

Returns

the created label

Return type

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, maintainer_can_modify=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

• maintainer_can_modify (bool) – (optional), Indicates whether a maintainer is allowed to modify the pull request or not.

Returns

the created pull request

Return type

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:

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 optionally the date it was tagged

• lightweight (bool) – (optional), if False, create an annotated tag, otherwise create a lightweight tag (a Reference).

Returns

if creating a lightweight tag, this will return a Reference, otherwise it will return 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)]

Raises

github3.exceptions.UnprocessableResponseBody – When the requested directory is not actually a directory

edit(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, default_branch=None, archived=None, allow_merge_commit=None, allow_squash_merge=None, allow_rebase_merge=None, has_projects=None)

Edit this repository.

Parameters

• name (str) – (required), name of the repository

• description (str) – (optional), If not None, change the description for this repository. API default: None - leave value unchanged.

• homepage (str) – (optional), If not None, change the homepage for this repository. API default: None - leave value unchanged.

• private (bool) – (optional), If True, make the repository private. 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.

• allow_rebase_merge (bool) – (optional), If not None, change whether the merge strategy that allows adding all commits from the head branch onto the base branch individually is enabled for this repository. API default: None - leave value unchanged.

• allow_squash_merge (bool) – (optional), If not None, change whether combining all commits from the head branch into a single commit in the base branch is allowed. API default: None - leave value unchanged.

• allow_merge_commit (bool) – (optional), If not None, change whether adding all commits from the head branch to the base branch with a merge commit is allowed. API default: None - leave value unchanged.

• has_projects (bool) – (optional), If True, enable projects for this repository. If False, disable projects projects for this repository. API default: None - leave value unchanged.

Returns

True if successful, False otherwise

Return type

bool

events(number=-1, etag=None)

Iterate over events on this repository.

Parameters

• number (int) – (optional), number of events to return. Default: -1 returns all available events

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of events

Return type

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’, ‘stargazers’), API default: ‘newest’

• number (int) – (optional), number of forks to return. Default: -1 returns all forks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of forks of this repository

Return type

ShortRepository

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

git_commit(sha)

Get a single (git) commit.

Parameters

sha (str) – (required), sha of the commit

Returns

the single commit data from git

Return type

Commit

hook(hook_id)

Get a single hook.

Parameters

hook_id (int) – (required), id of the hook

Returns

the hook

Return type

Hook

hooks(number=-1, etag=None)

Iterate over hooks registered on this repository.

Parameters

• number (int) – (optional), number of hoks to return. Default: -1 returns all hooks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of hooks

Return type

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.

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

Parameters

• title (string) – (required) Title of issue

• body (string) – (required) Body of issue

• created_at (datetime or str) – (required) Creation timestamp

• assignee (string) – (optional) Username to assign issue to

• milestone (int) – (optional) Milestone ID

• closed (boolean) – (optional) Status of issue is Closed if True

• labels (list) – (optional) List of labels containing string names

• comments (list) – (optional) List of dictionaries which contain created_at and body attributes

Returns

the imported issue

Return type

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.

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

Parameters

• number (int) – (optional), number of imported issues to return. Default: -1 returns all branches

• since – (optional), Only imported issues after this date will be returned. This can be a datetime instance, ISO8601 formatted date string, or a string formatted like so: 2016-02-04 i.e. %Y-%m-%d

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of imported issues

Return type

ImportedIssue

invitations(number=-1, etag=None)

Iterate over the invitations to this repository.

Parameters

• number (int) – (optional), number of invitations to return. Default: -1 returns all available invitations

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of repository invitation objects

Return type

Invitation

is_assignee(username)

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

Parameters

username (str or User) – name of the user to check

Returns

bool

is_collaborator(username)

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

Parameters

username (str or User) – (required), login for the user

Returns

True if successful, False otherwise

Return type

bool

issue(number)

Get the issue specified by number.

Parameters

number (int) – (required), number of the issue on this repository

Returns

the issue

Return type

Issue

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

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

readme()

Get the README for this repository.

Returns

this repository’s readme

Return type

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: bool = False) → GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

Parameters

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

Returns

self

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

Iterate over references for this repository.

Parameters

• subspace (str) – (optional), e.g. ‘tags’, ‘stashes’, ‘notes’

• number (int) – (optional), number of refs to return. Default: -1 returns all available refs

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of references

Return type

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

replace_topics(new_topics)

Replace the repository topics with new_topics.

Parameters

topics (list) – (required), new topics of the repository

Returns

new topics of the repository

Return type

Topics

stargazers(number=-1, etag=None)

List users who have starred this repository.

Parameters

• number (int) – (optional), number of stargazers to return. Default: -1 returns all subscribers available

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of users

Return type

Stargazer

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

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

topics()

Get the topics of this repository.

Returns

this repository’s topics

Return type

Topics

tree(sha, recursive=False)

Get a tree.

Parameters

• sha (str) – (required), sha of the object for this tree

• recursive (bool) – (optional), whether to fetch the tree recursively

Returns

the tree

Return type

Tree

unignore()

Unignore notifications from this repository for the user.

New in version 1.3.

This replaces Repository#set_subscription.

Returns

the new repository subscription

Return type

:class:~github3.notifications.RepositorySubscription`

unsubscribe()

Unsubscribe the user to this repository’s notifications.

New in version 1.3.

This replaces Repository#set_subscription

Returns

the new repository subscription

Return type

RepositorySubscription

views(per='day')

Get the total number of repository views and breakdown per day or week for the last 14 days.

New in version 1.4.0.

See also: https://developer.github.com/v3/repos/traffic/

Parameters

per (str) – (optional), (‘day’, ‘week’), views reporting period. Default ‘day’ will return views per day for the last 14 days.

Returns

views data

Return type

ViewsStats

Raises

ValueError if per is not a valid choice

weekly_commit_count()

Retrieve the total commit counts.

Note

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

..versionadded:: 0.7

The dictionary returned has two entries: all 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.ShortRepository(json, session: GitHubSession)

This represents a Repository object returned in collections.

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

This object only has the following attributes:

url

The GitHub API URL for this repository, e.g., https://api.github.com/repos/sigmavirus24/github3.py.

archive_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check archive_urlt.variables for the list of variables that can be passed to archive_urlt.expand().

assignees_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check assignees_urlt.variables for the list of variables that can be passed to assignees_urlt.expand().

blobs_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check blobs_urlt.variables for the list of variables that can be passed to blobs_urlt.expand().

branches_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check branches_urlt.variables for the list of variables that can be passed to branches_urlt.expand().

collaborators_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check collaborators_urlt.variables for the list of variables that can be passed to collaborators_urlt.expand().

comments_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check comments_urlt.variables for the list of variables that can be passed to comments_urlt.expand().

commits_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check commits_urlt.variables for the list of variables that can be passed to commits_urlt.expand().

compare_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check compare_urlt.variables for the list of variables that can be passed to compare_urlt.expand().

contents_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check contents_urlt.variables for the list of variables that can be passed to contents_urlt.expand().

contributors_url

The URL to retrieve this repository’s list of contributors.

deployments_url

The URL to retrieve this repository’s list of deployments.

description

The administrator created description of the repository.

downloads_url

The URL to retrieve this repository’s list of downloads.

events_url

The URL to retrieve this repository’s list of events.

fork

Whether or not this repository is a fork of another.

forks_url

The URL to retrieve this repository’s list of forks.

full_name

The full name of this repository, e.g., sigmavirus24/github3.py.

git_commits_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check git_commits_urlt.variables for the list of variables that can be passed to git_commits_urlt.expand().

git_refs_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check git_refs_urlt.variables for the list of variables that can be passed to git_refs_urlt.expand().

git_tags_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check git_tags_urlt.variables for the list of variables that can be passed to git_tags_urlt.expand().

hooks_url

The URL to retrieve this repository’s list of hooks.

html_url

The HTML URL of this repository, e.g., https://github.com/sigmavirus24/github3.py.

id

The unique GitHub assigned numerical id of this repository.

issue_comment_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check issue_comment_urlt.variables for the list of variables that can be passed to issue_comment_urlt.expand().

issue_events_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check issue_events_urlt.variables for the list of variables that can be passed to issue_events_urlt.expand().

issues_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check issues_urlt.variables for the list of variables that can be passed to issues_urlt.expand().

keys_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check keys_urlt.variables for the list of variables that can be passed to keys_urlt.expand().

labels_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check labels_urlt.variables for the list of variables that can be passed to labels_urlt.expand().

languages_url

The URL to retrieve this repository’s list of languages.

merges_url

The URL to retrieve this repository’s list of merges.

milestones_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check milestones_urlt.variables for the list of variables that can be passed to milestones_urlt.expand().

name

The name of the repository, e.g., github3.py.

notifications_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check notifications_urlt.variables for the list of variables that can be passed to notifications_urlt.expand().

owner

A ShortUser object representing the owner of the repository.

private

Whether the repository is private or public.

pulls_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check pulls_urlt.variables for the list of variables that can be passed to pulls_urlt.expand().

releases_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check releases_urlt.variables for the list of variables that can be passed to releases_urlt.expand().

stargazers_url

The URL to retrieve this repository’s list of stargazers.

statuses_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check statuses_urlt.variables for the list of variables that can be passed to statuses_urlt.expand().

subscribers_url

The URL to retrieve this repository’s list of subscribers.

subscription_url

The URL to modify subscription to this repository.

tags_url

The URL to retrieve this repository’s list of tags.

teams_url

The URL to retrieve this repository’s list of teams.

trees_urlt

The URITemplate object representing the URI template returned by GitHub’s API. Check trees_urlt.variables for the list of variables that can be passed to trees_urlt.expand().

New in version 1.0.0.

add_collaborator(username, permission=None)

Add username as a collaborator to a repository.

Parameters

• username (str or User) – (required), username of the user

• permission (str) – (optional), permission to grant the collaborator, valid on organization repositories only. Can be ‘pull’, ‘triage’, ‘push’, ‘maintain’, ‘admin’ or an organization-defined custom role name.

Returns

True if successful, False otherwise

Return type

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

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

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

Parameters

• format (str) – (required), accepted values: (‘tarball’, ‘zipball’)

• path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. it can take a file-like object as well

• ref (str) – (optional)

Returns

True if successful, False otherwise

Return type

bool

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns

this object’s attributes serialized to a dictionary

Return type

dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns

this object’s attributes as a JSON string

Return type

str

asset(id)

Return a single asset.

Parameters

id (int) – (required), id of the asset

Returns

the asset

Return type

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

auto_trigger_checks(app_id, enabled=True)

Change preferences for automatic creation of check suites.

New in version 1.3.0.

Enable/disable the automatic flow when creating check suites. By default, the check suite is automatically created each time code is pushed. When the automatic creation is disable they can be created manually.

Parameters

• app_id (int) – (required), the id of the GitHub App

• enabled (bool) – (optional), enable automatic creation of check suites Default: True

Returns

the check suite settings for this repository

Return type

dict

blob(sha)

Get the blob indicated by sha.

Parameters

sha (str) – (required), sha of the blob

Returns

the git blob

Return type

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

check_run(id)

Return a single check run.

New in version 1.3.0.

Parameters

id (int) – (required), id of the check run

Returns

the check run

Return type

CheckRun

check_suite(id)

Return a single check suite.

New in version 1.3.0.

Parameters

id (int) – (required), id of the check suite

Returns

the check suite

Return type

CheckSuite

clones(per='day')

Get the total number of repository clones and breakdown per day or week for the last 14 days.

New in version 1.4.0.

See also: https://developer.github.com/v3/repos/traffic/

Parameters

per (str) – (optional), (‘day’, ‘week’), clones reporting period. Default ‘day’ will return clones per day for the last 14 days.

Returns

clones data

Return type

ClonesStats

Raises

ValueError if per is not a valid choice

code_frequency(number=-1, etag=None)

Iterate over the code frequency per week.

New in version 0.7.

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

Note

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

Parameters

• number (int) – (optional), number of weeks to return. Default: -1 returns all weeks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of lists [seconds_from_epoch, additions, deletions]

Return type

list

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

Iterate over the collaborators of this repository.

Parameters

• affiliation (str) – (optional), affiliation of the collaborator to the repository. Default: “all” returns contributors with all affiliations

• number (int) – (optional), number of collaborators to return. Default: -1 returns all comments

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of collaborators

Return type

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 commits to return. Default: -1 returns all commits

• etag (str) – (optional), ETag from a previous request to the same endpoint

• since (datetime or str) – (optional), Only commits after this date will be returned. This can be 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.

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

Note

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

Parameters

• number (int) – (optional), number of weeks to return. Default -1 will return all of the weeks.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of contributor statistics for each contributor

Return type

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

create_branch_ref(name, sha=None)

Create a branch git reference.

This is a shortcut for calling github3.repos.repo.Repository.create_ref().

Parameters

• branch (str) – (required), the branch to create

• sha (str) – the commit to base the branch from

Returns

a reference object representing the branch

Return type

Reference

create_check_run(name, head_sha, details_url=None, external_id=None, started_at=None, status=None, conclusion=None, completed_at=None, output=None, actions=None)

Create a check run object on a commit

New in version 1.3.0.

Parameters

• name (str) – (required), The name of the check

• head_sha (str) – (required), The SHA of the commit

• details_url (str) – (optional), The URL of the integrator’s site that has the full details of the check

• external_id (str) – (optional), A reference for the run on the integrator’s system

• started_at (str) – (optional), ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ

• status (str) – (optional), (‘queued’, ‘in_progress’, ‘completed’)

• conclusion (str) – (optional), Required if you provide ‘completed_at’, or a ‘status’ of ‘completed’. The final conclusion of the check. (‘success’, ‘failure’, ‘neutral’, ‘cancelled’, ‘timed_out’, ‘action_required’)

• completed_at (str) – (optional), Required if you provide ‘conclusion’. ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ

• output (dict) – (optional), key-value pairs representing the output. Format: {'title': 'string', 'summary': 'text, can be markdown', 'text': 'text, can be markdown', 'annotations': [{}], 'images': [{}]}

• actions (list) – (optional), list of action objects. Format is: [{'label': 'text', 'description', 'text', 'identifier', 'text'}, ...]

Returns

the created check run

Return type

CheckRun

create_check_suite(head_sha)

Create a check suite object on a commit

New in version 1.3.0.

Parameters

head_sha (str) – The sha of the head commit.

Returns

the created check suite

Return type

CheckSuite

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

Create a comment on a commit.

Parameters

• body (str) – (required), body of the message

• sha (str) – (required), commit id

• path (str) – (optional), relative path of the file to comment on

• position (str) – (optional), line index in the diff to comment on

• line (int) – (optional), line number of the file to comment on, default: 1

Returns

the created comment

Return type

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.

See also: http://developer.github.com/v3/repos/contents/#create-a-file

Parameters

• path (str) – (required), path of the file in the repository

• message (str) – (required), commit message

• content (bytes) – (required), the actual data in the file

• branch (str) – (optional), branch to create the commit on. Defaults to the default branch of the repository

• committer (dict) – (optional), if no information is given the authenticated user’s information will be used. You must specify both a name and email.

• author (dict) – (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email.

Returns

dictionary of contents and commit for created file

Return type

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, description=None)

Create a label for this repository.

Parameters

• name (str) – (required), name to give to the label

• color (str) – (required), value of the color to assign to the label, e.g., ‘#fafafa’ or ‘fafafa’ (the latter is what is sent)

• description (str) – (optional), description to give to the label

Returns

the created label

Return type

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, maintainer_can_modify=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

• maintainer_can_modify (bool) – (optional), Indicates whether a maintainer is allowed to modify the pull request or not.

Returns

the created pull request

Return type

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:

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 optionally the date it was tagged

• lightweight (bool) – (optional), if False, create an annotated tag, otherwise create a lightweight tag (a Reference).

Returns

if creating a lightweight tag, this will return a Reference, otherwise it will return 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)]

Raises

github3.exceptions.UnprocessableResponseBody – When the requested directory is not actually a directory

edit(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, default_branch=None, archived=None, allow_merge_commit=None, allow_squash_merge=None, allow_rebase_merge=None, has_projects=None)

Edit this repository.

Parameters

• name (str) – (required), name of the repository

• description (str) – (optional), If not None, change the description for this repository. API default: None - leave value unchanged.

• homepage (str) – (optional), If not None, change the homepage for this repository. API default: None - leave value unchanged.

• private (bool) – (optional), If True, make the repository private. 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.

• allow_rebase_merge (bool) – (optional), If not None, change whether the merge strategy that allows adding all commits from the head branch onto the base branch individually is enabled for this repository. API default: None - leave value unchanged.

• allow_squash_merge (bool) – (optional), If not None, change whether combining all commits from the head branch into a single commit in the base branch is allowed. API default: None - leave value unchanged.

• allow_merge_commit (bool) – (optional), If not None, change whether adding all commits from the head branch to the base branch with a merge commit is allowed. API default: None - leave value unchanged.

• has_projects (bool) – (optional), If True, enable projects for this repository. If False, disable projects projects for this repository. API default: None - leave value unchanged.

Returns

True if successful, False otherwise

Return type

bool

events(number=-1, etag=None)

Iterate over events on this repository.

Parameters

• number (int) – (optional), number of events to return. Default: -1 returns all available events

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of events

Return type

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’, ‘stargazers’), API default: ‘newest’

• number (int) – (optional), number of forks to return. Default: -1 returns all forks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of forks of this repository

Return type

ShortRepository

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

git_commit(sha)

Get a single (git) commit.

Parameters

sha (str) – (required), sha of the commit

Returns

the single commit data from git

Return type

Commit

hook(hook_id)

Get a single hook.

Parameters

hook_id (int) – (required), id of the hook

Returns

the hook

Return type

Hook

hooks(number=-1, etag=None)

Iterate over hooks registered on this repository.

Parameters

• number (int) – (optional), number of hoks to return. Default: -1 returns all hooks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of hooks

Return type

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.

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

Parameters

• title (string) – (required) Title of issue

• body (string) – (required) Body of issue

• created_at (datetime or str) – (required) Creation timestamp

• assignee (string) – (optional) Username to assign issue to

• milestone (int) – (optional) Milestone ID

• closed (boolean) – (optional) Status of issue is Closed if True

• labels (list) – (optional) List of labels containing string names

• comments (list) – (optional) List of dictionaries which contain created_at and body attributes

Returns

the imported issue

Return type

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.

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

Parameters

• number (int) – (optional), number of imported issues to return. Default: -1 returns all branches

• since – (optional), Only imported issues after this date will be returned. This can be a datetime instance, ISO8601 formatted date string, or a string formatted like so: 2016-02-04 i.e. %Y-%m-%d

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of imported issues

Return type

ImportedIssue

invitations(number=-1, etag=None)

Iterate over the invitations to this repository.

Parameters

• number (int) – (optional), number of invitations to return. Default: -1 returns all available invitations

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of repository invitation objects

Return type

Invitation

is_assignee(username)

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

Parameters

username (str or User) – name of the user to check

Returns

bool

is_collaborator(username)

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

Parameters

username (str or User) – (required), login for the user

Returns

True if successful, False otherwise

Return type

bool

issue(number)

Get the issue specified by number.

Parameters

number (int) – (required), number of the issue on this repository

Returns

the issue

Return type

Issue

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

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

readme()

Get the README for this repository.

Returns

this repository’s readme

Return type

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: bool = False) → GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

Parameters

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

Returns

self

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

Iterate over references for this repository.

Parameters

• subspace (str) – (optional), e.g. ‘tags’, ‘stashes’, ‘notes’

• number (int) – (optional), number of refs to return. Default: -1 returns all available refs

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of references

Return type

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

replace_topics(new_topics)

Replace the repository topics with new_topics.

Parameters

topics (list) – (required), new topics of the repository

Returns

new topics of the repository

Return type

Topics

stargazers(number=-1, etag=None)

List users who have starred this repository.

Parameters

• number (int) – (optional), number of stargazers to return. Default: -1 returns all subscribers available

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns

generator of users

Return type

Stargazer

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

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

topics()

Get the topics of this repository.

Returns

this repository’s topics

Return type

Topics

tree(sha, recursive=False)

Get a tree.

Parameters

• sha (str) – (required), sha of the object for this tree

• recursive (bool) – (optional), whether to fetch the tree recursively

Returns

the tree

Return type

Tree

unignore()

Unignore notifications from this repository for the user.

New in version 1.3.

This replaces Repository#set_subscription.

Returns

the new repository subscription

Return type

:class:~github3.notifications.RepositorySubscription`

unsubscribe()

Unsubscribe the user to this repository’s notifications.

New in version 1.3.

This replaces Repository#set_subscription

Returns

the new repository subscription

Return type

RepositorySubscription

views(per='day')

Get the total number of repository views and breakdown per day or week for the last 14 days.

New in version 1.4.0.

See also: https://developer.github.com/v3/repos/traffic/

Parameters

per (str) – (optional), (‘day’, ‘week’), views reporting period. Default ‘day’ will return views per day for the last 14 days.

Returns

views data

Return type

ViewsStats

Raises

ValueError if per is not a valid choice

weekly_commit_count()

Retrieve the total commit counts.

Note

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

..versionadded:: 0.7

The dictionary returned has two entries: all 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: GitHubSession)

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

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

Attributes:

starred_at

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

repository

The Repository that was starred by the user.

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

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns

this object’s attributes serialized to a dictionary

Return type

dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns

this object’s attributes as a JSON string

Return type

str

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

new_session()

Generate a new session.

Returns

A brand new session

Return type

GitHubSession

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

Parameters

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

Returns

self

class github3.repos.contents.Contents(json, session: GitHubSession)

A representation of file contents returned via the API.

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

This object has the following attributes:

content

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

encoding

The encoding used on the content when returning the data from the API, e.g., base64. 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.hook.Hook(json, session: GitHubSession)

The representation of a hook on a repository.

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

This object has the following attributes:

active

A boolean attribute describing whether the hook is active or not.

config

A dictionary containing the configuration for this hook.

created_at

A datetime object representing the date and time when this hook was created.

events

The list of events which trigger this hook.

id

The unique identifier for this hook.

name

The name provided to this hook.

updated_at

A datetime object representing the date and time when this hook was updated.

delete()

Delete this hook.

Returns

True if successful, False otherwise

Return type

bool

edit(config={}, events=[], add_events=[], rm_events=[], active=True)

Edit this hook.

Parameters

• config (dict) – (optional), key-value pairs of settings for this hook

• events (list) – (optional), which events should this be triggered for

• add_events (list) – (optional), events to be added to the list of events that this hook triggers for

• rm_events (list) – (optional), events to be removed from the list of events that this hook triggers for

• active (bool) – (optional), should this event be active

Returns

True if successful, False otherwise

Return type

bool

ping()

Ping this hook.

Returns

True if successful, False otherwise

Return type

bool

test()

Test this hook.

Returns

True if successful, False otherwise

Return type

bool

class github3.repos.issue_import.ImportedIssue(json, session: GitHubSession)

Represents an issue imported via the unofficial API.

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

This object has the following attributes:

created_at

A datetime object representing the date and time when this imported issue was created.

id

The globally unique identifier for this imported issue.

import_issues_url

The URL used to import more issues via the API.

repository_url

The URL used to retrieve the repository via the API.

status

The status of this imported issue.

updated_at

A datetime object representing te date and time when this imported issue was last updated.

Git-related Objects

class github3.repos.tag.RepoTag(json, session: GitHubSession)

Representation of a tag made on a GitHub repository.

Note

This is distinct from Tag. This object has information specific to a tag on a GitHub repository. That includes URLs to the tarball and zipball files auto-generated by GitHub.

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

This object has the following attributes:

commit

Changed in version 1.0.0: This attribute used to be a two item dictionary.

A MiniCommit object representing the commit this tag references.

name

The name of this tag, e.g., v1.0.0.

tarball_url

The URL for the tarball file generated by GitHub for this tag.

zipball_url

The URL for the zipball file generated by GitHub for this tag.

Branches

class github3.repos.branch.Branch(json, session: GitHubSession)

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.branch.ShortBranch(json, session: GitHubSession)

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 following attributes:

commit

A MiniCommit representation of the newest commit on this branch with the associated repository metadata.

name

The name of this branch.

refresh(conditional: bool = False) → Branch

Helper for @overload to raise when called.

class github3.repos.branch.BranchProtection(json, session: GitHubSession)

The representation of a branch’s protection.

See also

Branch protection API documentation

GitHub’s documentation of branch protection

Changed in version 3.0.0: Added required_linear_history, allow_force_pushes, allow_deletions, and required_conversation_resolution.

This object has the following attributes:

enforce_admins

A ProtectionEnforceAdmins instance representing whether required status checks are required for admins.

restrictions

A ProtectionRestrictions representing who can push to this branch. Team and user restrictions are only available for organization-owned repositories.

required_pull_request_reviews

A ProtectionRequiredPullRequestReviews representing the protection provided by requiring pull request reviews.

required_status_checks

A ProtectionRequiredStatusChecks representing the protection provided by requiring status checks.

required_linear_history

New in version 3.0.0.

A ProtectionRequiredLinearHistory representing the information returned by the API about this protection.

allow_force_pushes

New in version 3.0.0.

A ProtectionAllowForcePushes representing the information returned by the API about this protection.

allow_deletions

New in version 3.0.0.

A ProtectionAllowDeletions representing the information returned by the API about this protection.

required_conversation_resolution

New in version 3.0.0.

A ProtectionRequiredConversationResolution representing the information returned by the API about this protection.

delete() → bool

Remove branch protection.

Returns

True if successful, False otherwise

Return type

bool

delete_signature_requirements() → bool

Stop requiring commit signatures for commits to this branch.

Returns

True if successful, False otherwise

Return type

bool

require_signatures() → bool

Require commit signatures for commits to this branch.

Returns

True if successful, False otherwise

Return type

bool

requires_signatures() → bool

Check if commit signatures are presently required.

Returns

True if enabled, False otherwise

Return type

bool

update(enforce_admins=None, required_status_checks=None, required_pull_request_reviews=None, restrictions=None)

Enable force push protection and configure status check enforcement.

See: http://git.io/v4Gvu

Parameters

• enforce_admins (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.

• required_status_checks (list) – (optional), A list of strings naming status checks that must pass before merging. Use None or omit to use the already associated value.

• required_pull_request_reviews (obj) – (optional), Object representing the configuration of Request Pull Request Reviews settings. Use None or omit to use the already associated value.

• restrictions (obj) – (optional), Object representing the configuration of Restrictions. Use None or omit to use the already associated value.

Returns

Updated branch protection

Return type

BranchProtection

class github3.repos.branch.ProtectionEnforceAdmins(json, session: GitHubSession)

The representation of a sub-portion of branch protection.

See also

Branch protection API documentation

GitHub’s documentation of branch protection

Admin enforcement of protected branch

GitHub’s documentation of protecting a branch with admins

This object has the following attributes:

enabled

A boolean attribute indicating whether the enforce_admins protection is enabled or disabled.

disable()

Disable Admin enforcement for protected branch.

enable()

Enable Admin enforcement for protected branch.

class github3.repos.branch.ProtectionRestrictions(json, session: GitHubSession)

The representation of a sub-portion of branch protection.

See also

Branch protection API documentation

GitHub’s documentation of branch protection

Branch restriction documentation

GitHub’s description of branch restriction

This object has the following attributes:

original_teams

List of ShortTeam objects representing the teams allowed to push to the protected branch.

original_users

List of ShortUser objects representing the users allowed to push to the protected branch.

teams_url

The URL to retrieve the list of teams allowed to push to the protected branch.

users_url

The URL to retrieve the list of users allowed to push to the protected branch.

add_app_restrictions(apps: Sequence[Union[tapps.App, str]]) → List[tapps.App]

Grant app push access to the current branch.

See https://docs.github.com/en/rest/reference/repos#add-app-access-restrictions

Per GitHub’s documentation above:

Grants the specified apps push access for this branch. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch.

Parameters

apps (list) – List of slugs of apps to grant push access to the protected branch. If you pass a list of App then the library will retrieve the slug for you.

Returns

List of apps with push access to the protected branch

Return type

List[App]

add_teams(teams: Sequence[str]) → Sequence[orgs.ShortTeam]

Add teams to the protected branch.

See: https://developer.github.com/v3/repos/branches/#add-team-restrictions-of-protected-branch

Warning

This will not update the object to replace the original_teams attribute.

Parameters

teams (list) – The list of the team names to have access to interact with protected branch.

Returns

List of added teams

Return type

List[github3.orgs.ShortTeam]

add_users(users: Sequence[str]) → Sequence[tusers.ShortUser]

Add users to protected branch.

See https://developer.github.com/v3/repos/branches/#add-user-restrictions-of-protected-branch

Warning

This will not update the object to replace the original_users attribute.

Parameters

users (list) – The list of the user logins to have access to interact with protected branch.

Returns

List of added users

Return type

List[github3.users.ShortUser]

apps(number: int = -1) → Generator[tapps.App, None, None]

Retrieve current list of apps with access to the protected branch.

See https://docs.github.com/en/rest/reference/repos#get-apps-with-access-to-the-protected-branch

Warning

This will not update the object to replace the original_apps attribute.

Parameters

number (int) – Limit the number of apps returned

Returns

An iterator of apps

Return type

App

delete() → bool

Completely remove restrictions of the protected branch.

See https://developer.github.com/v3/repos/branches/#remove-user-restrictions-of-protected-branch

Returns

True if successful, False otherwise.

Return type

bool

remove_app_restrictions(apps: Sequence[Union[tapps.App, str]]) → List[tapps.App]

Remove the apps’ push access to the protected branch.

See https://docs.github.com/en/rest/reference/repos#remove-app-access-restrictions

Parameters

apps (list) – List of slugs of apps to revoke push access to the protected branch. If you pass a list of App then the library will retrieve the slug for you.

Returns

List of apps that still have push access

Return type

List[App]

remove_teams(teams: Sequence[str]) → Sequence[orgs.ShortTeam]

Remove teams from protected branch.

See https://developer.github.com/v3/repos/branches/#remove-team-restrictions-of-protected-branch

Parameters

teams (list) – The list of the team names to stop having access to interact with protected branch.

Returns

List of removed teams

Return type

List[github3.orgs.ShortTeam]

remove_users(users: Sequence[str]) → Sequence[tusers.ShortUser]

Remove users from protected branch.

See https://developer.github.com/v3/repos/branches/#remove-user-restrictions-of-protected-branch

Parameters

users (list) – The list of the user logins to stop having access to interact with protected branch.

Returns

List of removed users

Return type

List[github3.users.ShortUser]

replace_app_restrictions(apps: Sequence[Union[tapps.App, str]]) → List[tapps.App]

Replace existing app push access with only those specified.

See https://docs.github.com/en/rest/reference/repos#set-app-access-restrictions

Per GitHub’s documentation above:

Replaces the list of apps that have push access to this branch. This removes all apps that previously had push access and grants push access to the new list of apps. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch.

Parameters

apps (list) – List of slugs of apps to grant push access to the protected branch. If you pass a list of App then the library will retrieve the slug for you.

Returns

List of apps with push access to the protected branch

Return type

List[App]

replace_teams(teams: Sequence[str]) → Sequence[orgs.ShortTeam]

Replace teams that will have access to protected branch.

See https://developer.github.com/v3/repos/branches/#replace-team-restrictions-of-protected-branch

Parameters

teams (list) – The list of the team names to have access to interact with protected branch.

Returns

List of teams that now have access to the protected branch

Return type

List[github3.orgs.ShortTeam]

replace_users(users: Sequence[str]) → Sequence[tusers.ShortUser]

Replace users that will have access to protected branch.

See https://developer.github.com/v3/repos/branches/#replace-user-restrictions-of-protected-branch

Parameters

users (list) – The list of the user logins to have access to interact with protected branch.

Returns

List of users that now have access to the protected branch

Return type

List[github3.users.ShortUser]

teams(number: int = -1) → Generator[orgs.ShortTeam, None, None]

Retrieve an up-to-date listing of teams.

Returns

An iterator of teams

Return type

ShortTeam

users(number: int = -1) → Generator[tusers.ShortUser, None, None]

Retrieve an up-to-date listing of users.

Returns

An iterator of users

Return type

ShortUser

class github3.repos.branch.ProtectionRequiredPullRequestReviews(json, session: GitHubSession)

The representation of a sub-portion of branch protection.

See also

Branch protection API documentation

GitHub’s documentation of branch protection.

Branch Required Pull Request Reviews

GitHub’s documentation of required pull request review protections

This object has the folllowing attributes:

dismiss_stale_reviews

A boolean attribute describing whether stale pull request reviews should be automatically dismissed by GitHub.

dismissal_restrictions

If specified, a ProtectionRestrictions object describing the dismissal restrictions for pull request reviews.

require_code_owner_reviews

A boolean attribute describing whether to require “code owners” to review a pull request before it may be merged.

required_approving_review_count

An integer describing the number (between 1 and 6) of reviews required before a pull request may be merged.

delete()

Remove the Required Pull Request Reviews.

Returns

Whether the operation finished successfully or not

Return type

bool

update(dismiss_stale_reviews=None, require_code_owner_reviews=None, required_approving_review_count=None, dismissal_restrictions=None)

Update the configuration for the Required Pull Request Reviews.

Parameters

• dismiss_stale_reviews (bool) – Whether or not to dismiss stale pull request reviews automatically

• require_code_owner_reviews (bool) – Blocks merging pull requests until code owners review them

• required_approving_review_count (int) – The number of reviewers required to approve pull requests. Acceptable values are between 1 and 6.

• dismissal_restrictions (dict) – An empty dictionary will disable this. This must have the following keys: users and teams each mapping to a list of user logins and team slugs respectively.

Returns

A updated instance of the required pull request reviews.

Return type

ProtectionRequiredPullRequestReviews

class github3.repos.branch.ProtectionRequiredStatusChecks(json, session: GitHubSession)

The representation of a sub-portion of branch protection.

See also

Branch protection API documentation

GitHub’s documentation of branch protection

Required Status Checks documentation

GitHub’s description of required status checks

Required Status Checks API documentation

The API documentation for required status checks

add_contexts(contexts)

Add contexts to the existing list of required contexts.

See: https://developer.github.com/v3/repos/branches/#add-required-status-checks-contexts-of-protected-branch

Parameters

contexts (list) – The list of contexts to append to the existing list.

Returns

The updated list of contexts.

Return type

list

contexts()

Retrieve the list of contexts required as status checks.

See: https://developer.github.com/v3/repos/branches/#list-required-status-checks-contexts-of-protected-branch

Returns

A list of context names which are required status checks.

Return type

list

delete()

Remove required status checks from this branch.

See: https://developer.github.com/v3/repos/branches/#remove-required-status-checks-of-protected-branch

Returns

True if successful, False otherwise

Return type

bool

delete_contexts(contexts)

Delete the contexts required as status checks.

See https://developer.github.com/v3/repos/branches/#replace-required-status-checks-contexts-of-protected-branch

Parameters

contexts (list) – The names of the contexts to be required as status checks

Returns

The updated list of contexts required as status checks.

Return type

list

remove_contexts(contexts)

Remove the specified contexts from the list of required contexts.

See: https://developer.github.com/v3/repos/branches/#remove-required-status-checks-contexts-of-protected-branch

Parameters

contexts (list) – The context names to remove

Returns

The updated list of contexts required as status checks.

Return type

list

replace_contexts(contexts)

Replace the existing contexts required as status checks.

See https://developer.github.com/v3/repos/branches/#replace-required-status-checks-contexts-of-protected-branch

Parameters

contexts (list) – The names of the contexts to be required as status checks

Returns

The new list of contexts required as status checks.

Return type

list

update(strict=None, contexts=None)

Update required status checks for the branch.

This requires admin or owner permissions to the repository and branch protection to be enabled.

See also

API docs

Descrption of how to update the required status checks.

Parameters

• strict (bool) – Whether this should be strict protection or not.

• contexts (list) – A list of context names that should be required.

Returns

A new instance of this class with the updated information

Return type

ProtectionRequiredStatusChecks

Commits

class github3.repos.commit.MiniCommit(json, session: GitHubSession)

A commit returned on a ShortBranch.

class github3.repos.commit.ShortCommit(json, session: GitHubSession)

Representation of an incomplete commit in a collection.

class github3.repos.commit.RepoCommit(json, session: GitHubSession)

Representation of a commit with repository and git data.

class github3.repos.comparison.Comparison(json, session: GitHubSession)

A representation of a comparison between two or more commit objects.

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

This object has the following attributes:

.. attribute:: ahead_by

The number of commits between the head and base commit.

base_commit

A ShortCommit representing the base commit in this comparison.

behind_by

The number of commits the head commit is behind the base.

commits

A list of ShortCommit objects representing the commits in the comparison.

diff_url

The URL to retrieve the diff between the head and base commits.

files

A list of dictionaries describing each of the modified files in the comparison.

html_url

The URL to view the comparison in a browser.

patch_url

The URL to retrieve the patch-formatted diff of this comparison.

permalink_url

The permanent URL to retrieve this comparison.

status

Whether the head commit is ahead or behind of base.

total_commits

The total number of commits difference.

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

Release Objects

class github3.repos.release.Asset(json, session: GitHubSession)

Representation of an asset in a release.

See also

List Assets, assets()

Documentation around listing assets of a release

Upload Assets, upload_asset()

Documentation around uploading assets to a release

Get a Single Asset, asset()

Documentation around retrieving an asset

Edit an Asset, edit()

Documentation around editing an asset

Delete an Asset, delete()

Documentation around deleting an asset

This object has the following attributes:

browser_download_url

The user-friendly URL to download this asset via a browser.

content_type

The Content-Type provided by the uploader when this asset was created.

created_at

A datetime object representing the date and time when this asset was created.

download_count

The number of times this asset has been downloaded.

download_url

The URL to retrieve this uploaded asset via the API, e.g., tarball, zipball, etc.

id

The unique identifier of this asset.

label

The short description of this asset.

name

The name provided to this asset.

size

The file size of this asset.

state

The state of this asset, e.g., 'uploaded'.

updated_at

A datetime object representing the date and time when this asset was most recently updated.

delete()

Delete this asset if the user has push access.

Returns

True if successful; False if not successful

Return type

bool

download(path='')

Download the data for this asset.

Parameters

path (str, file) – (optional), path where the file should be saved to, default is the filename provided in the headers and will be written in the current directory. It can take a file-like object as well

Returns

name of the file, if successful otherwise None

Return type

str

edit(name, label=None)

Edit this asset.

Parameters

• name (str) – (required), The file name of the asset

• label (str) – (optional), An alternate description of the asset

Returns

True if successful, False otherwise

Return type

bool

class github3.repos.release.Release(json, session: GitHubSession)

Representation of a GitHub release.

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

Please see GitHub’s Releases Documentation for more information.

This object has the following attributes:

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

Pages Objects

class github3.repos.pages.PagesInfo(json, session: GitHubSession)

Representation of the information about a GitHub pages website.

cname

The cname in use for the pages site, if one is set.

custom_404

A boolean attribute indicating whether the user configured a custom 404 page for this site.

status

The current status of the pages site, e.g., built.

class github3.repos.pages.PagesBuild(json, session: GitHubSession)

Representation of a single build of a GitHub pages website.

commit

The SHA of the commit that triggered this build.

created_at

A datetime object representing the date and time when this build was created.

duration

The time it spent processing this build.

error

If this build errored, a dictionary containing the error message and details about the error.

pusher

A ShortUser representing the user who pushed the commit that triggered this build.

status

The current statues of the build, e.g., building.

updated_at

A datetime object representing the date and time when this build was last updated.

Comment Objects

More information about these classes can be found in the official documentation about comments.

class github3.repos.comment.ShortComment(json, session: GitHubSession)

The representation of an abridged comment on an object in a repo.

This object has the following attributes:

author_association

The affiliation the author of this comment has with the repository.

body

The Markdown formatted text of this comment.

commit_id

The SHA1 associated with this comment.

created_at

A datetime object representing the date and time when this comment was created.

html_url

The URL to view this comment in a browser.

id

The unique identifier of this comment.

line

The line number where the comment is located.

path

The path to the file where this comment was made.

position

The position in the diff where the comment was left.

updated_at

A datetime object representing the date and time when this comment was most recently updated.

user

A ShortUser representing the author of this comment.

class github3.repos.comment.RepoComment(json, session: GitHubSession)

The representation of the full comment on an object in a repository.

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

body_html

The HTML formatted text of this comment.

body_text

The plain-text formatted text of this comment.

Deployment and Status Objects

class github3.repos.deployment.Deployment(json, session: GitHubSession)

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

See also: https://developer.github.com/v3/repos/deployments/

This object has the following attributes:

created_at

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

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, inactive, in_progress, queued, 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: GitHubSession)

Representation of the status of a deployment of a repository.

See also https://developer.github.com/v3/repos/deployments/#get-a-single-deployment-status

This object has the following attributes:

created_at

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

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.status.ShortStatus(json, session: GitHubSession)

Representation of a short status on a repository.

New in version 1.0.0.

This is the representation found in a CombinedStatus object.

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

This object has the following attributes:

context

This is a string that explains the context of this status object. For example, 'continuous-integration/travis-ci/pr'.

created_at

A datetime object representing the date and time when this status was created.

creator

A ShortUser representing the user who created this status.

description

A short description of the status.

id

The unique identifier of this status object.

state

The state of this status, e.g., 'success', 'pending', 'failure'.

target_url

The URL to retrieve more information about this status.

updated_at

A datetime object representing the date and time when this status was most recently updated.

class github3.repos.status.CombinedStatus(json, session: GitHubSession)

A representation of the combined statuses in a repository.

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

This object has the following attributes:

commit_url

The URL of the commit this combined status is present on.

repository

A ShortRepository representing the repository on which this combined status exists.

sha

The SHA1 of the commit this status exists on.

state

The state of the combined status, e.g., 'success', 'pending', 'failure'.

statuses

The list of ShortStatus objects representing the individual statuses that is combined in this object.

total_count

The total number of sub-statuses.

class github3.repos.status.Status(json, session: GitHubSession)

Representation of a full status on a repository.

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

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

creator

A ShortUser representing the user who created this status.

Contributor Statistics Objects

class github3.repos.stats.ContributorStats(json, session: GitHubSession)

Representation of a user’s contributor statistics to a repository.

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

This object has the following attributes:

author

A ShortUser representing the contributor whose stats this object represents.

total

The total number of commits authored by author.

weeks

A list of dictionaries containing weekly statistical data.

alternate_weeks

Note

github3 generates this data for a more humane interface to the data in weeks.

A list of dictionaries that provide an easier to remember set of keys as well as a datetime object representing the start of the week. The dictionary looks vaguely like:

{
    'start of week': datetime(2013, 5, 5, 5, 0, tzinfo=tzutc())
    'additions': 100,
    'deletions': 150,
    'commits': 5,
}