IGitt.GitHub package¶

Submodules¶

IGitt.GitHub.GitHub module¶

Contains the Hoster implementation for GitHub.

class IGitt.GitHub.GitHub.GitHub(token: IGitt.GitHub.GitHubToken)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Hoster.Hoster

A high level interface to GitHub.

get_repo(repository) → IGitt.GitHub.GitHubRepository.GitHubRepository[source]¶

Retrieve a given repository.

>>> from os import environ
>>> github = GitHub(environ['GITHUB_TEST_TOKEN'])
>>> repo = github.get_repo('gitmate-test-user/test')
>>> isinstance(repo, GitHubRepository)
True

Returns:	A repository object.

static get_repo_name(webhook: dict)[source]¶: Retrieves the repository name from given webhook data.

get_user(username: str = None) → IGitt.GitHub.GitHubUser.GitHubUser[source]¶

Retrieves repository name from given webhook data.

Parameters:	username – Username to fetch, use None to fetch authenticated user.
Returns:	The user.

handle_webhook(event: str, data: dict)[source]¶

Handles a GitHub webhook for you.

If it’s an issue event it returns e.g. IssueActions.OPENED, [GitHubIssue(...)], for comments it returns MergeRequestActions.COMMENTED, [GitHubMergeRequest(...), GitHubComment(...)], for updates it returns IssueActions.LABELED, [GitHubIssue(...), 'new label'].

Parameters:	event – The X_GITHUB_EVENT of the request header. data – The pythonified JSON data of the request.
Yields:	An IssueActions or MergeRequestActions member and a list of the affected IGitt objects.

master_repositories¶: Retrieves repositories the user has admin access to.

owned_repositories¶

Retrieves repositories owned by the authenticated user.

>>> from os import environ
>>> github = GitHub(GitHubToken(environ['GITHUB_TEST_TOKEN']))
>>> sorted(map(lambda x: x.full_name, github.owned_repositories))
['gitmate-test-user/test']

Returns:	A set of full repository names.

static raw_search(token, raw_query)[source]¶

Handles a GitHub search.

Search syntax reference at https://help.github.com/articles/understanding-the-search-syntax/

Parameters:	token – A GitHubToken object to use for authentication. raw_query – A string with the search query following syntax.
Yields:	Search results as GitHubIssue(…) and GitHubMergeRequest(…) objects for Issues and Merge Requests respectively.

write_repositories¶

Retrieves the full names of repositories this user can write to.

>>> from os import environ
>>> github = GitHub(GitHubToken(environ['GITHUB_TEST_TOKEN']))
>>> sorted(map(lambda x: x.full_name, github.write_repositories))
['gitmate-test-user/test', 'sils/gitmate-test']

Returns:	A set of strings.

IGitt.GitHub.GitHubComment module¶

Represents a comment on GitHub.

class IGitt.GitHub.GitHubComment.GitHubComment(token: IGitt.GitHub.GitHubToken, repository, comment_type, comment_id)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Comment.Comment

Represents a comment on GitHub, mainly with a body and author - oh and it’s deletable!

author¶

Retrieves the author of the comment.

>>> from os import environ
>>> issue = GitHubComment(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                      'gitmate-test-user/test', 172962077)
>>> issue.author.username
'sils'

Returns:	A GitHubUser object.

body¶

Retrieves the content of the comment:

>>> from os import environ
>>> issue = GitHubComment(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                      'gitmate-test-user/test', 172962077)
>>> issue.body
'test comment\n'

Returns:	A string containing the body.

created¶

Retrieves a timestamp on when the comment was created.

>>> from os import environ
>>> issue = GitHubComment(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                      'gitmate-test-user/test', 172962077)
>>> issue.created
datetime.datetime(2016, 1, 19, 19, 37, 53)

delete()[source]¶: Deletes the comment.

number¶: Retrieves the id of the comment.

repository¶: Returns the GitHub repository this comment was posted in, as a GitHubRepository instance.

type¶: Retrieves the type of the comment it links to.

updated¶

Retrieves a timestamp on when the comment was updated the last time.

>>> from os import environ
>>> issue = GitHubComment(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                      'gitmate-test-user/test', 172962077)
>>> issue.updated
datetime.datetime(2016, 10, 9, 11, 36, 7)

IGitt.GitHub.GitHubCommit module¶

Contains the abstraction for a commit in GitHub.

class IGitt.GitHub.GitHubCommit.GitHubCommit(token: IGitt.GitHub.GitHubToken, repository: str, sha: str)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Commit.Commit

Represents a commit on GitHub.

closes_issues¶: Returns a set of GitHubIssue objects which would be closed upon merging this commit.

combined_status¶

Retrieves a combined status of all the commits.

Returns:	Status.FAILED if any of the commits report as error or failure or canceled Status.PENDING if there are no statuses or a commit is pending or a test is running Status.SUCCESS if the latest status for all commits is success

comment(message: str, file: Optional[str] = None, line: Optional[int] = None, mr_number: Optional[int] = None) → IGitt.GitHub.GitHubComment.GitHubComment[source]¶

Places a comment on the commit.

