Pull Requests and their Associated Objects — github3.py 4.0.1 documentation (original) (raw)
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.
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.
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 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 baseinstance.
requested_reviewers
A list of ShortUser from which a review was requested.
requested_teams
A list of ShortTeam from which a review was requested.
A URITemplate instance that expands to provide the review comment URL provided a number.
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:
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 to PENDING 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’sCreate 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 andbody.
Returns:
The created review.
Return type:
PullReview
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
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
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 callingpull_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 asShortPullRequest 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.
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.
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 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 to PENDING 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’sCreate 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 andbody.
Returns:
The created review.
Return type:
PullReview
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
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
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’)
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:
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 Nonein 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
Object representing review comments left on a pull request.
Please see GitHub’s Pull Comments Documentation for more information.
The unique identifier for this comment across all GitHub review comments.
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.
The SHA of current commit this comment was left on.
A datetime instance representing the date and time this comment was created.
A string representation of the hunk of the diff where the comment was left.
The URL to view this comment in the webbrowser.
A dictionary of relevant URLs usually returned in the _linksattribute.
The SHA of the original commit this comment was left on.
The original position within the diff that this comment was left on.
The URL to retrieve the pull request via the API.
A datetime instance representing the date and time this comment was updated.
A ShortUser instance representing the author of this comment.
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
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 this comment.
Returns:
True if successful, False otherwise
Return type:
bool
Edit this comment.
Parameters:
body (str) – (required), new body of the comment, Markdown formatted
Returns:
True if successful, False otherwise
Return type:
bool
Return an instance of this class formed from json_dict.
Return an instance of this class formed from json.
Generate a new session.
Returns:
A brand new session
Return type:
property ratelimit_remaining
Number of requests before GitHub imposes a ratelimit.
Returns:
int
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 to this review comment with a new review comment.
Parameters:
body (str) – The text of the comment.
Returns:
The created review comment.
Return type: