Pull Requests and their Associated Objects

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

Pull Request Objects

class github3.pulls.ShortPullRequest(json, session: GitHubSession)

Object for the shortened representation of a PullRequest.

GitHub’s API returns different amounts of information about prs based upon how that information is retrieved. Often times, when iterating over several prs, GitHub will return less information. To provide a clear distinction between the types of Pull Requests, github3.py uses different classes with different sets of attributes.

New in version 1.0.0.

The attributes available on this object are:

url

The URL that describes this exact pull request.

assignee

Deprecated since version 1.0.0: Use assignees instead.

The assignee of the pull request, if present, represented as an instance of ShortUser

assignees

New in version 1.0.0.

A list of the assignees of the pull request. If not empty, a list of instances of ShortUser.

base

A Base object representing the base pull request destination.

body

The Markdown formatted body of the pull request message.

body_html

The HTML formatted body of the pull request mesage.

body_text

The plain-text formatted body of the pull request message.

closed_at

A datetime object representing the date and time when this pull request was closed.

comments_url

The URL to retrieve the comments on this pull request from the API.

commits_url

The URL to retrieve the commits in this pull request from the API.

created_at

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

diff_url

The URL to retrieve the diff for this pull request via the API.

head

A Head object representing the head pull request destination.

html_url

The URL one would use to view this pull request in the browser.

id

The unique ID of this pull request across all of GitHub.

issue_url

The URL of the resource that represents this pull request as an issue.

A dictionary provided by _links in the API response.

New in version 1.0.0.

merge_commit_sha

If unmerged, holds the sha of the commit to test mergability. If merged, holds commit sha of the merge commit, squashed commit on the base branch or the commit that the base branch was updated to after rebasing the PR.

merged_at

A datetime object representing the date and time this pull request was merged. If this pull request has not been merged then this attribute will be None.

number

The number of the pull request on the repository.

patch_url

The URL to retrieve the patch for this pull request via the API.

rebaseable

A boolean attribute indicating whether GitHub deems this pull request is rebaseable. None if not set.

repository

A ShortRepository from the base instance.

requested_reviewers

A list of ShortUser from which a review was requested.

requested_teams

A list of ShortTeam from which a review was requested.

review_comment_urlt

A URITemplate instance that expands to provide the review comment URL provided a number.

review_comments_url

The URl to retrieve all review comments on this pull request from the API.

state

The current state of this pull request.

title

The title of this pull request.

updated_at

A datetime instance representing the date and time when this pull request was last updated.

user

A ShortUser instance representing who opened this pull request.

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

close()

Close this Pull Request without merging.

Returns:

True if successful, False otherwise

Return type:

bool

commits(number=-1, etag=None)

Iterate over the commits on this pull request.

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

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

Returns:

generator of repository commit objects

Return type:

ShortCommit

create_comment(body)

Create a comment on this pull request’s issue.

Parameters:

body (str) – (required), comment body

Returns:

the comment that was created on the pull request

Return type:

IssueComment

create_review(body, commit_id=None, event=None, comments=None)

Create a review comment on this pull request.

Warning

If you do not specify event, GitHub will default it to PENDING which means that your review will need to be submitted after creation. (See also submit().)

Parameters:
  • body (str) – The comment text itself, required when using COMMENT or REQUEST_CHANGES.

  • commit_id (str) – The SHA of the commit to comment on

  • event (str) – The review action you want to perform. Actions include APPROVE, REQUEST_CHANGES or COMMENT. By leaving this blank you set the action to PENDING and will need to submit the review. Leaving blank may result in a 422 error response which will need to be handled.

  • comments (list) –

    Array of draft review comment objects. Please see Github’s Create a pull request review documentation for details on review comment objects. At the time of writing these were a dictionary with 3 keys: path, position and body.

Returns:

The created review.

Return type:

PullReview

create_review_comment(body, commit_id, path, position)

Create a review comment on this pull request.

Note

All parameters are required by the GitHub API.

Parameters:
  • body (str) – The comment text itself

  • commit_id (str) – The SHA of the commit to comment on

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

  • position (int) – The line index in the diff to comment on.

