Issue

This part of the documentation covers the module which handles Issues and their related objects:

Issue Objects

class github3.issues.issue.Issue(json, session=None)

The Issue object. It structures and handles the data returned via the Issues section of the GitHub API.

Two issue instances can be checked like so:

i1 == i2
i1 != i2

And is equivalent to:

i1.id == i2.id
i1.id != i2.id
add_labels(*args)

Add labels to this issue.

Parameters:args (str) – (required), names of the labels you wish to add
Returns:list of Labels
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)

Assigns user username to this issue. This is a short cut for issue.edit.

Parameters:username (str) – username of the person to assign this issue to
Returns:bool
close()

Close this issue.

Returns: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:IssueComment
comments(number=-1)

Iterate over the comments on this issue.

Parameters:number (int) – (optional), number of comments to iterate over
Returns:iterator of IssueComments
create_comment(body)

Create a comment on this issue.

Parameters:body (str) – (required), comment body
Returns:IssueComment
edit(title=None, body=None, assignee=None, state=None, milestone=None, labels=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
Returns:

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 IssueEvents
classmethod from_dict(json_dict)

Return an instance of this class formed from json_dict.

classmethod from_json(json)

Return an instance of this class formed from json.

is_closed()

Checks if the issue is closed.

Returns: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

pull_request()

Retrieve the pull request associated with this issue.

Returns: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:an empty list if successful
remove_label(name)

Removes label name from this issue.

Parameters:name (str) – (required), name of the label to remove
Returns:bool
reopen()

Re-open a closed issue.

Returns:bool
replace_labels(labels)

Replace all labels on this issue with labels.

Parameters:labels (list) – label names
Returns:bool

class github3.issues.comment.IssueComment(json, session=None)

The IssueComment object. This structures and handles the comments on issues specifically.

Two comment instances can be checked like so:

c1 == c2
c1 != c2

And is equivalent to:

c1.id == c2.id
c1.id != c2.id

See also: http://developer.github.com/v3/issues/comments/

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)

Return an instance of this class formed from json_dict.

classmethod from_json(json)

Return an instance of this class formed from json.

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=None)

The IssueEvent object. This specifically deals with events described in the Issues>Events section of the GitHub API.

Two event instances can be checked like so:

e1 == e2
e1 != e2

And is equivalent to:

e1.commit_id == e2.commit_id
e1.commit_id != e2.commit_id
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)

Return an instance of this class formed from json_dict.

classmethod from_json(json)

Return an instance of this class formed from json.

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=None)

The Milestone object. This is a small class to handle information about milestones on repositories and issues.

See also: http://developer.github.com/v3/issues/milestones/

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:bool
classmethod from_dict(json_dict)

Return an instance of this class formed from json_dict.

classmethod from_json(json)

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

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:

bool


class github3.issues.label.Label(json, session=None)

The Label object. Succintly represents a label that exists in a repository.

See also: http://developer.github.com/v3/issues/labels/

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:bool
classmethod from_dict(json_dict)

Return an instance of this class formed from json_dict.

classmethod from_json(json)

Return an instance of this class formed from json.

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:

bool