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` of whether the hash given
returns boolean true or false whether the hash is valid. is correct for the given user.
<br> <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 * __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": { "threads": {
"thread_id": { "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 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. 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 first. The order in the threads object is undefined and you should
instead use their `last_mod` attribute if you intend to list them instead use their `last_mod` attribute if you intend to list them
out visually. 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> <br>
## set_post_raw ## set_post_raw
@ -291,16 +292,15 @@ value, the OP message will never recieve special formatting.
**Arguments:** **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. Return an array with all the server's threads. They are already sorted for
Requires no arguments. you; most recently modified threads are at the beginning of the array.
Unless you supply `include_op`, these threads have no `messages` parameter.
Optionally, you may supply the argument `include_op`, which, when If you do, the `messages` parameter is an array with a single message object
non-nil, will include a "messages" key with the object, whose sole for the original post.
content is the original message (post_id 0).
<br> <br>
@ -404,7 +404,10 @@ Requires the arguments `body` and `format`. Applies
_requires no arguments_ _requires no arguments_
Returns an array with all registered user_ids, with the usermap 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> <br>
@ -416,7 +419,7 @@ object populated by their full objects.
_requires no arguments_ _requires no arguments_
Requires no arguments. Returns your internal user object, Requires no arguments. Returns your internal user object,
including your authorization hash. including your `auth_hash`.
<br> <br>
@ -441,8 +444,7 @@ of whether that user is an admin.
Retreive an external user object for the given `target_user`. Returns a user object for the given target.
Can be a user_id or user_name.
<br> <br>
@ -454,8 +456,8 @@ Can be a user_id or user_name.
Takes the argument `target_user` and returns true or false Returns boolean `true` or `false` of whether the given target is
whether they are in the system or not. registered on the server.
<br> <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> <p><strong>target_hash</strong>: string: sha256 hash for the password to check</p>
</li> </li>
</ul> </ul>
<p>Takes the arguments <code>target_user</code> and <code>target_hash</code>, and <p>Returns boolean <code>true</code> or <code>false</code> of whether the hash given
returns boolean true or false whether the hash is valid.</p> is correct for the given user.</p>
<p><br> <p><br>
<br><br></p> <br><br></p>
<h1 id="threads-messages">Threads &amp; Messages</h1> <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> <h2 id="message_feed">message_feed</h2>
<p><strong>Arguments:</strong></p> <p><strong>Arguments:</strong></p>
<ul> <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> </ul>
<p>Returns a special object representing all activity on the board since <p>Returns a special object representing all activity on the board since <code>time</code>.</p>
the argument <code>time</code>, a unix/epoch timestamp.</p> <pre><code class="javascript">{
<p>{ &quot;threads&quot;: {
"threads": { &quot;thread_id&quot;: {
"thread_id": { // ...thread object
...thread object
}, },
...more thread_id/object pairs // ...more thread_id/object pairs
}, },
"messages": [...standard message object array sorted by date] &quot;messages&quot;: [
}</p> ...standard message object array sorted by date
<p>The message objects in "messages" are the same objects returned ]
}
</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 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> 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 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 instead use their <code>last_mod</code> attribute if you intend to list them
out visually.</p> 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> <p><br></p>
<h2 id="set_post_raw">set_post_raw</h2> <h2 id="set_post_raw">set_post_raw</h2>
<p><strong>Arguments:</strong></p> <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> <h2 id="thread_index">thread_index</h2>
<p><strong>Arguments:</strong></p> <p><strong>Arguments:</strong></p>
<ul> <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> </ul>
<p>Return an array with all the threads, ordered by most recent activity. <p>Return an array with all the server's threads. They are already sorted for
Requires no arguments.</p> you; most recently modified threads are at the beginning of the array.
<p>Optionally, you may supply the argument <code>include_op</code>, which, when Unless you supply <code>include_op</code>, these threads have no <code>messages</code> parameter.
non-nil, will include a "messages" key with the object, whose sole If you do, the <code>messages</code> parameter is an array with a single message object
content is the original message (post_id 0).</p> for the original post.</p>
<p><br></p> <p><br></p>
<h2 id="thread_load">thread_load</h2> <h2 id="thread_load">thread_load</h2>
<p><strong>Arguments:</strong></p> <p><strong>Arguments:</strong></p>
@ -459,7 +464,10 @@ provided value is safe to use.</p>
<h2 id="user_map">user_map</h2> <h2 id="user_map">user_map</h2>
<p><em>requires no arguments</em></p> <p><em>requires no arguments</em></p>
<p>Returns an array with all registered user_ids, with the usermap <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> <p><br>
<br><br></p> <br><br></p>
<h1 id="users">Users</h1> <h1 id="users">Users</h1>
@ -467,7 +475,7 @@ object populated by their full objects.</p>
<h2 id="get_me">get_me</h2> <h2 id="get_me">get_me</h2>
<p><em>requires no arguments</em></p> <p><em>requires no arguments</em></p>
<p>Requires no arguments. Returns your internal user object, <p>Requires no arguments. Returns your internal user object,
including your authorization hash.</p> including your <code>auth_hash</code>.</p>
<p><br></p> <p><br></p>
<h2 id="is_admin">is_admin</h2> <h2 id="is_admin">is_admin</h2>
<p><strong>Arguments:</strong></p> <p><strong>Arguments:</strong></p>
@ -482,16 +490,15 @@ of whether that user is an admin.</p>
<ul> <ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li> <li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul> </ul>
<p>Retreive an external user object for the given <code>target_user</code>. <p>Returns a user object for the given target.</p>
Can be a user_id or user_name.</p>
<p><br></p> <p><br></p>
<h2 id="user_is_registered">user_is_registered</h2> <h2 id="user_is_registered">user_is_registered</h2>
<p><strong>Arguments:</strong></p> <p><strong>Arguments:</strong></p>
<ul> <ul>
<li><strong>target_user</strong>: string: either a user_name or a user_id</li> <li><strong>target_user</strong>: string: either a user_name or a user_id</li>
</ul> </ul>
<p>Takes the argument <code>target_user</code> and returns true or false <p>Returns boolean <code>true</code> or <code>false</code> of whether the given target is
whether they are in the system or not.</p> registered on the server.</p>
<p><br></p> <p><br></p>
<h2 id="user_register">user_register</h2> <h2 id="user_register">user_register</h2>
<p><strong>Arguments:</strong></p> <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 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> <url>
<loc>/</loc> <loc>/</loc>
<lastmod>2017-05-03</lastmod> <lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq> <changefreq>daily</changefreq>
</url> </url>
@ -13,19 +13,19 @@
<url> <url>
<loc>/api_overview/</loc> <loc>/api_overview/</loc>
<lastmod>2017-05-03</lastmod> <lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq> <changefreq>daily</changefreq>
</url> </url>
<url> <url>
<loc>/errors/</loc> <loc>/errors/</loc>
<lastmod>2017-05-03</lastmod> <lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq> <changefreq>daily</changefreq>
</url> </url>
<url> <url>
<loc>/validation/</loc> <loc>/validation/</loc>
<lastmod>2017-05-03</lastmod> <lastmod>2017-05-04</lastmod>
<changefreq>daily</changefreq> <changefreq>daily</changefreq>
</url> </url>

56
server.py
View File

@ -233,7 +233,7 @@ class API(object):
def get_me(self, args, database, user, **kwargs): def get_me(self, args, database, user, **kwargs):
""" """
Requires no arguments. Returns your internal user object, Requires no arguments. Returns your internal user object,
including your authorization hash. including your `auth_hash`.
""" """
return user return user
get_me.doctype = "Users" get_me.doctype = "Users"
@ -243,7 +243,10 @@ class API(object):
def user_map(self, args, database, user, **kwargs): def user_map(self, args, database, user, **kwargs):
""" """
Returns an array with all registered user_ids, with the usermap 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 = { users = {
user[0] for user in database.execute("SELECT user_id FROM users") user[0] for user in database.execute("SELECT user_id FROM users")
@ -263,8 +266,7 @@ class API(object):
@api_method @api_method
def user_get(self, args, database, user, **kwargs): def user_get(self, args, database, user, **kwargs):
""" """
Retreive an external user object for the given `target_user`. Returns a user object for the given target.
Can be a user_id or user_name.
""" """
validate(args, ["target_user"]) validate(args, ["target_user"])
return db.user_resolve( return db.user_resolve(
@ -277,8 +279,8 @@ class API(object):
@api_method @api_method
def user_is_registered(self, args, database, user, **kwargs): def user_is_registered(self, args, database, user, **kwargs):
""" """
Takes the argument `target_user` and returns true or false Returns boolean `true` or `false` of whether the given target is
whether they are in the system or not. registered on the server.
""" """
validate(args, ["target_user"]) validate(args, ["target_user"])
return bool(db.user_resolve(database, args["target_user"])) return bool(db.user_resolve(database, args["target_user"]))
@ -290,8 +292,8 @@ class API(object):
@api_method @api_method
def check_auth(self, args, database, user, **kwargs): def check_auth(self, args, database, user, **kwargs):
""" """
Takes the arguments `target_user` and `target_hash`, and Returns boolean `true` or `false` of whether the hash given
returns boolean true or false whether the hash is valid. is correct for the given user.
""" """
validate(args, ["target_user", "target_hash"]) validate(args, ["target_user", "target_hash"])
user = db.user_resolve( user = db.user_resolve(
@ -306,51 +308,50 @@ class API(object):
@api_method @api_method
def thread_index(self, args, database, user, **kwargs): def thread_index(self, args, database, user, **kwargs):
""" """
Return an array with all the threads, ordered by most recent activity. Return an array with all the server's threads. They are already sorted for
Requires no arguments. you; most recently modified threads are at the beginning of the array.
Unless you supply `include_op`, these threads have no `messages` parameter.
Optionally, you may supply the argument `include_op`, which, when If you do, the `messages` parameter is an array with a single message object
non-nil, will include a "messages" key with the object, whose sole for the original post.
content is the original message (post_id 0).
""" """
threads = db.thread_index(database, include_op=args.get("include_op")) threads = db.thread_index(database, include_op=args.get("include_op"))
cherrypy.thread_data.usermap = create_usermap(database, threads, True) cherrypy.thread_data.usermap = create_usermap(database, threads, True)
return threads return threads
thread_index.doctype = "Threads & Messages" thread_index.doctype = "Threads & Messages"
thread_index.arglist = ( 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 @api_method
def message_feed(self, args, database, user, **kwargs): def message_feed(self, args, database, user, **kwargs):
""" """
Returns a special object representing all activity on the board since Returns a special object representing all activity on the board since `time`.
the argument `time`, a unix/epoch timestamp.
```javascript
{ {
"threads": { "threads": {
"thread_id": { "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 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. 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 first. The order in the threads object is undefined and you should
instead use their `last_mod` attribute if you intend to list them instead use their `last_mod` attribute if you intend to list them
out visually. 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"]) validate(args, ["time"])
feed = db.message_feed(database, args["time"]) feed = db.message_feed(database, args["time"])
@ -363,6 +364,7 @@ class API(object):
message_feed.doctype = "Threads & Messages" message_feed.doctype = "Threads & Messages"
message_feed.arglist = ( message_feed.arglist = (
("time", "int/float: epoch/unix time of the earliest point of interest"), ("time", "int/float: epoch/unix time of the earliest point of interest"),
("OPTIONAL: format", "string: the specifier for the desired formatting engine")
) )
@api_method @api_method