Returns:

The created review comment.

Return type:

ReviewComment

create_review_requests(reviewers=None, team_reviewers=None)

Ask for reviews on this pull request.

Parameters:
  • reviewers (list) – The users to which request a review

  • team_reviewers (list) – The teams to which request a review

Returns:

The pull request on which the reviews were requested

Return type:

ShortPullRequest

delete_review_requests(reviewers=None, team_reviewers=None)

Cancel review requests on this pull request.

Parameters:
  • reviewers (list) – The users whose review is no longer requested

  • team_reviewers (list) – The teams whose review is no longer requested

Returns:

True if successful, False otherwise

Return type:

bool

diff()

Return the diff.

Returns:

representation of the diff

Return type:

bytes

files(number=-1, etag=None)

Iterate over the files associated with this pull request.

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

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

Returns:

generator of pull request files

Return type:

PullFile

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.

is_merged()

Check to see if the pull request was merged.

Changed in version 1.0.0: This now always makes a call to the GitHub API. To avoid that, check merged before making this call.

Returns:

True if merged, False otherwise

Return type:

bool

issue()

Retrieve the issue associated with this pull request.

Returns:

the issue object that this pull request builds upon

Return type:

Issue

issue_comments(number=-1, etag=None)

Iterate over the issue comments on this pull request.

In this case, GitHub leaks implementation details. Pull Requests are really just Issues with a diff. As such, comments on a pull request that are not in-line with code, are technically issue comments.

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

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

Returns:

generator of non-review comments on this pull request

Return type:

IssueComment

merge(commit_message=None, sha=None, merge_method='merge', commit_title=None)

Merge this pull request.

Changed in version 1.3.0: The commit_title parameter has been added to allow users to set the merge commit title.

Changed in version 1.0.0: The boolean squash parameter has been replaced with merge_method which requires a string.

Parameters:
  • commit_message (str) – (optional), message to be used for the merge commit

  • commit_title (str) – (optional), message to be used for the merge commit title

  • sha (str) – (optional), SHA that pull request head must match to merge.

  • merge_method (str) – (optional), Change the merge method. Either ‘merge’, ‘squash’ or ‘rebase’. Default is ‘merge’.

Returns:

True if successful, False otherwise

Return type:

bool

Returns:

bool

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

patch()

Return the patch.

Returns:

bytestring representation of the patch

Return type:

bytes

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

reopen()

Re-open a closed Pull Request.

Returns:

True if successful, False otherwise

Return type:

bool

review_comments(number=-1, etag=None)

Iterate over the review comments on this pull request.

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

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

Returns:

generator of review comments

Return type:

ReviewComment

review_requests()

Retrieve the review requests associated with this pull request.

Returns:

review requests associated with this pull request

Return type:

ReviewRequests

reviews(number=-1, etag=None)

Iterate over the reviews associated with this pull request.

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

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

Returns:

generator of reviews for this pull request

Return type:

PullReview

update(title=None, body=None, state=None, base=None, maintainer_can_modify=None)

Update this pull request.

Parameters:
  • title (str) – (optional), title of the pull

  • body (str) – (optional), body of the pull request

  • state (str) – (optional), one of (‘open’, ‘closed’)

  • base (str) – (optional), Name of the branch on the current repository that the changes should be pulled into.

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

Returns:

True if successful, False otherwise

Return type:

bool

class github3.pulls.PullRequest(json, session: GitHubSession)

Object for the full representation of a PullRequest.

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

Changed in version 1.0.0.

This object has all of the same attributes as ShortPullRequest as well as the following:

additions_count

The number of lines of code added in this pull request.

deletions_count

The number of lines of code deleted in this pull request.

comments_count

The number of comments left on this pull request.

commits_count

The number of commits included in this pull request.

mergeable

A boolean attribute indicating whether GitHub deems this pull request is mergeable.

mergeable_state

A string indicating whether this would be a ‘clean’ or ‘dirty’ merge.

merged

A boolean attribute indicating whether the pull request has been merged or not.

merged_by

