Gists

This part of the documentation details the properties and methods associated with Gist, GistComment, GistHistory, and GistFile objects. These classes should never be instantiated by the user (developer) directly.

Gist Objects

class github3.gists.gist.Gist(json, session)

This object constitutes the full representation of a Gist.

GitHub’s API returns different amounts of information about gists based upon how that information is retrieved. This object exists to represent the full amount of information returned for a specific gist. For example, you would receive this class when calling gist(). To provide a clear distinction between the types of gists, github3.py uses different classes with different sets of attributes.

This object has all the same attributes as ShortGist as well as:

commits_url

The URL to retrieve gist commits from the GitHub API.

original_forks

A list of GistFork objects representing each fork of this gist. To retrieve the most recent list of forks, use the forks() method.

forks_url

The URL to retrieve the current listing of forks of this gist.

history

A list of GistHistory objects representing each change made to this gist.

truncated

This is a boolean attribute that indicates whether the content of this Gist has been truncated or not.

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
comments(number=-1, etag=None)

Iterate over comments on this gist.

Parameters:
  • number (int) – (optional), number of comments to iterate over. Default: -1 will iterate over all comments on the gist
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of comments

Return type:

GistComment

commits(number=-1, etag=None)

Iterate over the commits on this gist.

These commits will be requested from the API and should be the same as what is in Gist.history.

New in version 0.6.

Changed in version 0.9: Added param etag.

Parameters:
  • number (int) – (optional), number of commits to iterate over. Default: -1 will iterate over all commits associated with this gist.
  • etag (str) – (optional), ETag from a previous request to this endpoint.
Returns:

generator of the gist’s history

Return type:

GistHistory

create_comment(body)

Create a comment on this gist.

Parameters:body (str) – (required), body of the comment
Returns:Created comment or None
Return type:GistComment
delete()

Delete this gist.

Returns:Whether the deletion was successful or not
Return type:bool
edit(description=u'', files={})

Edit this gist.

Parameters:
  • description (str) – (optional), description of the gist
  • files (dict) – (optional), files that make up this gist; the key(s) should be the file name(s) and the values should be another (optional) dictionary with (optional) keys: ‘content’ and ‘filename’ where the former is the content of the file and the latter is the new name of the file.
Returns:

Whether the edit was successful or not

Return type:

bool

fork()

Fork this gist.

Returns:New gist if successfully forked, None otherwise
Return type:ShortGist
forks(number=-1, etag=None)

Iterator of forks of this gist.

Changed in version 0.9: Added params number and etag.

Parameters:
  • number (int) – (optional), number of forks to iterate over. Default: -1 will iterate over all forks of this gist.
  • etag (str) – (optional), ETag from a previous request to this endpoint.
Returns:

generator of gists

Return type:

ShortGist

from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

is_starred()

Check to see if this gist is starred by the authenticated user.

Returns:True if it is starred, False otherwise
Return type:bool
new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
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
star()

Star this gist.

Returns:True if successful, False otherwise
Return type:bool
unstar()

Un-star this gist.

Returns:True if successful, False otherwise
Return type:bool

class github3.gists.comment.GistComment(json, session)

Representation of a comment left on a Gist.

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

Changed in version 1.0.0: The links, html_url, and pull_request_url attributes were removed as none of them exist in the response from GitHub.

This object has the following attributes:

author_association

The comment author’s (user) association with this gist.

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.

id

The unique identifier for this comment.

updated_at

A datetime object representing the date and time when this comment was most recently updated.

user

A ShortUser representing the author of this comment.

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 from the gist.

Returns:True if successful, False otherwise
Return type:bool
edit(body)

Edit this comment.

Parameters:body (str) – (required), new body of the comment, Markdown-formatted
Returns:True if successful, False otherwise
Return type:bool
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

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
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.gists.file.GistFile(json, session)

This represents the full file object returned by interacting with gists.

The object has all of the attributes as returned by the API for a ShortGistFile as well as:

truncated

A boolean attribute that indicates whether original_content contains all of the file’s contents.

original_content

The contents of the file (potentially truncated) returned by the API. If the file was truncated use content() to retrieve it in its entirety.

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
content()

Retrieve contents of file from key ‘raw_url’.

Returns:unaltered, untruncated contents of file.
Return type:bytes
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

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
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.gists.history.GistHistory(json, session)

This object represents one version (or revision) of a gist.

The GitHub API returns the following attributes:

url

The URL to the revision of the gist retrievable through the API.

version

The commit ID of the revision of the gist.

user

The ShortUser representation of the user who owns this gist.

committed_at

The date and time of the revision’s commit.

change_status

A dictionary with the number of deletions, additions, and total changes to the gist.

For convenience, github3.py also exposes the following attributes from the change_status:

additions

The number of additions to the gist compared to the previous revision.

deletions

The number of deletions from the gist compared to the previous revision.

totoal

The total number of changes to the gist compared to the previous revision.

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
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

gist()

Retrieve the gist at this version.

Returns:the gist at this point in history or None
Return type:Gist
new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
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