>>> from os import environ
>>> commit = GitHubCommit(GithubToken(environ['GITHUB_TEST_TOKEN']),
...                       'gitmate-test-user/test', '3fc4b86')

So this line places a comment on the bottom of the commit, not associated to any particular piece of code:

>>> commit.comment("An issue is here!")

However, we can also comment on a particular file and line, if that is included in the diff:

>>> commit.comment("Here in line 4, there's a spelling mistake!",
...                'README.md', 4)

If you supply the pr_number argument, the comment will appear in the review UI of that pull request:

>>> commit.comment("Here in line 4, there's a spelling mistake!",
...                'README.md', 4, mr_number=6)

Beat that! Of course, there’s a lot of error handling. If you give the wrong file, the comment will appear below the commit with a note about the commit, file and line:

>>> commit.comment("Oh, this'll end up below!!", 'READMENOT.md', 4)

Also if the line isn’t contained in the diff GitHub won’t accept that and it’ll also end up below - sorry!

>>> commit.comment("Oh, this'll too end up below!!", 'README.md', 8)

If you give a pull request, the comment will appear on the PR instead:

>>> commit.comment("Oh, this'll too end up on the PR.",
...                'README.md', 8, mr_number=6)

Parameters:	message – The body of the comment. file – The file to place the comment, relative to repository root. line – The line in the file in the comment or None. mr_number – The number of a merge request if this should end up in the review UI of the merge request.

get_patch_for_file(filename: str)[source]¶

Retrieves the patch for the given file:

>>> from os import environ
>>> commit = GitHubCommit(GithubToken(environ['GITHUB_TEST_TOKEN']),
...                       'gitmate-test-user/test', '3fc4b86')
>>> commit.get_patch_for_file('README.md')
'@@ -1,2 +1,4 @@\n # test\n a test repo\n+\n+a tst pr'

But only if it exists!

>>> commit.get_patch_for_file('isnt there!')
Traceback (most recent call last):
 ...
IGitt.ElementDoesntExistError: The file does not exist.

Parameters:	filename – The file to receive the patch for.
Returns:	A string containing the patch.
Raises:	ElementDoesntExistError – If the given filename doesn’t exist.

get_statuses() → Set[IGitt.Interfaces.CommitStatus.CommitStatus][source]¶

Retrieves the all commit statuses.

Returns:	A (frozen)set of CommitStatus objects.
Raises:	RuntimeError – If something goes wrong (network, auth…).

mentioned_issues¶: Returns a set of GitHubIssue objects which are related to the commit.

message¶

Returns the commit message.

Returns:	Commit message as string.

parent¶

Retrieves the parent commit. In case of a merge commit the first parent will be returned.

>>> from os import environ
>>> commit = GitHubCommit(GithubToken(environ['GITHUB_TEST_TOKEN']),
...                       'gitmate-test-user/test', '3fc4b86')
>>> commit.parent.sha
'674498fd415cfadc35c5eb28b8951e800f357c6f'

Returns:	A Commit object.

repository¶

Retrieves the repository that holds this commit.

>>> from os import environ
>>> commit = GitHubCommit(GithubToken(environ['GITHUB_TEST_TOKEN']),
...                       'gitmate-test-user/test', '3fc4b86')
>>> commit.repository.full_name
'gitmate-test-user/test'

Returns:	A usable Repository instance.

set_status(status: IGitt.Interfaces.CommitStatus.CommitStatus)[source]¶

Adds the given status to the commit.

>>> from os import environ
>>> commit = GitHubCommit(GithubToken(environ['GITHUB_TEST_TOKEN']),
...                       'gitmate-test-user/test', '3fc4b86')
>>> status = CommitStatus(Status.FAILED, 'Theres a problem',
...                       'gitmate/test')
>>> commit.set_status(status)
>>> commit.get_statuses().pop().description
'Theres a problem'

If a status with the same context already exists, it will be bluntly overridden:

>>> status.status = Status.SUCCESS
>>> status.description = "Theres no problem"
>>> commit.set_status(status)
>>> len(commit.get_statuses())
2
>>> commit.get_statuses().pop().description
'This commit needs work.'

Parameters:	status – The CommitStatus to set to this commit.
Raises:	RuntimeError – If something goes wrong (network, auth…).

sha¶

Retrieves the SHA of the commit:

>>> from os import environ
>>> commit = GitHubCommit(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                       'gitmate-test-user/test', '674498')
>>> commit.sha
'674498'

Returns:	A string holding the SHA of the commit.

unified_diff¶: Retrieves the unified diff for the commit excluding the diff index.

will_close_issues¶: Returns a set of GitHubIssue objects which would be closed as stated in this commit message.

will_fix_issues¶: Returns a set of GitHubIssue objects which would be fixed as stated in this commit message.

will_resolve_issues¶: Returns a set of GitHubIssue objects which would be resolved as stated in this commit message.

IGitt.GitHub.GitHubCommit.get_diff_index(patch, line_nr)[source]¶

Takes a patch and receives the position of the given line number in it.

