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 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: 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:
-
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:
-
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:
-
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 withmerge_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:
-
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.
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.
-
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
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
-
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
-