Issues API Objects¶
The following objects represent data returned by the Issues API
Issues¶
- class github3.issues.issue.ShortIssue(json, session: GitHubSession)¶
Object for the shortened representation of an Issue.
GitHub’s API returns different amounts of information about issues based upon how that information is retrieved. Often times, when iterating over several issues, GitHub will return less information. To provide a clear distinction between the types of issues, github3.py uses different classes with different sets of attributes.
New in version 1.0.0.
This object has the following attributes:
- assignee¶
Deprecated since version 1.0.0: While the API still returns this attribute, it’s not as useful in the context of multiple assignees.
If a user is assigned to this issue, then it will be represented as a
ShortUser
.
- assignees¶
If users are assigned to this issue, then they will be represented as a list of
ShortUser
.
- body¶
The markdown formatted text of the issue as writen by the user who opened the issue.
- closed_at¶
If this issue is closed, this will be a
datetime
object representing the date and time this issue was closed. Otherwise it will beNone
.
- comments_count¶
The number of comments on this issue.
- comments_url¶
The URL to retrieve the comments on this issue from the API.
- created_at¶
A
datetime
object representing the date and time this issue was created.
- events_url¶
The URL to retrieve the events related to this issue from the API.
- html_url¶
The URL to view this issue in a browser.
- id¶
The unique identifier for this issue in GitHub.
- labels_urlt¶
A
URITemplate
object that can expand to a URL to retrieve the labels on this issue from the API.
- locked¶
A boolean attribute representing whether or not this issue is locked.
- number¶
The number identifying this issue on its parent repository.
- original_labels¶
If any are assigned to this issue, the list of
ShortLabel
objects representing the labels returned by the API for this issue.
- pull_request_urls¶
If present, a dictionary of URLs for retrieving information about the associated pull request for this issue.
- state¶
The current state of this issue, e.g.,
'closed'
or'open'
.
- title¶
The title for this issue.
- updated_at¶
A
datetime
object representing the date and time when this issue was last updated.
- add_assignees(users)¶
Assign
users
to this issue.This is a shortcut for
edit()
.- Parameters
users (list of str) – users or usernames to assign this issue to
- Returns
True if successful, False otherwise
- Return type
bool
- 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
ShortLabel
- 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 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
- comments(number=-1, sort='', direction='', 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
- 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, or 0 to remove the milestone
Note
This is not the milestone’s globally unique identifier, it’s value in
number
.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
- 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
- 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_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
ShortLabel
- 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
- pull_request()¶
Retrieve the pull request associated with this issue.
- Returns
the pull request associated with this issue
- 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
- remove_all_labels()¶
Remove all labels from this issue.
- Returns
the list of current labels (empty) if successful
- Return type
list
- remove_assignees(users)¶
Unassign
users
from this issue.This is a shortcut for
edit()
.- Parameters
users (list of str) – users or usernames to unassign this issue from
- Returns
True if successful, False otherwise
- Return type
bool
- 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
ShortLabel
- 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
ShortLabel
- unlock()¶
Unlock an issue.
- Returns
True if successful, False otherwise
- Return type
bool
- class github3.issues.issue.Issue(json, session: GitHubSession)¶
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.
- add_assignees(users)¶
Assign
users
to this issue.This is a shortcut for
edit()
.- Parameters
users (list of str) – users or usernames to assign this issue to
- Returns
True if successful, False otherwise
- Return type
bool
- 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
ShortLabel
- 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 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
- comments(number=-1, sort='', direction='', 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
- 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, or 0 to remove the milestone
Note
This is not the milestone’s globally unique identifier, it’s value in
number
.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
- 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
- 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_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
ShortLabel
- 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
- pull_request()¶
Retrieve the pull request associated with this issue.
- Returns
the pull request associated with this issue
- 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
- remove_all_labels()¶
Remove all labels from this issue.
- Returns
the list of current labels (empty) if successful
- Return type
list
- remove_assignees(users)¶
Unassign
users
from this issue.This is a shortcut for
edit()
.- Parameters
users (list of str) – users or usernames to unassign this issue from
- Returns
True if successful, False otherwise
- Return type
bool
- 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
ShortLabel
- 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
ShortLabel
- unlock()¶
Unlock an issue.
- Returns
True if successful, False otherwise
- Return type
bool
Issue Comments¶
- class github3.issues.comment.IssueComment(json, session: GitHubSession)¶
Representation of a comment left on an issue.
See also: http://developer.github.com/v3/issues/comments/
This object has the following attributes:
- 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.
- 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
- 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
Issue Events¶
- class github3.issues.event.IssueEvent(json, session: GitHubSession)¶
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:
- 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
- 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.issues.event.RepositoryIssueEvent(json, session: GitHubSession)¶
Representation of an issue event on the repository level.
This object will be instantiated from calling
issue_events()
orissue_events()
which call https://developer.github.com/v3/issues/events/#list-events-for-a-repositorySee also: http://developer.github.com/v3/issues/events
This object has all of the attributes of
IssueEvent
and the following:- issue¶
A
ShortIssue
representing the issue where this event originated from.
Issue Labels¶
- class github3.issues.label.Label(json, session: GitHubSession)¶
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.
- description¶
The description for 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
- 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
- update(name, color, description=None)¶
Update this label.
- Parameters
name (str) – (required), new name of the label
color (str) – (required), color code, e.g., 626262, no leading ‘#’
description (str) – (optional), new description of the label
- Returns
True if successfully updated, False otherwise
- Return type
bool
Milestone Objects¶
- class github3.issues.milestone.Milestone(json, session: GitHubSession)¶
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.
- 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
- 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
.
- 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
ShortLabel
- 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
- 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