>>> patch = ('---/version/a\n'
...          '+++/version/b\n'
...          '@@ -1,2 +1,4 @@\n'
...          ' # test\n'  # Line 1
...          '+\n'  # Line 2
...          '-a test repo\n'  # Line 3
...          '+something new\n'  # Line 3
...          ' something old\n')  # Line 4
>>> get_diff_index(patch, 1)
1
>>> get_diff_index(patch, 3)
4
>>> get_diff_index(patch, 4)
5

If the line isn’t covered in the patch, it’ll return None:

>>> get_diff_index(patch, 8)

Sometimes patches contain the function and shall still be interpreted correctly:

>>> patch = ('@@ -464,11 +464,10 @@ def get_action_info(section, action):\n'
...          ' line 464\n'
...          ' line 465\n'
...          ' line 466\n'
...          '-line 467\n'
...          '-line 468\n'
...          '+line 467\n'
...          '+line 468\n'
...          ' line 469\n')
>>> get_diff_index(patch, 465)
2
>>> get_diff_index(patch, 467)
6

Parameters:	patch – A list of lines of a unified diff. line_nr – The line number to identify.
Returns:	The position in the Patch or None

IGitt.GitHub.GitHubContent module¶

This contains the Content implementation for GitHub.

class IGitt.GitHub.GitHubContent.GitHubContent(token: IGitt.GitHub.GitHubToken, repository: str, path: str)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Content.Content

This class represents a content on GitHub

delete(message: str, branch: Optional[str] = None)[source]¶

Deletes content

Parameters:	message – The commit message for the deletion commit. branch – The branch to delete this content from. Defaults to master.

get_content(ref='master')[source]¶: Get content

update(message: str, content: str, branch: Optional[str] = None)[source]¶: Updates existing file in repository

IGitt.GitHub.GitHubInstallation module¶

This module contains the GitHubInstallation class which provides properties and actions related to GitHub App installations.

class IGitt.GitHub.GitHubInstallation.GitHubInstallation(token: IGitt.GitHub.GitHubInstallationToken, installation_id: int)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Installation.Installation

Represents a GitHub App installation.

app_id¶: The application which was installed.

identifier¶: Returns the identifier of the installation.

permissions¶: The permissions granted to this installation.

repositories¶: Returns the set of repositories this installation has access to.

webhooks¶: Returns the list of webhooks registered by installing the application.

IGitt.GitHub.GitHubIssue module¶

This contains the Issue implementation for GitHub.

class IGitt.GitHub.GitHubIssue.GitHubIssue(token: IGitt.GitHub.GitHubToken, repository: str, number: int)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Issue.Issue

This class represents an issue on GitHub.

add_comment(body)[source]¶

Adds a comment to the issue:

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 3)
>>> comment = issue.add_comment("Doh!")

You can use the comment right after:

>>> comment.body
'Doh!'
>>> comment.delete()

The comment will be created by the user authenticated via the oauth token.

Parameters:	body – The body of the new comment to create.
Returns:	The newly created comment.

assign(*users)[source]¶: Adds the user as one of the assignees of the issue. :param username: Username of the user to be added as an assignee.

assignees¶

Retrieves the assignee of the issue:

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> {a.username for a in issue.assignees}
{'gitmate-test-user'}

>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 2)
>>> issue.assignees  # Returns empty set, unassigned
{}

Returns:	A set containing the usernames of assignees.

author¶

Retrieves the author of the issue.

Returns:	A GitHubUser object.

available_assignees¶

Retrieves a set of available assignees for the issue.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> {a.username for a in issue.available_assignees}
{'gitmate-test-user'}

Returns:	A set of GitHubUsers.

available_labels¶

Retrieves a set of captions that are available for labelling bugs.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> sorted(issue.available_labels)
['a', 'b', 'c']

Returns:	A set of label captions (str).

close()[source]¶

Closes the issue.

Raises:	RuntimeError – If something goes wrong (network, auth…).

comments¶

Retrieves comments from the issue.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 9)
>>> comments = issue.comments

Now we can e.g. access the last comment:

>>> comments[-1].body
'Do not comment here.\n'

Returns:	A list of Comment objects.

static create(token: str, repository: str, title: str, body: str = '', issue_type: Optional[str] = None)[source]¶

Create a new issue with given title and body.

>>> from os import environ
>>> issue = GitHubIssue.create(
...     GitHubToken(environ['GITHUB_TEST_TOKEN']),
...     'gitmate-test-user/test',
...     'test issue title',
...     'sample description'
... )
>>> issue.state
<IssueStates.OPEN: 'open'>
>>> str(issue.state)
'open'

Let’s delete the newly created one, because it’s useless.

>>> issue.delete()
... 
Traceback (most recent call last):
 ...
NotImplementedError

Because GitHub is stupid, they don’t allow deleting issues. So, let’s atleast close this for now.

>>> issue.close()

Returns:	GitHubIssue object of the newly created issue.

created¶

Retrieves a timestamp on when the issue was created.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> issue.created
datetime.datetime(2016, 1, 13, 7, 56, 23)

delete()[source]¶

Should delete the issue, but GitHub doesn’t allow it yet.

Reference: https://github.com/isaacs/github/issues/253

description¶

Retrieves the main description of the issue:

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> issue.description
'A nice description!\n'

