From fb013773c3ef4f6ee2b2e1c0dd516c563c0fb6ba Mon Sep 17 00:00:00 2001 From: Blake DeMarcy Date: Sun, 2 Apr 2017 23:51:44 -0500 Subject: [PATCH] documentation changes --- src/exceptions.py | 11 +++++++++++ src/formatting.py | 5 +++++ src/schema.py | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/src/exceptions.py b/src/exceptions.py index a34e02c..c9e449f 100644 --- a/src/exceptions.py +++ b/src/exceptions.py @@ -1,3 +1,14 @@ +""" +These exceptions create schema objects to send back to the client. +The new error codes have not been fully documented since ditching +the prototype but there are less of them and the handling is much +more robust and less verbose in the source code. + +At any point of the API's codepath, these may be raised and will be +captured by the request handler. Their schema is then sent back to +the client. +""" + from src.schema import error diff --git a/src/formatting.py b/src/formatting.py index d327a24..abf13f5 100644 --- a/src/formatting.py +++ b/src/formatting.py @@ -1,3 +1,8 @@ +""" +This module is not complete and none of its functions are currently +used elsewhere. Subject to major refactoring. +""" + from markdown import markdown from html import escape import re diff --git a/src/schema.py b/src/schema.py index 0851ffa..85de132 100644 --- a/src/schema.py +++ b/src/schema.py @@ -1,3 +1,40 @@ +""" +This module provides functions that return API objects in +a clearly defined, consistent manner. Schmea representing +data types mirror the column order used by the sqlite +database. An sql object can be unpacked by using star +expansion as an argument, such as thread(*sql_thread_obj) + +Each response has a base layout as follows: + +{ + "error": false, // boolean false or error object + "data": null, // null or the requested data from endpoint. + "usermap": {} // a potentially empty object mapping user_ids to their objects +} + +If "error" is true, it looks like this: + +{ + "error": { + "code": an integer from 0 to 5, + "description": a string describing the error in detail. +} + "data": null // ALWAYS null if error is not false + "usermap": {} // ALWAYS empty if error is not false +} + +"data" can be anything. It could be a boolean, it could be a string, +object, anything. The return value for an endpoint is described clearly +in its documentation. However, no endpoint will EVER return null. If +"data" is null, then "error" is filled. + +"usermap" is filled with objects whenever users are present in +"data". its keys are all the user_ids that occur in the "data" +object. Use this to get information about users, as follows: +usermap[id]["user_name"] +""" + def base(): return { "error": False,