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 theforks()
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:
-
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:
-
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='', 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
otherwiseReturn type: ShortGist
-
forks
(number=-1, etag=None)¶ Iterator of forks of this gist.
Changed in version 0.9: Added params
number
andetag
.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
, andpull_request_url
attributes were removed as none of them exist in the response from GitHub.This object has the following attributes:
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
-