Returns:	A string containing the main description of the issue.

labels¶

Retrieves all labels associated with this bug.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> issue.labels
set()

Use the property setter to set the labels:

>>> issue.labels = {'a', 'b', 'c'}
>>> sorted(issue.labels)
['a', 'b', 'c']

Use the empty set intuitively to clear all labels:

>>> issue.labels = set()

Returns:	A list of label captions (str).

milestone¶: Retrieves the milestone.

mrs_closed_by¶: Returns the merge requests that close this issue.

number¶

Returns the issue “number” or id.

>>> from os import environ
>>> issue = GitHubIssue(environ['GITHUB_TEST_TOKEN'],
...                     'gitmate-test-user/test', 1)
>>> issue.number
1

Returns:	The number of the issue.

reactions¶: Retrieves the reactions / award emojis applied on the issue.

reopen()[source]¶

Reopens the issue.

Raises:	RuntimeError – If something goes wrong (network, auth…).

repository¶: Returns the GitHub repository this issue is linked with as a GitHubRepository instance.

state¶

Get’s the state of the issue.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 10)
>>> issue.state
<IssueStates.OPEN: 'open'>
>>> str(issue.state)
'open'

So if we close it:

>>> issue.close()
>>> issue.state
<IssueStates.CLOSED: 'closed'>
>>> str(issue.state)
'closed'

And reopen it:

>>> issue.reopen()
>>> issue.state
<IssueStates.OPEN: 'open'>

Returns:	Either <IssueStates.OPEN: ‘open’> or <IssueStates.CLOSED: ‘closed’>.

title¶

Retrieves the title of the issue.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 1)
>>> issue.title
'test issue'

You can simply set it using the property setter:

>>> issue.title = 'dont panic'
>>> issue.title
'dont panic'

>>> issue.title = 'test issue'

Returns:	The title of the issue - as string.

unassign(*users)[source]¶: Removes the user from the assignees of the issue. :param users: Username of the user to be unassigned.

updated¶

Retrieves a timestamp on when the issue was updated the last time.

>>> from os import environ
>>> issue = GitHubIssue(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                     'gitmate-test-user/test', 9)
>>> issue.updated
datetime.datetime(2016, 10, 9, 11, 27, 11)

weight¶: Retrieves the weight associated with the current issue.

IGitt.GitHub.GitHubMergeRequest module¶

Contains a class representing the GitHub pull request.

Labels, Milestones, Assignees and Comments are an integral part of GitHubIssue class. They have a rich unified way of handling issues and pull requests.

Reference - https://developer.github.com/v3/pulls/#labels-assignees-and-milestones

The methods being used from GitHubIssue are: - number - assignee - add_comment - comments - labels - labels.setter - available_labels

class IGitt.GitHub.GitHubMergeRequest.GitHubMergeRequest(token: IGitt.GitHub.GitHubToken, repository: str, number: int)[source]¶

Bases: IGitt.GitHub.GitHubIssue.GitHubIssue, IGitt.Interfaces.MergeRequest.MergeRequest

A Pull Request on GitHub.

affected_files¶

Retrieves affected files from a GitHub pull request.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.affected_files
{'README.md'}

Returns:	A set of filenames.

author¶

Retrieves the author of the merge request.

Returns:	A GitHubUser object.

base¶

Retrieves the base commit as a commit object.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.base.sha
'674498fd415cfadc35c5eb28b8951e800f357c6f'

Returns:	A Commit object.

base_branch_name¶

Retrieves the base branch name of the merge request, i.e. the one it should be merged into.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.base_branch_name
'master'

Returns:	A string.

closes_issues¶: Returns a set of GitHubIssue objects which would be closed upon merging this pull request.

commits¶

Retrieves a tuple of commit objects that are included in the PR.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> [commit.sha for commit in pr.commits]
['f6d2b7c66372236a090a2a74df2e47f42a54456b']

Returns:	A tuple of commit objects.

delete()[source]¶: GitHub doesn’t allow deleting issues or pull requests.

diffstat¶

Gets additions and deletions of a merge request.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.diffstat
(2, 0)

Returns:	An (additions, deletions) tuple.

head¶

Retrieves the head commit as a commit object.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.head.sha
'f6d2b7c66372236a090a2a74df2e47f42a54456b'

Returns:	A Commit object.

head_branch_name¶

Retrieves the head branch name of the merge request, i.e. the one that will be merged.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.head_branch_name
'gitmate-test-user-patch-2'

Returns:	A string.

mentioned_issues¶: Returns a set of GitHubIssue objects which are related to the pull request.

merge(message: str = None, sha: str = None, should_remove_source_branch: bool = False, _github_merge_method: str = None, _gitlab_merge_when_pipeline_succeeds: bool = False)[source]¶

Merges the merge request.

Parameters:

message – The commit message.
sha – The commit sha that the HEAD must match in order to merge.
should_remove_source_branch – Whether the source branch should be removed upon a successful merge.
_github_merge_method – On GitHub, the merge method to use when merging the MR. Can be one of merge, squash or rebase.
_gitlab_wait_for_pipeline – On GitLab, whether the MR should be merged immediately after the pipeline succeeds.

