Issues API Objects — github3.py 4.0.1 documentation (original) (raw)

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

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 datetimeobject representing the date and time this issue was closed. Otherwise it will be None.

The number of comments on this issue.

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.

milestone

A Milestone object representing the milestone to which this issue was assigned.

number

The number identifying this issue on its parent repository.

original_labels

If any are assigned to this issue, the list ofShortLabel 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.

user

A ShortUser representing the user who opened 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

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

Iterate over the comments on this issue.

Parameters:

Returns:

iterator of comments

Return type:

IssueComment

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:

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:

IssueEvent

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:

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:

GitHubSession

pull_request()

Retrieve the pull request associated with this issue.

Returns:

the pull request associated with this issue

Return type:

PullRequest

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 callingissue(). 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 aShortIssue 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 ShortUserrepresenting the user who closed the 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

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

Iterate over the comments on this issue.

Parameters:

Returns:

iterator of comments

Return type:

IssueComment

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:

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:

IssueEvent

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:

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:

GitHubSession

pull_request()

Retrieve the pull request associated with this issue.

Returns:

the pull request associated with this issue

Return type:

PullRequest

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 Events

class github3.issues.event.IssueEvent(json, session: GitHubSession)

Representation of an event from a specific issue.

This object will be instantiated from callingevents() which callshttps://developer.github.com/v3/issues/events/#list-events-for-an-issue

See 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 beNone.

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:

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:

GitHubSession

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 callingissue_events() orissue_events() which callhttps://developer.github.com/v3/issues/events/#list-events-for-a-repository

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

This object has all of the attributes ofIssueEvent 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:

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:

GitHubSession

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:

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.

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

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:

Returns:

generator of labels

Return type:

ShortLabel

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

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:

Returns:

True if successful, False otherwise

Return type:

bool