Pull Request

This section of the documentation covers:

Pull Request Objects

class github3.pulls.PullRequest(json, session)

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_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

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

from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

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

Merge this pull request.

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
  • 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
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

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.ReviewComment(json, session)

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
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

class github3.pulls.PullDestination(json, session)

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
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

class github3.pulls.PullFile(json, session)

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

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
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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