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
class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
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
Issue.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
Issue.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
Issue.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
Issue.close()

Close this issue.

Returns:bool
Issue.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
Issue.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 IssueComments

Issue.create_comment(body)

Create a comment on this issue.

Parameters:body (str) – (required), comment body
Returns:IssueComment
Issue.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:

bool

[1]Milestone numbering starts at 1, i.e. the first milestone you create is 1, the second is 2, etc.
Issue.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
Issue.from_dict(json_dict)

Return an instance of this class formed from json_dict.

Issue.from_json(json)

Return an instance of this class formed from json.

Issue.is_closed()

Checks if the issue is closed.

Returns:bool
Issue.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

Issue.lock()

Lock an issue.

Returns:bool
Issue.pull_request()

Retrieve the pull request associated with this issue.

Returns:PullRequest
Issue.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
Issue.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
Issue.remove_all_labels()

Remove all labels from this issue.

Returns:an empty list if successful
Issue.remove_label(name)

Removes label name from this issue.

Parameters:name (str) – (required), name of the label to remove
Returns:list of Label
Issue.reopen()

Re-open a closed issue.

Returns:bool
Issue.replace_labels(labels)

Replace all labels on this issue with labels.

Parameters:labels (list) – label names
Returns:list of Label
Issue.unlock()

Unlock an issue.

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/

class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
IssueComment.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
IssueComment.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
IssueComment.delete()

Delete this comment.

Returns:bool
IssueComment.edit(body)

Edit this comment.

Parameters:body (str) – (required), new body of the comment, Markdown formatted
Returns:bool
IssueComment.from_dict(json_dict)

Return an instance of this class formed from json_dict.

IssueComment.from_json(json)

Return an instance of this class formed from json.

IssueComment.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
IssueComment.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
class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
IssueEvent.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
IssueEvent.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
IssueEvent.from_dict(json_dict)

Return an instance of this class formed from json_dict.

IssueEvent.from_json(json)

Return an instance of this class formed from json.

IssueEvent.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
IssueEvent.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/

class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
Milestone.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
Milestone.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
Milestone.delete()

Delete this milestone.

Returns:bool
Milestone.from_dict(json_dict)

Return an instance of this class formed from json_dict.

Milestone.from_json(json)

Return an instance of this class formed from json.

Milestone.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

Milestone.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
Milestone.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
Milestone.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/

class Empty

Class to indicate something wasn’t returned by the API.

The Empty class indicates that the attribute requested was not found in the json returned by the API. The Empty class is declared in every GitHubCore subclass using GitHubCore.Empty.

A model’s field can be checked for Empty like so:

# type(user) == github3.users.User
user.owner_private_repos is not user.Empty

And that is equivalent to:

from github3.empty import Empty
user.owner_private_repos is not Empty
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
Label.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
Label.delete()

Delete this label.

Returns:bool
Label.from_dict(json_dict)

Return an instance of this class formed from json_dict.

Label.from_json(json)

Return an instance of this class formed from json.

Label.ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
Label.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
Label.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