An instance of ShortUser to indicate the user who merged this pull request. If this hasn’t been merged or if mergeable is still being decided by GitHub this will be None.

review_comments_count

The number of review comments on this pull request.

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

close()

Close this Pull Request without merging.

Returns:

True if successful, False otherwise

Return type:

bool

commits(number=-1, etag=None)

Iterate over the commits on this pull request.

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

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

Returns:

generator of repository commit objects

Return type:

ShortCommit

create_comment(body)

Create a comment on this pull request’s issue.

Parameters:

body (str) – (required), comment body

Returns:

the comment that was created on the pull request

Return type:

IssueComment

create_review(body, commit_id=None, event=None, comments=None)

Create a review comment on this pull request.

Warning

If you do not specify event, GitHub will default it to PENDING which means that your review will need to be submitted after creation. (See also submit().)

Parameters:
  • body (str) – The comment text itself, required when using COMMENT or REQUEST_CHANGES.

  • commit_id (str) – The SHA of the commit to comment on

  • event (str) – The review action you want to perform. Actions include APPROVE, REQUEST_CHANGES or COMMENT. By leaving this blank you set the action to PENDING and will need to submit the review. Leaving blank may result in a 422 error response which will need to be handled.

  • comments (list) –

    Array of draft review comment objects. Please see Github’s Create a pull request review documentation for details on review comment objects. At the time of writing these were a dictionary with 3 keys: path, position and body.

Returns:

The created review.

Return type:

PullReview

create_review_comment(body, commit_id, path, position)

Create a review comment on this pull request.

Note

All parameters are required by the GitHub API.

Parameters:
  • body (str) – The comment text itself

  • commit_id (str) – The SHA of the commit to comment on

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

  • position (int) – The line index in the diff to comment on.

Returns:

The created review comment.

Return type:

ReviewComment

create_review_requests(reviewers=None, team_reviewers=None)

Ask for reviews on this pull request.

Parameters:
  • reviewers (list) – The users to which request a review

  • team_reviewers (list) – The teams to which request a review

Returns:

The pull request on which the reviews were requested

Return type:

ShortPullRequest

delete_review_requests(reviewers=None, team_reviewers=None)

Cancel review requests on this pull request.

Parameters:
  • reviewers (list) – The users whose review is no longer requested

  • team_reviewers (list) – The teams whose review is no longer requested

Returns:

True if successful, False otherwise

Return type:

bool

diff()

Return the diff.

Returns:

representation of the diff

Return type:

bytes

files(number=-1, etag=None)

Iterate over the files associated with this pull request.

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

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

Returns:

generator of pull request files

Return type:

PullFile

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.

is_merged()

Check to see if the pull request was merged.

Changed in version 1.0.0: This now always makes a call to the GitHub API. To avoid that, check merged before making this call.

Returns:

True if merged, False otherwise

Return type:

bool

issue()

Retrieve the issue associated with this pull request.

Returns:

the issue object that this pull request builds upon

Return type:

Issue

issue_comments(number=-1, etag=None)

Iterate over the issue comments on this pull request.

In this case, GitHub leaks implementation details. Pull Requests are really just Issues with a diff. As such, comments on a pull request that are not in-line with code, are technically issue comments.

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

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

Returns:

generator of non-review comments on this pull request

Return type:

IssueComment

merge(commit_message=None, sha=None, merge_method='merge', commit_title=None)

Merge this pull request.

Changed in version 1.3.0: The commit_title parameter has been added to allow users to set the merge commit title.

Changed in version 1.0.0: The boolean squash parameter has been replaced with merge_method which requires a string.

Parameters:
  • commit_message (str) – (optional), message to be used for the merge commit

  • commit_title (str) – (optional), message to be used for the merge commit title

  • sha (str) – (optional), SHA that pull request head must match to merge.

  • merge_method (str) – (optional), Change the merge method. Either ‘merge’, ‘squash’ or ‘rebase’. Default is ‘merge’.

Returns:

True if successful, False otherwise

Return type:

bool

Returns:

bool

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

patch()

Return the patch.

Returns:

bytestring representation of the patch

