magical
/
bbj
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update some more docstrings

pull/4/head
Blake DeMarcy 2017-05-04 18:05:24 -05:00
parent b82aba8152
commit f4aec05c48
6 changed files with 108 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/docs/api_overview.md
View File

@ -100,8 +100,8 @@ See also [the Authorization page](authorization.md).
Takes the arguments `target_user` and `target_hash`, and
returns boolean true or false whether the hash is valid.
Returns boolean `true` or `false` of whether the hash given
is correct for the given user.
<br>
@ -189,35 +189,36 @@ on success. Returns a descriptive code 4 otherwise.
* __time__: int/float: epoch/unix time of the earliest point of interest
* __OPTIONAL: format__: string: the specifier for the desired formatting engine
Returns a special object representing all activity on the board since
the argument `time`, a unix/epoch timestamp.
Returns a special object representing all activity on the board since `time`.
```javascript
{
"threads": {
"thread_id": {
...thread object
// ...thread object
},
...more thread_id/object pairs
// ...more thread_id/object pairs
},
"messages": [...standard message object array sorted by date]
"messages": [
...standard message object array sorted by date
]
}
```
The message objects in "messages" are the same objects returned
The message objects in `messages` are the same objects returned
in threads normally. They each have a thread_id parameter, and
you can access metadata for these threads by the "threads" object
you can access metadata for these threads by the `threads` object
which is also provided.
The "messages" array is already sorted by submission time, newest
The `messages` array is already sorted by submission time, newest
first. The order in the threads object is undefined and you should
instead use their `last_mod` attribute if you intend to list them
out visually.
You may optionally provide a `format` argument: this is treated
the same way as the `thread_load` endpoint and you should refer
to its documentation for more info.
<br>
## set_post_raw
@ -291,16 +292,15 @@ value, the OP message will never recieve special formatting.
**Arguments:**
* __OPTIONAL: include_op__: boolean: Include a `messages` object with the original post
* __OPTIONAL: include_op__: boolean: Include a `messages` object containing the original post
Return an array with all the threads, ordered by most recent activity.
Requires no arguments.
Optionally, you may supply the argument `include_op`, which, when
non-nil, will include a "messages" key with the object, whose sole
content is the original message (post_id 0).
Return an array with all the server's threads. They are already sorted for
you; most recently modified threads are at the beginning of the array.
Unless you supply `include_op`, these threads have no `messages` parameter.
If you do, the `messages` parameter is an array with a single message object
for the original post.
<br>
@ -404,7 +404,10 @@ Requires the arguments `body` and `format`. Applies
_requires no arguments_
Returns an array with all registered user_ids, with the usermap
object populated by their full objects.
object populated by their full objects. This method is _NEVER_
neccesary when using other endpoints, as the usermap returned
on those requests already contains all the information you will
need. This endpoint is useful for statistic purposes only.
<br>
@ -416,7 +419,7 @@ object populated by their full objects.
_requires no arguments_
Requires no arguments. Returns your internal user object,
including your authorization hash.
including your `auth_hash`.
<br>
@ -441,8 +444,7 @@ of whether that user is an admin.
Retreive an external user object for the given `target_user`.
Can be a user_id or user_name.
Returns a user object for the given target.
<br>
@ -454,8 +456,8 @@ Can be a user_id or user_name.
Takes the argument `target_user` and returns true or false
whether they are in the system or not.
Returns boolean `true` or `false` of whether the given target is
registered on the server.
<br>

67
docs/site/api_overview/index.html
View File

