Skip to main content

JSON-RPC request handler for Tornado.

Project description

🐍🌪️ tornado-jsonrpc2

Build Status codecov

A JSON-RPC request handler for Tornado.

It follows the specifications for JSON-RPC 2.0 and 1.0. Differences between the versions are described here in short form. By default both versions will be handled and answers are made according to the version detected for the request.

The aim is to have a spec-compliant handler that can be set up in a flexible way.


The current requirement for this is to have at least Python 3.6 and Tornado 5.


The usage of json.JSONDecodeError leads to the minimum version Python 3.6.

The usage of async / await means the lowest ever supported version will be Python 3.5. While currently not in focus having this running on Python 3.5 may become an option.


To allow for flexible configuration the JSONRPCHandler will have to be passed a parameter response_creator which takes an callable that the request in form will get passed to. The request is an instance of tornado_jsonrpc2.jsonrpc.JSONRPCRequest with the attributes method and params (and id and version should they be required).

The following example shows how this can be used to execute methods on a backend instance. By using functools we are able to create a function that only requires the request as an parameter.

import functools
import tornado.web

from tornado_jsonrpc2.handler import JSONRPCHandler
from tornado_jsonrpc2.exceptions import MethodNotFound

class MyBackend:
    def subtract(self, minuend, subtrahend):
        return minuend - subtrahend

async def create_response(request, backend):
        method = getattr(backend, request.method)
    except AttributeError:
        raise MethodNotFound("Method {!r} not found!".format(request.method))

        params = request.params
    except AttributeError:
        return method()

    if isinstance(params, list):
        return method(*params)
    elif isinstance(params, dict):
        return method(**params)

def make_app():
    simple_creator = functools.partial(create_response,

    return tornado.web.Application([
        (r"/jsonrpc", JSONRPCHandler, {"response_creator": simple_creator}),

if __name__ == "__main__":
    app = make_app()

You can access this example app on port 8888 with curl:

$ curl --insecure --data '{"jsonrpc": "2.0", "method": "subtract", "params": [5, 1], "id": 1}' http://localhost:8888/jsonrpc

{"jsonrpc": "2.0", "id": 1, "result": 4}

You can also name the parameters:

$ curl --insecure --data '{"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 5, "subtrahend": 1}, "id": 1}' http://localhost:8888/jsonrpc

{"jsonrpc": "2.0", "id": 1, "result": 4}

Handling specific JSON-RPC versions

By default the handler will process JSON-RPC 1.0 and 2.0. It is possible to configure the handler to only work with one specific version by adding a key version with the value "1.0" or "2.0" to the route spec.

The following example adds a specific route for each version:

def make_app():
    simple_creator = functools.partial(create_response,

    return tornado.web.Application([
        (r"/jsonrpc", JSONRPCHandler, {"response_creator": simple_creator}),
        (r"/jsonrpc1", JSONRPCHandler, {"version": "1.0",
                                        "response_creator": simple_creator}),
        (r"/jsonrpc2", JSONRPCHandler, {"version": "2.0",
                                        "response_creator": simple_creator}),

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tornado-jsonrpc2-0.5.tar.gz (6.0 kB view hashes)

Uploaded source

Built Distribution

tornado_jsonrpc2-0.5-py3-none-any.whl (18.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page