Pull Request

This section of the documentation covers:

Pull Request Objects

class github3.pulls.PullRequest(pull, 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/

additions = None

Number of additions on this pull request

assignee = None

User object representing the assignee of the pull request

base = None

Base of the merge

body = None

Body of the pull request message

body_html = None

Body of the pull request as HTML

body_text = None

Body of the pull request as plain text

close()

Closes this Pull Request without merging.

Returns:bool
closed_at = None

datetime object representing when the pull was closed

comments = None

Number of comments

comments_url = None

Comments url (not a template)

commits = None

Number of commits

commits_url = None

GitHub.com url of commits in this pull request

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

created_at = None

datetime object representing when the pull was created

deletions = None

Number of deletions on this pull request

diff()

Return the diff

diff_url = None

URL to view the diff associated with the pull

from_json(json)

Return an instance of cls formed from json.

head = None

The new head after the pull request

html_url = None

The URL of the pull request

id = None

The unique id of the pull request

is_merged()

Checks to see if the pull request was merged.

Returns:bool
issue_url = None

The URL of the associated issue

iter_comments(number=-1, etag=None)

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

iter_commits(number=-1, etag=None)

Iterates 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 Commits

iter_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

iter_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

Dictionary of _links

merge(commit_message=u'')

Merge this pull request.

Parameters:commit_message (str) – (optional), message to be used for the merge commit
Returns:bool
merge_commit_sha = None

SHA of the merge commit. DEPRECATED

mergeable = None

Whether the pull is deemed mergeable by GitHub

mergeable_state = None

Whether it would be a clean merge or not

merged_at = None

datetime object representing when the pull was merged

merged_by = None

User who merged this pull

number = None

Number of the pull/issue on the repository

patch()

Return the patch

patch_url = None

The URL 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 and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

reopen()

Re-open a closed Pull Request.

Returns:bool
repository = None

Returns (‘owner’, ‘repository’) this issue was filed on.

review_comment_url = None

Review comment URL Template. Expands with number

review_comments(number=-1, etag=None)

Iterate over the review comments on this pull request. :param int number: (optional), number of comments to return. Default:

-1 returns all available comments.
Parameters:etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:generator of ReviewComments
review_comments_count = None

Number of review comments on the pull request

review_comments_url = None

GitHub.com url for review comments (not a template)

state = None

The state of the pull

statuses_url = None

Statuses URL

title = None

The title of the request

to_json()

Return the json representing this object.

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

updated_at = None

datetime object representing the last time the object was changed

user = None

User object representing the creator of the pull request


class github3.pulls.ReviewComment(comment, 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/

commit_id = None

SHA of the commit the comment is on

delete()

Delete this comment.

Returns:bool
diff_hunk = None

The diff hunk

edit(body)

Edit this comment.

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

Return an instance of cls formed from json.

original_commit_id = None

Original commit SHA

original_position = None

Original position inside the file

path = None

Path to the file

position = None

Position within the commit

pull_request_url = None

API URL for the Pull Request

ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

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
to_json()

Return the json representing this object.

user = None

User who made the comment


class github3.pulls.PullDestination(dest, direction)

The PullDestination object.

See also: http://developer.github.com/v3/pulls/#get-a-single-pull-request

direction = None

Direction of the merge with respect to this destination

from_json(json)

Return an instance of cls 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 and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

sha = None

SHA of the commit at the head

to_json()

Return the json representing this object.

user = None

User representing the owner


class github3.pulls.PullFile(pfile)

The PullFile object.

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

additions = None

Number of additions on this file

blob_url = None

URL to view the blob for this file

changes = None

Number of changes made to this file

deletions = None

Number of deletions on this file

filename = None

Name of the file

from_json(json)

Return an instance of cls formed from json.

patch = None

Patch generated by this pull request

raw_url = None

URL to view the raw diff of this file

sha = None

SHA of the commit

status = None

Status of the file, e.g., ‘added’

to_json()

Return the json representing this object.