@ -203,8 +203,8 @@ choice. See <a href="../errors/">the full error page</a> for details.</p>
<p><strong>target_hash</strong>: string: sha256 hash for the password to check</p>
</li>
</ul>
<p>Takes the arguments <code>target_user</code> and <code>target_hash</code>, and
returns boolean true or false whether the hash is valid.</p>
<p>Returns boolean <code>true</code> or <code>false</code> of whether the hash given
is correct for the given user.</p>
<p><br>
<br><br></p>
<h1 id="threads-messages">Threads &amp; Messages</h1>
@ -277,30 +277,35 @@ on success. Returns a descriptive code 4 otherwise.</p>
<h2 id="message_feed">message_feed</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>time</strong>: int/float: epoch/unix time of the earliest point of interest</li>
<li>
<p><strong>time</strong>: int/float: epoch/unix time of the earliest point of interest</p>
</li>
<li>
<p><strong>OPTIONAL: format</strong>: string: the specifier for the desired formatting engine</p>
</li>
</ul>
<p>Returns a special object representing all activity on the board since
the argument <code>time</code>, a unix/epoch timestamp.</p>
<p>{
"threads": {
"thread_id": {
...thread object
<p>Returns a special object representing all activity on the board since <code>time</code>.</p>
<pre><code class="javascript">{
&quot;threads&quot;: {
&quot;thread_id&quot;: {
// ...thread object
},
...more thread_id/object pairs
// ...more thread_id/object pairs
},
"messages": [...standard message object array sorted by date]
}</p>
<p>The message objects in "messages" are the same objects returned
&quot;messages&quot;: [
...standard message object array sorted by date
]
}
</code></pre>
<p>The message objects in <code>messages</code> are the same objects returned
in threads normally. They each have a thread_id parameter, and
you can access metadata for these threads by the "threads" object
you can access metadata for these threads by the <code>threads</code> object
which is also provided.</p>
<p>The "messages" array is already sorted by submission time, newest
<p>The <code>messages</code> array is already sorted by submission time, newest
first. The order in the threads object is undefined and you should
instead use their <code>last_mod</code> attribute if you intend to list them
out visually.</p>
<p>You may optionally provide a <code>format</code> argument: this is treated
the same way as the <code>thread_load</code> endpoint and you should refer
to its documentation for more info.</p>
<p><br></p>
<h2 id="set_post_raw">set_post_raw</h2>
<p><strong>Arguments:</strong></p>
@ -364,13 +369,13 @@ value, the OP message will never recieve special formatting.</p>
<h2 id="thread_index">thread_index</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>OPTIONAL: include_op</strong>: boolean: Include a <code>messages</code> object with the original post</li>
<li><strong>OPTIONAL: include_op</strong>: boolean: Include a <code>messages</code> object containing the original post</li>
</ul>
<p>Return an array with all the threads, ordered by most recent activity.
Requires no arguments.</p>
<p>Optionally, you may supply the argument <code>include_op</code>, which, when
non-nil, will include a "messages" key with the object, whose sole
content is the original message (post_id 0).</p>
<p>Return an array with all the server's threads. They are already sorted for
you; most recently modified threads are at the beginning of the array.
Unless you supply <code>include_op</code>, these threads have no <code>messages</code> parameter.
If you do, the <code>messages</code> parameter is an array with a single message object
for the original post.</p>
<p><br></p>
<h2 id="thread_load">thread_load</h2>
<p><strong>Arguments:</strong></p>
@ -459,7 +464,10 @@ provided value is safe to use.</p>
<h2 id="user_map">user_map</h2>
<p><em>requires no arguments</em></p>
<p>Returns an array with all registered user_ids, with the usermap
object populated by their full objects.</p>
object populated by their full objects. This method is <em>NEVER</em>
neccesary when using other endpoints, as the usermap returned
on those requests already contains all the information you will
need. This endpoint is useful for statistic purposes only.</p>
<p><br>
<br><br></p>
<h1 id="users">Users</h1>
@ -467,7 +475,7 @@ object populated by their full objects.</p>
<h2 id="get_me">get_me</h2>
<p><em>requires no arguments</em></p>
<p>Requires no arguments. Returns your internal user object,
including your authorization hash.</p>
including your <code>auth_hash</code>.</p>
<p><br></p>
<h2 id="is_admin">is_admin</h2>
<p><strong>Arguments:</strong></p>
@ -482,16 +490,15 @@ of whether that user is an admin.</p>
<ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul>
<p>Retreive an external user object for the given <code>target_user</code>.
Can be a user_id or user_name.</p>
<p>Returns a user object for the given target.</p>
<p><br></p>
<h2 id="user_is_registered">user_is_registered</h2>
<p><strong>Arguments:</strong></p>
<ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul>
<p>Takes the argument <code>target_user</code> and returns true or false
whether they are in the system or not.</p>
<p>Returns boolean <code>true</code> or <code>false</code> of whether the given target is
registered on the server.</p>
<p><br></p>
<h2 id="user_register">user_register</h2>
<p><strong>Arguments:</strong></p>

2
docs/site/index.html
View File

@ -149,5 +149,5 @@ It is fully documented on this site.</p></div>
<!--
MkDocs version : 0.16.3
Build Date UTC : 2017-05-04 03:22:04
Build Date UTC : 2017-05-04 23:05:17
-->

16
docs/site/mkdocs/search_index.json
View File

File diff suppressed because one or more lines are too long

8
docs/site/sitemap.xml
View File

@ -4,7 +4,7 @@
<url>
<loc>/</loc>
<lastmod>2017-05-03</lastmod>
<lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq>
</url>
@ -13,19 +13,19 @@
<url>
<loc>/api_overview/</loc>
<lastmod>2017-05-03</lastmod>
<lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/errors/</loc>
<lastmod>2017-05-03</lastmod>
<lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>/validation/</loc>
<lastmod>2017-05-03</lastmod>
<lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq>
</url>

56
server.py
View File

@ -233,7 +233,7 @@ class API(object):
def get_me(self, args, database, user, **kwargs):
"""
Requires no arguments. Returns your internal user object,
including your authorization hash.
including your `auth_hash`.
"""
return user
get_me.doctype = "Users"
@ -243,7 +243,10 @@ class API(object):
def user_map(self, args, database, user, **kwargs):
"""
Returns an array with all registered user_ids, with the usermap
object populated by their full objects.
object populated by their full objects. This method is _NEVER_
neccesary when using other endpoints, as the usermap returned
on those requests already contains all the information you will
need. This endpoint is useful for statistic purposes only.
"""
users = {
user[0] for user in database.execute("SELECT user_id FROM users")
@ -263,8 +266,7 @@ class API(object):
@api_method
def user_get(self, args, database, user, **kwargs):
"""
Retreive an external user object for the given `target_user`.
Can be a user_id or user_name.
Returns a user object for the given target.
"""
validate(args, ["target_user"])
return db.user_resolve(
@ -277,8 +279,8 @@ class API(object):
@api_method
def user_is_registered(self, args, database, user, **kwargs):
"""
Takes the argument `target_user` and returns true or false
whether they are in the system or not.
Returns boolean `true` or `false` of whether the given target is
registered on the server.
"""
validate(args, ["target_user"])
return bool(db.user_resolve(database, args["target_user"]))
@ -290,8 +292,8 @@ class API(object):
@api_method
def check_auth(self, args, database, user, **kwargs):
"""
Takes the arguments `target_user` and `target_hash`, and
returns boolean true or false whether the hash is valid.
Returns boolean `true` or `false` of whether the hash given
is correct for the given user.
"""
validate(args, ["target_user", "target_hash"])
user = db.user_resolve(
@ -306,51 +308,50 @@ class API(object):
@api_method
def thread_index(self, args, database, user, **kwargs):
"""
Return an array with all the threads, ordered by most recent activity.
Requires no arguments.
Optionally, you may supply the argument `include_op`, which, when
non-nil, will include a "messages" key with the object, whose sole
content is the original message (post_id 0).
Return an array with all the server's threads. They are already sorted for
you; most recently modified threads are at the beginning of the array.
Unless you supply `include_op`, these threads have no `messages` parameter.
If you do, the `messages` parameter is an array with a single message object
for the original post.
"""
threads = db.thread_index(database, include_op=args.get("include_op"))
cherrypy.thread_data.usermap = create_usermap(database, threads, True)
return threads
thread_index.doctype = "Threads & Messages"
thread_index.arglist = (
("OPTIONAL: include_op", "boolean: Include a `messages` object with the original post"),
("OPTIONAL: include_op", "boolean: Include a `messages` object containing the original post"),
)
@api_method
def message_feed(self, args, database, user, **kwargs):
"""
Returns a special object representing all activity on the board since
the argument `time`, a unix/epoch timestamp.
Returns a special object representing all activity on the board since `time`.
```javascript
{
"threads": {
"thread_id": {
...thread object
// ...thread object
},
...more thread_id/object pairs
// ...more thread_id/object pairs
},
"messages": [...standard message object array sorted by date]
"messages": [
...standard message object array sorted by date
]
}
```
The message objects in "messages" are the same objects returned
The message objects in `messages` are the same objects returned
in threads normally. They each have a thread_id parameter, and
you can access metadata for these threads by the "threads" object
you can access metadata for these threads by the `threads` object
which is also provided.
The "messages" array is already sorted by submission time, newest
The `messages` array is already sorted by submission time, newest
first. The order in the threads object is undefined and you should
instead use their `last_mod` attribute if you intend to list them
out visually.
You may optionally provide a `format` argument: this is treated
the same way as the `thread_load` endpoint and you should refer
to its documentation for more info.
"""
# XXX: Update with new formatting documentation for arg `format`
validate(args, ["time"])
feed = db.message_feed(database, args["time"])
@ -363,6 +364,7 @@ class API(object):
message_feed.doctype = "Threads & Messages"
message_feed.arglist = (
("time", "int/float: epoch/unix time of the earliest point of interest"),
("OPTIONAL: format", "string: the specifier for the desired formatting engine")
)
@api_method