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(data, 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/

comments = None

Number of comments on this gist

comments_url = None

Comments URL (not a template)

commits_url = None

Commits URL (not a template)

create_comment(body)

Create a comment on this gist.

Parameters:body (str) – (required), body of the comment
Returns:GistComment
created_at = None

datetime object representing when the gist was created.

delete()

Delete this gist.

Returns:bool – whether the deletion was successful
description = None

Description of the gist

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

Number of files in this gist.

fork()

Fork this gist.

Returns:Gist if successful, None otherwise
forks = None

The number of forks of this gist.

forks_url = None

Forks URL (not a template)

from_json(json)

Return an instance of cls formed from json.

git_pull_url = None

Git URL to pull this gist, e.g., git://gist.github.com/1.git

git_push_url = None

Git URL to push to gist, e.g., git@gist.github.com/1.git

history = None

History of this gist, list of GistHistory

html_url = None

URL of this gist at Github, e.g., https://gist.github.com/1

id = None

Unique id for this gist.

is_public()

Check to see if this gist is public or not.

Returns:bool – True if public, False if private
is_starred()

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

Returns:bool – True if it is starred, False otherwise
iter_comments(number=-1, etag=None)

List 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

iter_commits(number=-1, etag=None)

Iter 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

iter_files()

Iterator over the files stored in this gist.

Returns:generator of :class`GistFile <github3.gists.file.GistFile>`
iter_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

owner = None

User object representing the owner of the gist.

public = None

Boolean describing if the gist is public or private

ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

star()

Star this gist.

Returns:bool – True if successful, False otherwise
to_json()

Return the json representing this object.

truncated = None

Whether the content of this Gist has been truncated or not

unstar()

Un-star this gist.

Returns:bool – True if successful, False otherwise
updated_at = None

datetime object representing the last time this gist was updated.


class github3.gists.comment.GistComment(comment, 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/

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_json(json)

Return an instance of cls 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 and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

to_json()

Return the json representing this object.

user = None

User who made the comment Unless it is not associated with an account


class github3.gists.file.GistFile(attributes)

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.

content = None

The content of the file.

filename = None

The name of the file.

from_json(json)

Return an instance of cls formed from json.

language = None

The language associated with the file.

name = None

The name of the file.

raw_url = None

The raw URL for the file at GitHub.

size = None

The size of the file.

to_json()

Return the json representing this object.


class github3.gists.history.GistHistory(history, 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
additions = None

number of additions made

change_status = None

dict containing the change status; see also: deletions, additions, total

committed_at = None

datetime representation of when the commit was made

deletions = None

number of deletions made

from_json(json)

Return an instance of cls 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 and returns the refreshed instance.

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

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.iter_repos('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.iter_repos('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

to_json()

Return the json representing this object.

total = None

total number of changes made

user = None

user who made these changes

version = None

SHA of the commit associated with this version