8000 Touch up ShortGist and Gist docstrings · pythonthings/github3.py@b21bd44 · GitHub
[go: up one dir, main page]
Skip to content

Commit b21bd44

Browse files
sigmavirus24sigmavirus24
committed
Touch up ShortGist and Gist docstrings
1 parent 373a582 commit b21bd44

File tree

1 file changed

+67
-38
lines changed

1 file changed

+67
-38
lines changed

‎github3/gists/gist.py

Lines changed: 67 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,12 @@ def _repr(self):
6363
def create_comment(self, body):
6464
"""Create a comment on this gist.
6565
66-
:param str body: (required), body of the comment
67-
:returns: Created comment or None
68-
:rtype: :class:`~github3.gists.comment.GistComment`
66+
:param str body:
67+
(required), body of the comment
68+
:returns:
69+
Created comment or None
70+
:rtype:
71+
:class:`~github3.gists.comment.GistComment`
6972
"""
7073
json = None
7174
if body:
@@ -77,23 +80,28 @@ def create_comment(self, body):
7780
def delete(self):
7881
"""Delete this gist.
7982
80-
:returns: Whether the deletion was successful or not
81-
:rtype: bool
83+
:returns:
84+
Whether the deletion was successful or not
85+
:rtype:
86+
bool
8287
"""
8388
return self._boolean(self._delete(self._api), 204, 404)
8489

8590
@requires_auth
8691
def edit(self, description='', files={}):
8792
"""Edit this gist.
8893
89-
:param str description: (optional), description of the gist
90-
:param dict files: (optional), files that make up this gist; the
91-
key(s) should be the file name(s) and the values should be another
92-
(optional) dictionary with (optional) keys: 'content' and
93-
'filename' where the former is the content of the file and the
94-
latter is the new name of the file.
95-
:returns: Whether the edit was successful or not
96-
:rtype: bool
94+
:param str description:
95+
(optional), description of the gist
96+
:param dict files:
97+
(optional), files that make up this gist; the key(s) should be the
98+
file name(s) and the values should be another (optional) dictionary
99+
with (optional) keys: 'content' and 'filename' where the former is
100+
the content of the file and the latter is the new name of the file.
101+
:returns:
102+
Whether the edit was successful or not
103+
:rtype:
104+
bool
97105
"""
98106
data = {}
99107
json = None
@@ -112,8 +120,10 @@ def edit(self, description='', files={}):
112120
def fork(self):
113121
"""Fork this gist.
114122
115-
:returns: New gist if successfully forked, ``None`` otherwise
116-
:rtype: :class:`~github3.gists.gist.ShortGist`
123+
:returns:
124+
New gist if successfully forked, ``None`` otherwise
125+
:rtype:
126+
:class:`~github3.gists.gist.ShortGist`
117127
"""
118128
url = self._build_url('forks', base_url=self._api)
119129
json = self._json(self._post(url), 201)
@@ -123,21 +133,26 @@ def fork(self):
123133
def is_starred(self):
124134
"""Check to see if this gist is starred by the authenticated user.
125135
126-
:returns: True if it is starred, False otherwise
127-
:rtype: bool
136+
:returns:
137+
True if it is starred, False otherwise
138+
:rtype:
139+
bool
128140
"""
129141
url = self._build_url('star', base_url=self._api)
130142
return self._boolean(self._get(url), 204, 404)
131143

132144
def comments(self, number=-1, etag=None):
133145
"""Iterate over comments on this gist.
134146
135-
:param int number: (optional), number of comments to iterate over.
147+
:param int number:
148+
(optional), number of comments to iterate over.
136149
Default: -1 will iterate over all comments on the gist
137-
:param str etag: (optional), ETag from a previous request to the same
138-
endpoint
139-
:returns: generator of comments
140-
:rtype: :class:`~github3.gists.comment.GistComment`
150+
:param str etag:
151+
(optional), ETag from a previous request to the same endpoint
152+
:returns:
153+
generator of comments
154+
:rtype:
155+
:class:`~github3.gists.comment.GistComment`
141156
"""
142157
url = self._build_url('comments', base_url=self._api)
143158
return self._iter(int(number), url, comment.GistComment, etag=etag)
@@ -154,13 +169,16 @@ def commits(self, number=-1, etag=None):
154169
155170
Added param ``etag``.
156171
157-
:param int number: (optional), number of commits to iterate over.
172+
:param int number:
173+
(optional), number of commits to iterate over.
158174
Default: -1 will iterate over all commits associated with this
159175
gist.
160-
:param str etag: (optional), ETag from a previous request to this
161-
endpoint.
162-
:returns: generator of the gist's history
163-
:rtype: :class:`~github3.gists.history.GistHistory`
176+
:param str etag:
177+
(optional), ETag from a previous request to this endpoint.
178+
:returns:
179+
generator of the gist's history
180+
:rtype:
181+
:class:`~github3.gists.history.GistHistory`
164182
"""
165183
url = self._build_url('commits', base_url=self._api)
166184
return self._iter(int(number), url, history.GistHistory)
@@ -172,12 +190,15 @@ def forks(self, number=-1, etag=None):
172190
173191
Added params ``number`` and ``etag``.
174192
175-
:param int number: (optional), number of forks to iterate over.
193+
:param int number:
194+
(optional), number of forks to iterate over.
176195
Default: -1 will iterate over all forks of this gist.
177-
:param str etag: (optional), ETag from a previous request to this
178-
endpoint.
179-
:returns: generator of gists
180-
:rtype: :class:`~github3.gists.gist.ShortGist`
196+
:param str etag:
197+
(optional), ETag from a previous request to this endpoint.
198+
:returns:
199+
generator of gists
200+
:rtype:
201+
:class:`~github3.gists.gist.ShortGist`
181202
"""
182203
url = self._build_url('forks', base_url=self._api)
183204
return self._iter(int(number), url, ShortGist, etag=etag)
@@ -186,8 +207,10 @@ def forks(self, number=-1, etag=None):
186207
def star(self):
187208
"""Star this gist.
188209
189-
:returns: True if successful, False otherwise
190-
:rtype: bool
210+
:returns:
211+
True if successful, False otherwise
212+
:rtype:
213+
bool
191214
"""
192215
url = self._build_url('star', base_url=self._api)
193216
return self._boolean(self._put(url), 204, 404)
@@ -196,8 +219,10 @@ def star(self):
196219
def unstar(self):
197220
"""Un-star this gist.
198221
199-
:returns: True if successful, False otherwise
200-
:rtype: bool
222+
:returns:
223+
True if successful, False otherwise
224+
:rtype:
225+
bool
201226
"""
202227
url = self._build_url('star', base_url=self._api)
203228
return self._boolean(self._delete(url), 204, 404)
@@ -324,12 +349,16 @@ def _repr(self):
324349
def to_gist(self):
325350
"""Retrieve the full Gist representation of this fork.
326351
327-
:returns: The Gist if retrieving it was successful or ``None``
328-
:rtype: :class:`~github3.gists.gist.Gist`
352+
:returns:
353+
The Gist if retrieving it was successful or ``None``
354+
:rtype:
355+
:class:`~github3.gists.gist.Gist`
329356
"""
330357
json = self._json(self._get(self.url), 200)
331358
return self._instance_or_null(Gist, json)
332359

360+
refresh = to_gist
361+
333362

334363
class Gist(_Gist):
335364
"""This object constitutes the full representation of a Gist.

0 commit comments

Comments
 (0)
0