tornado_json Package¶
api_doc_gen
Module¶
-
tornado_json.api_doc_gen.
api_doc_gen
(routes)[source]¶ Get and write API documentation for
routes
to file
-
tornado_json.api_doc_gen.
get_api_docs
(routes)[source]¶ Generates GitHub Markdown formatted API documentation using provided schemas in RequestHandler methods and their docstrings.
Parameters: routes ([(url, RequestHandler), ..]) – List of routes (this is ideally all possible routes of the app) Return type: str Returns: generated GFM-formatted documentation
application
Module¶
-
class
tornado_json.application.
Application
(routes, settings, db_conn=None, generate_docs=False)[source]¶ Bases:
tornado.web.Application
Entry-point for the app
- Generate API documentation using provided routes
- Initialize the application
Parameters: - routes ([(url, RequestHandler), ..]) – List of routes for the app
- settings (dict) – Settings for the app
- db_conn – Database connection
- generate_docs (bool) – If set, will generate API documentation for
provided
routes
. Documentation is written as API_Documentation.md in the cwd.
jsend
Module¶
-
class
tornado_json.jsend.
JSendMixin
[source]¶ Bases:
object
http://labs.omniti.com/labs/jsend
JSend is a specification that lays down some rules for how JSON responses from web servers should be formatted.
JSend focuses on application-level (as opposed to protocol- or transport-level) messaging which makes it ideal for use in REST-style applications and APIs.
-
error
(message, data=None, code=None)[source]¶ An error occurred in processing the request, i.e. an exception was thrown.
Parameters: - data (A JSON-serializable object) – A generic container for any other information about the error, i.e. the conditions that caused the error, stack traces, etc.
- message (A JSON-serializable object) – A meaningful, end-user-readable (or at the least log-worthy) message, explaining what went wrong
- code (int) – A numeric code corresponding to the error, if applicable
-
fail
(data)[source]¶ There was a problem with the data submitted, or some pre-condition of the API call wasn’t satisfied.
Parameters: data (A JSON-serializable object) – Provides the wrapper for the details of why the request failed. If the reasons for failure correspond to POST values, the response object’s keys SHOULD correspond to those POST values.
-
success
(data)[source]¶ When an API call is successful, the JSend object is used as a simple envelope for the results, using the data key.
Parameters: data (A JSON-serializable object) – Acts as the wrapper for any data returned by the API call. If the call returns no data, data should be set to null.
-
requesthandlers
Module¶
-
class
tornado_json.requesthandlers.
APIHandler
(application, request, **kwargs)[source]¶ Bases:
tornado_json.requesthandlers.BaseHandler
,tornado_json.jsend.JSendMixin
RequestHandler for API calls
- Sets header as
application/json
- Provides custom write_error that writes error back as JSON rather than as the standard HTML template
- Sets header as
-
class
tornado_json.requesthandlers.
BaseHandler
(application, request, **kwargs)[source]¶ Bases:
tornado.web.RequestHandler
BaseHandler for all other RequestHandlers
-
db_conn
¶ Returns database connection abstraction
If no database connection is available, raises an AttributeError
-
-
class
tornado_json.requesthandlers.
ViewHandler
(application, request, **kwargs)[source]¶ Bases:
tornado_json.requesthandlers.BaseHandler
Handler for views
routes
Module¶
-
tornado_json.routes.
gen_submodule_names
(package)[source]¶ Walk package and yield names of all submodules
Parameters: package (package) – The package to get submodule names of Returns: Iterator that yields names of all submodules of package
Return type: Iterator that yields str
-
tornado_json.routes.
get_module_routes
(module_name, custom_routes=None, exclusions=None, arg_pattern='(?P<{}>[a-zA-Z0-9_\\-]+)')[source]¶ Create and return routes for module_name
Routes are (url, RequestHandler) tuples
Returns: list of routes for
module_name
with respect toexclusions
andcustom_routes
. Returned routes are with URLs formatted such that they are forward-slash-separated by module/class level and end with the lowercase name of the RequestHandler (it will also remove ‘handler’ from the end of the name of the handler). For example, a requesthandler with the namehelloworld.api.HelloWorldHandler
would be assigned the url/api/helloworld
. Additionally, if a method has extra arguments aside fromself
in its signature, routes with URL patterns will be generated to matchr"(?P<{}>[a-zA-Z0-9_\-]+)".format(argname)
for each argument. The aforementioned regex will match ONLY values with alphanumeric, hyphen and underscore characters. You can provide your own pattern by setting aarg_pattern
param.Return type: [(url, RequestHandler), .. ]
Parameters: - module_name (str) – Name of the module to get routes for
- custom_routes ([(str, RequestHandler), .. ]) – List of routes that have custom URLs and therefore should be automagically generated
- exclusions ([str, str, ..]) – List of RequestHandler names that routes should not be generated for
- arg_pattern (str) – Default pattern for extra arguments of any method
-
tornado_json.routes.
get_routes
(package)[source]¶ This will walk
package
and generates routes from any and allAPIHandler
andViewHandler
subclasses it finds. If you need to customize or remove any routes, you can do so to the list of returned routes that this generates.Parameters: package (package) – The package containing RequestHandlers to generate routes from Returns: List of routes for all submodules of package
Return type: [(url, RequestHandler), .. ]