Issue¶
This part of the documentation covers the module which handles Issue
s and their related objects:
Issue Objects¶
-
class
github3.issues.issue.
Issue
(json, session)¶ Object for the full representation of an Issue.
GitHub’s API returns different amounts of information about issues based upon how that information is retrieved. This object exists to represent the full amount of information returned for a specific issue. For example, you would receive this class when calling
issue()
. To provide a clear distinction between the types of issues, 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 a
ShortIssue
as well as the following:-
body_html
¶ The HTML formatted body of this issue.
-
body_text
¶ The plain-text formatted body of this issue.
-
closed_by
¶ If the issue is closed, a
ShortUser
representing the user who closed the issue.
-
add_labels
(*args)¶ Add labels to this issue.
Parameters: args (str) – (required), names of the labels you wish to add Returns: list of labels Return type: Label
-
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
-
assign
(username)¶ Assign user
username
to this issue.This is a short cut for
edit()
.Parameters: username (str) – username of the person to assign this issue to Returns: True if successful, False, otherwise Return type: bool
-
close
()¶ Close this issue.
Returns: True if successful, False otherwise Return type: bool
-
comment
(id_num)¶ Get a single comment by its id.
The catch here is that id is NOT a simple number to obtain. If you were to look at the comments on issue #15 in sigmavirus24/Todo.txt-python, the first comment’s id is 4150787.
Parameters: id_num (int) – (required), comment id, see example above Returns: the comment identified by id_num
Return type: IssueComment
-
comments
(number=-1, sort=u'', direction=u'', since=None)¶ Iterate over the comments on this issue.
Parameters: - number (int) – (optional), number of comments to iterate over Default: -1 returns all comments
- sort (str) – accepted valuees: (‘created’, ‘updated’) api-default: created
- direction (str) – accepted values: (‘asc’, ‘desc’) Ignored without the sort parameter
- since (datetime or string) – (optional), Only issues after this date will be returned. This can
be a
datetime
or an ISO8601 formatted date string, e.g.,2012-05-20T23:10:27Z
Returns: iterator of comments
Return type:
-
create_comment
(body)¶ Create a comment on this issue.
Parameters: body (str) – (required), comment body Returns: the created comment Return type: IssueComment
-
edit
(title=None, body=None, assignee=None, state=None, milestone=None, labels=None, assignees=None)¶ Edit this issue.
Parameters: - title (str) – title of the issue
- body (str) – markdown formatted body (description) of the issue
- assignee (str) – login name of user the issue should be assigned to
- state (str) – accepted values: (‘open’, ‘closed’)
- milestone (int) – the NUMBER (not title) of the milestone to assign this to [1], or 0 to remove the milestone
- labels (list) – list of labels to apply this to
- assignees (list of strings) – (optional), login of the users to assign the issue to
Returns: True if successful, False otherwise
Return type: bool
[1] Milestone numbering starts at 1, i.e. the first milestone you create is 1, the second is 2, etc.
-
events
(number=-1)¶ Iterate over events associated with this issue only.
Parameters: number (int) – (optional), number of events to return. Default: -1 returns all events available. Returns: generator of events on this issues Return type: IssueEvent
-
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_closed
()¶ Check if the issue is closed.
Returns: True if successful, False otherwise Return type: bool
-
labels
(number=-1, etag=None)¶ Iterate over the labels associated with this issue.
Parameters: - number (int) – (optional), number of labels to return. Default: -1 returns all labels applied to this issue.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of labels on this issue
Return type:
-
lock
()¶ Lock an issue.
Returns: True if successful, False otherwise Return type: bool
-
new_session
()¶ Generate a new session.
Returns: A brand new session Return type: GitHubSession
-
pull_request
()¶ Retrieve the pull request associated with this issue.
Returns: the pull request associated with this issue Return type: PullRequest
-
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
-
remove_all_labels
()¶ Remove all labels from this issue.
Returns: the list of current labels (empty) if successful Return type: list
-
remove_label
(name)¶ Remove label
name
from this issue.Parameters: name (str) – (required), name of the label to remove Returns: list of removed labels Return type: Label
-
reopen
()¶ Re-open a closed issue.
Note
This is a short cut to using
edit()
.Returns: True if successful, False otherwise Return type: bool
-
replace_labels
(labels)¶ Replace all labels on this issue with
labels
.Parameters: labels (list) – label names Returns: list of labels Return type: Label
-
unlock
()¶ Unlock an issue.
Returns: True if successful, False otherwise Return type: bool
-
-
class
github3.issues.comment.
IssueComment
(json, session)¶ Representation of a comment left on an issue.
See also: http://developer.github.com/v3/issues/comments/
This object has the following attributes:
The association of the author (
user
) with the repository this issue belongs to.
-
body
¶ The markdown formatted original text written by the author.
-
body_html
¶ The HTML formatted comment body.
-
body_text
¶ The plain-text formatted comment body.
-
created_at
¶ A
datetime
object representing the date and time when this comment was created.
-
html_url
¶ The URL to view this comment in a browser.
-
id
¶ The unique identifier for this comment.
-
issue_url
¶ The URL of the parent issue in the API.
-
updated_at
¶ A
datetime
object representing the date and time when this comment was most recently updated.
-
user
¶ A
ShortUser
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: bool
-
edit
(body)¶ Edit this comment.
Parameters: body (str) – (required), new body of the comment, Markdown formatted Returns: 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
-
class
github3.issues.event.
IssueEvent
(json, session)¶ Representation of an event from a specific issue.
This object will be instantiated from calling
events()
which calls https://developer.github.com/v3/issues/events/#list-events-for-an-issueSee also: http://developer.github.com/v3/issues/events
This object has the following attributes:
-
actor
¶ A
ShortUser
representing the user who generated this event.
-
commit_id
¶ The string SHA of a commit that referenced the parent issue. If there was no commit referencing this issue, then this will be
None
.
-
commit_url
¶ The URL to retrieve commit information from the API for the commit that references the parent issue. If there was no commit, this will be
None
.
-
created_at
¶ A
datetime
object representing the date and time this event occurred.
-
event
¶ The issue-specific action that generated this event. Some examples are:
- closed
- reopened
- subscribed
- merged
- referenced
- mentioned
- assigned
See this list of events for a full listing.
-
id
¶ The unique identifier for this event.
-
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.issues.milestone.
Milestone
(json, session)¶ Representation of milestones on a repository.
See also: http://developer.github.com/v3/issues/milestones/
This object has the following attributes:
-
closed_issues_count
¶ The number of closed issues in this milestone.
-
created_at
¶ A
datetime
object representing the date and time when this milestone was created.
-
creator
¶ If present, a
ShortUser
representing the user who created this milestone.
-
description
¶ The written description of this milestone and its purpose.
-
due_on
¶ If set, a
datetime
object representing the date and time when this milestone is due.
-
id
¶ The unique identifier of this milestone in GitHub.
-
number
¶ The repository-local numeric identifier of this milestone. This starts at 1 like issues.
-
open_issues_count
¶ The number of open issues still in this milestone.
-
state
¶ The state of this milestone, e.g.,
'open'
or'closed'
.
-
title
¶ The title of this milestone.
-
updated_at
¶ A
datetime
object representing the date and time when this milestone 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
-
delete
()¶ Delete this milestone.
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
.
-
labels
(number=-1, etag=None)¶ Iterate over the labels of every associated issue.
Changed in version 0.9: Add etag parameter.
Parameters: - number (int) – (optional), number of labels to return. Default: -1 returns all available labels.
- etag (str) – (optional), ETag header from a previous response
Returns: generator of labels
Return type:
-
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
-
update
(title=None, state=None, description=None, due_on=None)¶ Update this milestone.
All parameters are optional, but it makes no sense to omit all of them at once.
Parameters: - title (str) – (optional), new title of the milestone
- state (str) – (optional), (‘open’, ‘closed’)
- description (str) – (optional)
- due_on (str) – (optional), ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ
Returns: True if successful, False otherwise
Return type: bool
-
-
class
github3.issues.label.
Label
(json, session)¶ A representation of a label object defined on a repository.
See also: http://developer.github.com/v3/issues/labels/
This object has the following attributes:
.. attribute:: color
The hexadecimeal representation of the background color of this label.-
name
¶ The name (display label) for this label.
-
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 label.
Returns: True if successfully deleted, 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
-
update
(name, color)¶ Update this label.
Parameters: - name (str) – (required), new name of the label
- color (str) – (required), color code, e.g., 626262, no leading ‘#’
Returns: True if successfully updated, False otherwise
Return type: bool
-