Issues

classgithub3.issues.issue.ShortIssue(json,session:GitHubSession)

Object for the shortened representation of an Issue.

GitHub’s API returns different amounts of information about issues basedupon how that information is retrieved. Often times, when iterating overseveral issues, GitHub will return less information. To provide a cleardistinction between the types of issues, github3.py uses different classeswith 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 inthe 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 asa list ofShortUser.

body

The markdown formatted text of the issue as writen by the user whoopened the issue.

closed_at

If this issue is closed, this will be adatetimeobject representing the date and time this issue was closed. Otherwiseit 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

Adatetime object representing the date and timethis 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

AURITemplate object that can expand to a URL toretrieve the labels on this issue from the API.

locked

A boolean attribute representing whether or not this issue is locked.

milestone

AMilestone object representing themilestone 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 thelabels returned by the API for this issue.

pull_request_urls

If present, a dictionary of URLs for retrieving information about theassociated 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

Adatetime object representing the date and timewhen this issue was last updated.

user

AShortUser representing the user who openedthis issue.

add_assignees(users)

Assignusers to this issue.

This is a shortcut foredit().

Parameters:

users (list ofstr) – 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. Ifyou were to look at the comments on issue #15 insigmavirus24/Todo.txt-python, the first comment’s id is 4150787.

Parameters:

id_num (int) – (required), comment id, see example above

Returns:

the comment identified byid_num

Return type:

IssueComment

comments(number=-1,sort='',direction='',since=None)

Iterate over the comments on this issue.

Parameters:

• number (int) – (optional), number of comments to iterate overDefault: -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 orstring) – (optional), Only issues after this date will be returned. This canbe adatetime or an ISO8601 formatted date string, e.g.,2012-05-20T23:10:27Z

Returns:

iterator of comments

Return type:

IssueComment

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,or 0 to remove the milestone

  Note

  This is not the milestone’s globally unique identifier, it’svalue innumber.

• labels (list) – list of labels to apply this to

• assignees (list ofstrings) – (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 allevents available.

Returns:

generator of events on this issues

Return type:

IssueEvent

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

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

GitHubSession

pull_request()

Retrieve the pull request associated with this issue.

Returns:

the pull request associated with this issue

Return type:

PullRequest

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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)

Unassignusers from this issue.

This is a shortcut foredit().

Parameters:

users (list ofstr) – users or usernames to unassign this issue from

Returns:

True if successful, False otherwise

Return type:

bool

remove_label(name)

Remove labelname 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 usingedit().

Returns:

True if successful, False otherwise

Return type:

bool

replace_labels(labels)

Replace all labels on this issue withlabels.

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

classgithub3.issues.issue.Issue(json,session:GitHubSession)

Object for the full representation of an Issue.

GitHub’s API returns different amounts of information about issues basedupon how that information is retrieved. This object exists to representthe full amount of information returned for a specific issue. For example,you would receive this class when callingissue(). To provide a cleardistinction between the types of issues, github3.py uses different classeswith 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, aShortUserrepresenting the user who closed the issue.

add_assignees(users)

Assignusers to this issue.

This is a shortcut foredit().

Parameters:

users (list ofstr) – 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. Ifyou were to look at the comments on issue #15 insigmavirus24/Todo.txt-python, the first comment’s id is 4150787.

Parameters:

id_num (int) – (required), comment id, see example above

Returns:

the comment identified byid_num

Return type:

IssueComment

comments(number=-1,sort='',direction='',since=None)

Iterate over the comments on this issue.

Parameters:

• number (int) – (optional), number of comments to iterate overDefault: -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 orstring) – (optional), Only issues after this date will be returned. This canbe adatetime or an ISO8601 formatted date string, e.g.,2012-05-20T23:10:27Z

Returns:

iterator of comments

Return type:

IssueComment

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,or 0 to remove the milestone

  Note

  This is not the milestone’s globally unique identifier, it’svalue innumber.

• labels (list) – list of labels to apply this to

• assignees (list ofstrings) – (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 allevents available.

Returns:

generator of events on this issues

Return type:

IssueEvent

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

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

GitHubSession

pull_request()

Retrieve the pull request associated with this issue.

Returns:

the pull request associated with this issue

Return type:

PullRequest

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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)

Unassignusers from this issue.

This is a shortcut foredit().

Parameters:

users (list ofstr) – users or usernames to unassign this issue from

Returns:

True if successful, False otherwise

Return type:

bool

remove_label(name)

Remove labelname 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 usingedit().

Returns:

True if successful, False otherwise

Return type:

bool

replace_labels(labels)

Replace all labels on this issue withlabels.

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

classgithub3.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:

author_association

The association of the author (user) with the repositorythis 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

Adatetime object representing the date and timewhen 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

Adatetime object representing the date and timewhen this comment was most recently updated.

user

AShortUser representing the author of thiscomment.

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, Markdownformatted

Returns:

bool

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

Issue Events

classgithub3.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

AShortUser representing the user whogenerated this event.

commit_id

The string SHA of a commit that referenced the parent issue. If therewas no commit referencing this issue, then this will beNone.

commit_url

The URL to retrieve commit information from the API for the committhat references the parent issue. If there was no commit, this will beNone.

created_at

Adatetime object representing the date and timethis event occurred.

event

The issue-specific action that generated this event. Some examplesare:

• closed

• reopened

• subscribed

• merged

• referenced

• mentioned

• assigned

Seethis 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

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

classgithub3.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

AShortIssue representing the issuewhere this event originated from.

Issue Labels

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

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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

classgithub3.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

Adatetime object representing the date and timewhen this milestone was created.

creator

If present, aShortUser representing the userwho created this milestone.

description

The written description of this milestone and its purpose.

due_on

If set, adatetime object representing the date andtime when this milestone is due.

id

The unique identifier of this milestone in GitHub.

number

The repository-local numeric identifier of this milestone. This startsat 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

Adatetime object representing the date and timewhen 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

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

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

GitHubSession

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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 themat 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