Raises:

RuntimeError – If something goes wrong (network, auth…).
NotImplementedError – If an unused parameter is passed.

mergeable¶: Returns true if there is no merge conflict.

milestone¶: Retrieves the milestone.

repository¶

Retrieves the repository where this comes from.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.repository.full_name
'gitmate-test-user/test'

Returns:	The repository object.

source_repository¶

Retrieves the repository where this PR’s head branch is located at.

>>> from os import environ
>>> pr = GitHubMergeRequest(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test', 7)
>>> pr.source_repository.full_name
'gitmate-test-user/test'

Returns:	The repository object.

state¶

Retrieves the state of the Pull Request on GitHub.

Returns:	A MergeRequestStates object.

will_close_issues¶: Returns a set of GitHubIssue objects which would be closed as stated in this pull request.

will_fix_issues¶: Returns a set of GitHubIssue objects which would be fixed as stated in this pull request.

will_resolve_issues¶: Returns a set of GitHubIssue objects which would be resolved as stated in this pull request.

IGitt.GitHub.GitHubMilestone module¶

This contains the Milestone implementation for GitHub

class IGitt.GitHub.GitHubMilestone.GitHubMilestone(token: IGitt.GitHub.GitHubToken, repository: str, number: int)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Milestone.Milestone

This class represents a milestone on GitHub.

close()[source]¶

Closes the milestone.

Raises:	RuntimeError – If something goes wrong (network, auth…).

static create(token: IGitt.GitHub.GitHubToken, repository: str, title: str, state: IGitt.Interfaces.MilestoneStates = <MilestoneStates.OPEN: 'open'>, description: str = None, due_on: datetime.datetime = None)[source]¶: Create a new milestone with given title :return: GitHubMilestone object of the newly created milestone.

created¶: Retrieves a timestamp on when the milestone was created.

delete()[source]¶

Deletes the milestone. This is not possible with GitLab api v4.

Raises:	RuntimeError – If something goes wrong (network, auth…).

description¶: Retrieves the main description of the milestone.

due_date¶: Retrieves a timestamp on when the milestone is due.

issues¶: Retrieves a set of issue objects that are assigned to this milestone.

merge_requests¶: Retrieves a set of merge_request objects that are assigned to this milestone.

number¶: Returns the milestone “number” or id.

project¶: Returns the repository this milestone is linked with.

reopen()[source]¶

Reopens the milestone.

Raises:	RuntimeError – If something goes wrong (network, auth…).

start_date¶: Retrieves a timestamp on when the milestone was started. The start_date does not exist in GitHub.

state¶

Get’s the state of the milestone.

Returns:	Either MilestoneStates.OPEN or MilestoneStates.CLOSED.

title¶: Retrieves the title of the milestone.

updated¶: Retrieves a timestamp on when the milestone was updated the last time.

IGitt.GitHub.GitHubNotification module¶

This contains the Notification implementation for GitHub.

Take note that GitHub Notifications are actually available via Threads API and Notifications API is just a wrapper to fetching these threads.

class IGitt.GitHub.GitHubNotification.GitHubNotification(token: IGitt.GitHub.GitHubToken, identifier: Union[str, int])[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Notification.Notification

This class represents a Notification on GitHub.

static fetch_all(token: IGitt.GitHub.GitHubToken)[source]¶: Returns the list of notifications for the user bearing the token.

identifier¶: Returns the id of the notification thread from GitHub.

mark_done()[source]¶: Marks the notification as done/read.

pending¶: Returns True if the notification is pending/not read.

reason¶: Returns the reason for notification.

repository¶: Returns the repository this notification is related to.

subject¶

Returns the subject of the notification.

Returns:	A GitHubCommit, GitHubIssue or GitHubMergeRequest object.

subject_type¶: Returns the type of the subject the notification.

unsubscribe()[source]¶: Unsubscribe from this subject.

IGitt.GitHub.GitHubOrganization module¶

Here you go: GitHub organizations can be used in IGitt.

class IGitt.GitHub.GitHubOrganization.GitHubOrganization(token, name)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Organization.Organization

Represents an organization on GitHub.

billable_users¶: Number of paying/registered users on the organization.

static create(token: IGitt.GitHub.GitHubToken, name: str, path: str, parent_id: Optional[int] = None, description: Optional[str] = None, visibility: str = 'private', lfs_enabled: bool = False, request_access_enabled: bool = False) → IGitt.Interfaces.Organization.Organization[source]¶: GitHub does not allow creating new organizations via the API.

description¶: Returns the description of this organization.

filter_issues(state: Optional[str] = None, label: Optional[str] = None, assignee: Optional[str] = None) → Set[IGitt.GitHub.GitHubIssue.GitHubIssue][source]¶

Filters the issues in the organization based on properties

Parameters:	state – ‘opened’ or ‘closed’ or ‘all’. label – Label of the issue assignee – username of issue assignee
Returns:	Set of GitHubIssue objects

identifier¶: Returns the identifier of the organization.

issues¶: Returns the set of Issues in this organization.

masters¶: Gets all owners (because there’s no masters role on GitHub).

name¶: The name of the organization.

owners¶: Returns the user handles of all admin users.

repositories¶: Returns the list of repositories contained in this organization.

suborgs¶: Returns the sub-organizations within this repository.

web_url¶: Returns the web link for GitHub.

IGitt.GitHub.GitHubReaction module¶

Contains an object representation of a reaction on GitHub.

class IGitt.GitHub.GitHubReaction.GitHubReaction(token: IGitt.GitHub.GitHubToken, related: Union[IGitt.Interfaces.Issue.Issue, IGitt.Interfaces.Comment.Comment], identifier: int)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Reaction.Reaction

A GitHub reaction, e.g. heart.

name¶: Retrieves the name of the reaction.

user¶: Retrieves the user who reacted with this reaction.

IGitt.GitHub.GitHubRepository module¶

Contains the GitHub Repository implementation.

class IGitt.GitHub.GitHubRepository.GitHubRepository(token: [<class 'IGitt.GitHub.GitHubToken'>, <class 'IGitt.GitHub.GitHubInstallationToken'>], repository: Union[str, int])[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Repository.Repository

Represents a repository on GitHub.

clone_url¶

Retrieves the URL of the repository.

>>> from os import environ as env
>>> repo = GitHubRepository(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test')
>>> expected = 'https://{}@github.com/gitmate-test-user/test.git'
>>> assert repo.clone_url == expected.format(GitHubToken(
...     env['GITHUB_TEST_TOKEN'])
... )

Returns:	A URL that can be used to clone the repository with Git.

commits¶

Retrieves the set of commits in this repository.

Returns:	A set of GitHubCommit objects.

static create(token: Union[IGitt.GitHub.GitHubToken, IGitt.Interfaces.BasicAuthorizationToken, IGitt.GitHub.GitHubInstallationToken], name: str, org_name: Optional[str] = None, description: Optional[str] = None, homepage: Optional[str] = None, visibility: str = 'public', has_issues: bool = True, has_projects: bool = True, has_wiki: bool = True, team_id: Optional[int] = None, auto_init: bool = False, gitignore_template: Optional[str] = None, license_template: Optional[str] = None, allow_squash_merge: bool = True, allow_merge_commit: bool = True, allow_rebase_merge: bool = True, **kwargs)[source]¶

Creates a new repository and returns associated GitHubRepository instance.

Parameters:

token – The token to be used for authentication.
name – The name of the repository.
org_name – The name of the organization this repository is to be created in. Pass None if it is a user repository.
description – A short description of the repository.
homepage – A URL with more information about the repository.
visibility – Either private to create a private repository or public to create a public one.
has_issues – Either True to enable issues for this repository or False to disable them.
has_projects – Either True to enable projects for this repository or False to disable them. Note: If you’re creating a repository in an organization that has disabled repository projects, the default is false, and if you pass true, the API returns an error.
has_wiki – Either True to enable a wiki for this repository or False to disable it.
team_id – The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization.
auto_init – Pass True to create an initial commit with empty README.
gitignore_template – Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, “Haskell”. Reference: https://github.com/github/gitignore
license_template – Choose an open source license template that best suits your needs, and then use the license keyword as the license_template string. For example, “mit” or “mpl-2.0”. Reference: https://help.github.com/articles/licensing-a-repository/#searching-github-by-license-type
allow_squash_merge – Pass True to allow squash merging pull requests.
allow_merge_commit – Pass True to allow merging pull requests with a merge commit.
allow_rebase_merge – Pass True to allow rebase-merging pull requests.

create_file(path: str, message: str, content: str, branch: Optional[str] = None, committer: Optional[str] = None, author: Optional[dict] = None, encoding: Optional[str] = None)[source]¶: Creates a new file in the Repository

create_fork(organization: Optional[str] = None, namespace: Optional[str] = None)[source]¶: Creates a fork of repository.

create_issue(title: str, body: str = '') → IGitt.GitHub.GitHubIssue.GitHubIssue[source]¶

Create a new issue in the repository.

>>> from os import environ
>>> repo = GitHubRepository(environ['GITHUB_TEST_TOKEN'],
...                         'gitmate-test-user/test')
>>> iss = repo.create_issue('test issue title', 'test body title')
>>> isinstance(iss, GitHubIssue)
True

create_label(name: str, color: str = '', **kwargs)[source]¶

Creates a new label with the given color. For an example, see delete_label.

If a label that already exists is attempted to be created, that throws an exception:

>>> from os import environ
>>> repo = GitHubRepository(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test')
>>> sorted(repo.get_labels())
['a', 'b', 'c']
>>> repo.create_label('c', '#555555')
Traceback (most recent call last):
 ...
IGitt.ElementAlreadyExistsError: c already exists.

Parameters:	name – The name of the label to create. color – A HTML color value with a leading #.
Raises:	ElementAlreadyExistsError – If the label name already exists. RuntimeError – If something goes wrong (network, auth…).

create_merge_request(title: str, base: str, head: str, body: Optional[str] = None, target_project_id: Optional[int] = None, target_project: Optional[str] = None)[source]¶: Creates a merge request to that repository

delete()[source]¶: Deletes the repository

delete_hook(url: str)[source]¶

Deletes all webhooks to the given URL.

Parameters:	url – The URL to not fire the webhook to anymore.
Raises:	RuntimeError – If something goes wrong (network, auth…).

delete_label(name: str)[source]¶

Deletes a label.

Take a given repository:

>>> from os import environ
>>> repo = GitHubRepository(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test')
>>> sorted(repo.get_labels())
['a', 'b', 'c']

Let’s create a label ‘d’:

>>> repo.create_label('d', '#555555')
>>> sorted(repo.get_labels())
['a', 'b', 'c', 'd']

>>> repo.delete_label('d')
>>> sorted(repo.get_labels())
['a', 'b', 'c']

If the label doesn’t exist it won’t get silently dropped - no! You will get an exception.

>>> repo.delete_label('d')
Traceback (most recent call last):
 ...
IGitt.ElementDoesntExistError: d doesnt exist.

Parameters:	name – The caption of the label to delete.
Raises:	ElementDoesntExistError – If the label doesn’t exist. RuntimeError – If something goes wrong (network, auth…).

filter_commits(author: Optional[str] = None)[source]¶

Filter commits based on properties.

Author:	Author username of the commit.
Returns:	A set of GitHubCommit objects.

filter_issues(state: str = 'opened', label: Optional[str] = None, assignee: Optional[str] = None) → set[source]¶

Filters the issues from the repository based on properties.

Parameters:	state – ‘opened’ or ‘closed’ or ‘all’. label – Label of the issue assignee – username of issue assignee

filter_merge_requests(state: str = 'opened') → set[source]¶

Filters the merge requests from the repository based on the state of the merge requests.

Parameters:	state – ‘opened’ or ‘closed’, ‘merged’, or ‘all’.

full_name¶

Retrieves the full name of the repository, e.g. “sils/something”.

>>> from os import environ
>>> repo = GitHubRepository(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test')
>>> repo.full_name
'gitmate-test-user/test'

Returns:	The full repository name as string.

get_issue(issue_number: int)[source]¶

Retrieves an issue:

>>> from os import environ
>>> repo = GitHubRepository(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test')
>>> repo.get_issue(1).title
'test issue'

Parameters:	issue_number – The issue ID of the issue to retrieve.
Returns:	An Issue object.
Raises:	ElementDoesntExistError – If the issue doesn’t exist. RuntimeError – If something goes wrong (network, auth…).

get_labels()[source]¶

Retrieves the labels of the repository.

>>> from os import environ
>>> repo = GitHubRepository(GitHubToken(environ['GITHUB_TEST_TOKEN']),
...                         'gitmate-test-user/test')
>>> sorted(repo.get_labels())
['a', 'b', 'c']

Returns:	A set of strings containing the label captions.

get_mr(mr_number: int)[source]¶

Retrieves an MR:

Parameters:	mr_number – The merge_request ID of the MR to retrieve.
Returns:	A MergeRequest object.
Raises:	ElementDoesntExistError – If the MR doesn’t exist. RuntimeError – If something goes wrong (network, auth…).

get_permission_level(user) → IGitt.Interfaces.AccessLevel[source]¶

Retrieves the permission level for the specified user on this repository.

Note that this request can be made only if the access token used here has atleast write access to the repository. If not, a HTTP 403 occurs.

hooks¶

Retrieves all URLs this repository is hooked to.

Returns:	Set of URLs (str).

identifier¶: Returns the identifier of the repository.

issues¶

Retrieves a set of open issue objects.

>>> from os import environ
>>> repo = GitHubRepository(environ['GITHUB_TEST_TOKEN'],
...                         'gitmate-test-user/test')
>>> len(repo.issues)
81

merge_requests¶

Retrieves a set of open merge request objects.

>>> from os import environ
>>> repo = GitHubRepository(environ['GITHUB_TEST_TOKEN'],
...                         'gitmate-test-user/test')
>>> len(repo.merge_requests)
3

parent¶: Returns the repository from which this repository is forked from. Returns None if it has no fork relationship.

register_hook(url: str, secret: Optional[str] = None, events: Optional[Set[IGitt.Interfaces.Repository.WebhookEvents]] = None)[source]¶

Registers a webhook to the given URL. Use it as simple as:

>>> from os import environ
>>> repo = GitHubRepository(environ['GITHUB_TEST_TOKEN'],
...                         'gitmate-test-user/test')
>>> repo.register_hook("http://some.url/in/the/world")

It does nothing if the hook is already there:

>>> repo.register_hook("http://some.url/in/the/world")

To register a secret token with the webhook, simply add the secret param:

>>> repo.register_hook("http://some.url/i/have/a/secret",
...     "mylittlesecret")

To delete it simply run:

>>> repo.delete_hook("http://some.url/in/the/world")
>>> repo.delete_hook("http://some.url/i/have/a/secret")

Parameters:	url – The URL to fire the webhook to. secret – An optional secret token to be registered with the webhook. An X-Hub-Signature value, in the response header, computed as a HMAC hex digest of the body, using the secret as the key would be returned when the webhook is fired. events – The events for which the webhook is to be registered against. Defaults to all possible events.
Raises:	RuntimeError – If something goes wrong (network, auth…).

search_issues(created_after: Optional[datetime.datetime] = None, created_before: Optional[datetime.datetime] = None, updated_after: Optional[datetime.datetime] = None, updated_before: Optional[datetime.datetime] = None, state: Optional[IGitt.Interfaces.IssueStates] = None)[source]¶: List open issues in the repository.

search_mrs(created_after: Optional[datetime.datetime] = None, created_before: Optional[datetime.datetime] = None, updated_after: Optional[datetime.datetime] = None, updated_before: Optional[datetime.datetime] = None, state: Optional[IGitt.Interfaces.MergeRequestStates] = None)[source]¶: List open pull request in the repository.

top_level_org¶: Returns the topmost organization, e.g. for gitmate/open-source/IGitt this is gitmate.

IGitt.GitHub.GitHubTeam module¶

Contains the GitHub Team implementation.

class IGitt.GitHub.GitHubTeam.GitHubTeam(token, team_id)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.Team.Team

Represents a team on GitHub.

description¶: Returns the description of this team.

get_organization¶: Returns parent organization.

id¶: Retrieves the id of the team.

is_member(username)[source]¶: Checks if given username is member of this team.

members¶: Returns the user handles of all members of this team.

name¶: Name of the team.

web_url¶: Returns the web link for GitHub.

IGitt.GitHub.GitHubUser module¶

Contains a representation of GitHub users.

class IGitt.GitHub.GitHubUser.GitHubUser(token: IGitt.GitHub.GitHubToken, username: Optional[str] = None)[source]¶

Bases: IGitt.GitHub.GitHubMixin, IGitt.Interfaces.User.User

A GitHub user, e.g. sils :)

get_installations(jwt)[source]¶

Gets the installations this user has access to.

Parameters:	jwt – The GitHubJsonWebToken required to fetch data.

identifier¶: Gets a unique id for the user that never changes.

installed_repositories(installation_id: int)[source]¶: List repositories that are accessible to the authenticated user for an installation.

username¶: Retrieves the login for the user.

Module contents¶

This package contains the GitHub implementations of the interfaces in server.git.Interfaces.

class IGitt.GitHub.GitHubInstallationToken(installation_id: int, jwt_token: IGitt.GitHub.GitHubJsonWebToken, token: Optional[str] = None, expiry: Optional[datetime.datetime] = None)[source]¶

Bases: IGitt.Interfaces.Token

Object representation of GitHub Installation Token.

auth¶

OAuth 2.0 JWT Bearer Token Flow is not supported by oauthlib yet.

Reference: https://github.com/oauthlib/oauthlib/issues/50

headers¶: The Authorization headers.

is_expired¶: Returns true if the token has expired.

jwt¶: Retrieves the JWT being used.

parameter¶: GitHub Installation Token can only be authenticated via the Authorization header and so, all the nested requests have to be made in only that way.

value¶: Token value

class IGitt.GitHub.GitHubJsonWebToken(private_key: str, app_id: int)[source]¶

Bases: IGitt.Interfaces.Token

Object representation of JSON Web Token.

auth¶

OAuth 2.0 JWT Bearer Token Flow is not supported by oauthlib yet.

Reference: https://github.com/oauthlib/oauthlib/issues/50

headers¶: The Authorization headers.

is_expired¶: Returns True if the JWT has expired.

parameter¶: GitHub’s JSON Web Token can only be authenticated via the Authorization header and so, all the nested requests have to be made in only that way.

payload¶: Returns the payload to be sent for JWT encoding.

value¶: Token value

class IGitt.GitHub.GitHubMixin[source]¶

Bases: IGitt.Utils.CachedDataMixin

Base object for things that are on GitHub.

static absolute_url(url)[source]¶: Makes a URL like /repo/coala/coala absolute.

hoster¶: Returns github.

url¶: Returns github API url.

web_url¶: Returns the web link for GitHub.

class IGitt.GitHub.GitHubToken(token)[source]¶

Bases: IGitt.Interfaces.Token

Object representation of oauth tokens.

auth¶: A AuthBase instance that can be readily used to configure any kind of authentication easily with requests library.

headers¶: GitHub Access token does not require any special headers.

parameter¶: No additional query parameters are used with GitHub token.

value¶: Token value

IGitt.GitHub package¶

Submodules¶

IGitt.GitHub.GitHub module¶

IGitt.GitHub.GitHubComment module¶

IGitt.GitHub.GitHubCommit module¶

IGitt.GitHub.GitHubContent module¶

IGitt.GitHub.GitHubInstallation module¶

IGitt.GitHub.GitHubIssue module¶

IGitt.GitHub.GitHubMergeRequest module¶

IGitt.GitHub.GitHubMilestone module¶

IGitt.GitHub.GitHubNotification module¶

IGitt.GitHub.GitHubOrganization module¶

IGitt.GitHub.GitHubReaction module¶

IGitt.GitHub.GitHubRepository module¶

IGitt.GitHub.GitHubTeam module¶

IGitt.GitHub.GitHubUser module¶

Module contents¶

IGitt

Navigation

Related Topics