Return type:

bytes

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

reopen()

Re-open a closed Pull Request.

Returns:

True if successful, False otherwise

Return type:

bool

review_comments(number=-1, etag=None)

Iterate over the review comments on this pull request.

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

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

Returns:

generator of review comments

Return type:

ReviewComment

review_requests()

Retrieve the review requests associated with this pull request.

Returns:

review requests associated with this pull request

Return type:

ReviewRequests

reviews(number=-1, etag=None)

Iterate over the reviews associated with this pull request.

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

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

Returns:

generator of reviews for this pull request

Return type:

PullReview

update(title=None, body=None, state=None, base=None, maintainer_can_modify=None)

Update this pull request.

Parameters:
  • title (str) – (optional), title of the pull

  • body (str) – (optional), body of the pull request

  • state (str) – (optional), one of (‘open’, ‘closed’)

  • base (str) – (optional), Name of the branch on the current repository that the changes should be pulled into.

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

Returns:

True if successful, False otherwise

Return type:

bool

class github3.pulls.PullDestination(json, session: GitHubSession)

The object that represents a pull request destination.

This is the base class for the Head and Base objects. Each has identical attributes to this object.

Please see GitHub’s Pull Request Documentation for more information.

ref

The full reference string for the git object

label

The label for the destination (e.g., ‘master’, ‘mybranch’)

user

If provided, a ShortUser instance representing the owner of the destination

sha

The SHA of the commit at the head of the destination

repository

A ShortRepository representing the repository containing this destination

repo

A tuple containing the login and repository name, e.g., (‘sigmavirus24’, ‘github3.py’)

This attribute is generated by github3.py and may be deprecated in the future.

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

An object representing the Head destination of a pull request.

See PullDestination for more details.

class github3.pulls.Base(json, session: GitHubSession)

An object representing the Base destination of a pull request.

See PullDestination for more details.

class github3.pulls.PullFile(json, session: GitHubSession)

The object that represents a file in a pull request.

Please see GitHub’s Pull Request Files Documentation for more information.

additions_count

The number of additions made to this file

blob_url

The API resource used to retrieve the blob for this file

changes_count

The number of changes made to this file

contents_url

The API resource to view the raw contents of this file

deletions_count

The number of deletions made to this file

filename

The name of this file

patch

The patch generated by this

Note

If the patch is larger than a specific size it may be missing from GitHub’s response. The attribute will be set to None in this case.

raw_url

The API resource to view the raw diff of this file

sha

The SHA of the commit that this file belongs to

status

The string with the status of the file, e.g., ‘added’

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

contents()

Return the contents of the file.

Returns:

An object representing the contents of this file

Return type:

Contents

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

Review Objects

class github3.pulls.ReviewComment(json, session: GitHubSession)

Object representing review comments left on a pull request.

Please see GitHub’s Pull Comments Documentation for more information.

id

The unique identifier for this comment across all GitHub review comments.

author_association

The role of the author of this comment on the repository.

body

The Markdown formatted body of this comment.

body_html

The HTML formatted body of this comment.

body_text

The plain text formatted body of this comment.

commit_id

The SHA of current commit this comment was left on.

created_at

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

diff_hunk

A string representation of the hunk of the diff where the comment was left.

html_url

The URL to view this comment in the webbrowser.

A dictionary of relevant URLs usually returned in the _links attribute.

original_commit_id

The SHA of the original commit this comment was left on.

original_position

The original position within the diff that this comment was left on.

pull_request_url

The URL to retrieve the pull request via the API.

updated_at

A datetime instance representing the date and time this comment was updated.

user

A ShortUser instance representing the author of this comment.

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

delete()

Delete this comment.

Returns:

True if successful, False otherwise

Return type:

bool

edit(body)

Edit this comment.

Parameters:

body (str) – (required), new body of the comment, Markdown formatted

Returns:

True if successful, False otherwise

Return type:

bool

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

reply(body)

Reply to this review comment with a new review comment.

Parameters:

body (str) – The text of the comment.

Returns:

The created review comment.

Return type:

ReviewComment