tornado_json Package

api_doc_gen Module

tornado_json.api_doc_gen.api_doc_gen(routes)

Get and write API documentation for routes to file

tornado_json.api_doc_gen.get_api_docs(routes)

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)

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

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)

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)

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)

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)

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

initialize()

• Set Content-type for JSON

write_error(status_code, **kwargs)

Override of RequestHandler.write_error

Calls error() or fail() from JSendMixin depending on which exception was raised with provided reason and status code.

Parameters:status_code (int) – HTTP status code

class tornado_json.requesthandlers.BaseHandler(application, request, **kwargs)

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)

Bases: tornado_json.requesthandlers.BaseHandler

Handler for views

initialize()

• Set Content-type for HTML

routes Module

tornado_json.routes.gen_submodule_names(package)

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_\\-]+)')

Create and return routes for module_name

Routes are (url, RequestHandler) tuples

Returns:

list of routes for module_name with respect to exclusions and custom_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 name helloworld.api.HelloWorldHandler would be assigned the url /api/helloworld. Additionally, if a method has extra arguments aside from self in its signature, routes with URL patterns will be generated to match r"(?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 a arg_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)

This will walk package and generates routes from any and all APIHandler and ViewHandler 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), .. ]