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

This object holds all the information returned by Github about a gist.

With it you can comment on or fork the gist (assuming you are authenticated), edit or delete the gist (assuming you own it). You can also “star” or “unstar” the gist (again assuming you have authenticated).

Two gist instances can be checked like so:

g1 == g2
g1 != g2

And is equivalent to:

g1.id == g2.id
g1.id != g2.id

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

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 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 GistHistory

create_comment(body)

Create a comment on this gist.

Parameters:body (str) – (required), body of the comment
Returns:GistComment
delete()

Delete this gist.

Returns:bool – whether the deletion was successful
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:

bool – whether the edit was successful

files()

Iterator over the files stored in this gist.

Returns:generator of :class`GistFile <github3.gists.file.GistFile>`
fork()

Fork this gist.

Returns:Gist if successful, None otherwise
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 Gist

from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

Return an instance of this class formed from json.

is_starred()

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

Returns:bool – True if it is starred, False otherwise
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:bool – True if successful, False otherwise
unstar()

Un-star this gist.

Returns:bool – True if successful, False otherwise

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

This object represents a comment on a gist.

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/gists/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
from_dict(json_dict)

Return an instance of this class formed from json_dict.

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

This represents the file object returned by interacting with gists.

It stores the raw url of the file, the file name, language, size and content.

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’ if there is no ‘content’ key in Gist object.

from_dict(json_dict)

Return an instance of this class formed from json_dict.

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

Thisobject represents one version (or revision) of a gist.

Two history instances can be checked like so:

h1 == h2
h1 != h2

And is equivalent to:

h1.version == h2.version
h1.version != h2.version
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)

Return an instance of this class formed from json_dict.

from_json(json)

Return an instance of this class formed from json.

get_gist()

Retrieve the gist at this version.

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