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
.
- 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.
- 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.
- links
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 beNone
.
- 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 thebase
instance.
- 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.
- 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:
- 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:
- 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 toPENDING
which means that your review will need to be submitted after creation. (See alsosubmit()
.)- 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:
- 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:
- 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:
- 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:
- 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 withmerge_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:
- 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:
- 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 ifmergeable
is still being decided by GitHub this will beNone
.
- 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:
- 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:
- 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 toPENDING
which means that your review will need to be submitted after creation. (See alsosubmit()
.)- 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:
- 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:
- 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:
- 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:
- 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 withmerge_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:
- 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:
- 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
andBase
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’)
- 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:
- 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:
- 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:
- 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.
- links
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.
- 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:
- 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: