Pull Request

This section of the documentation covers:

Pull Request Objects

class github3.pulls.PullRequest(json, session=None)

The PullRequest object.

Two pull request instances can be checked like so:

p1 == p2
p1 != p2

And is equivalent to:

p1.id == p2.id
p1.id != p2.id

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

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: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 RepoCommits

create_comment(body)

Create a comment on this pull request’s issue.

Parameters:body (str) – (required), comment body
Returns:IssueComment
create_review_comment(body, commit_id, path, position)

Create a review comment on this pull request.

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:bytestring representation of the diff.
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 PullFiles

from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

Return an instance of this class formed from json.

is_merged()

Check to see if the pull request was merged.

Returns:bool
issue()

Retrieve the issue associated with this pull request.

Returns:Issue
issue_comments(number=-1, etag=None)

Iterate over the issue 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 IssueComments

merge(commit_message=None, sha=None, squash=False)

Merge this pull request.

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.
  • squash (bool) – (optional), commit a single commit to the head branch.
Returns:

bool

patch()

Return the patch.

Returns:bytestring representation of the patch
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: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 ReviewComments

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 PullReviews

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

Update this pull request.

Parameters:
  • title (str) – (optional), title of the pull
  • body (str) – (optional), body of the pull request
  • state (str) – (optional), (‘open’, ‘closed’)
Returns:

bool


class github3.pulls.ReviewComment(json, session=None)

The ReviewComment object.

This is used to represent comments on pull requests.

Two comment instances can be checked like so:

c1 == c2
c1 != c2

And is equivalent to:

c1.id == c2.id
c1.id != c2.id

See also: http://developer.github.com/v3/pulls/comments/

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:bool
edit(body)

Edit this comment.

Parameters:body (str) – (required), new body of the comment, Markdown formatted
Returns:bool
from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

Return an instance of this class formed from json.

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(dest, direction)

The PullDestination object.

See also: http://developer.github.com/v3/pulls/#get-a-single-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
direction = None

Direction of the merge with respect to this destination

from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

Return an instance of this class formed from json.

label = None

label of the destination

ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
ref = None

Full reference string of the object

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
sha = None

SHA of the commit at the head

user = None

User representing the owner


class github3.pulls.PullFile(json, session=None)

The PullFile object.

See also: http://developer.github.com/v3/pulls/#list-pull-requests-files

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:Contents
from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

Return an instance of this class formed from json.

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