jsonrpcserver Guide

This library allows you to act on remote procedure calls.


First build a list of methods that can be called remotely.

Use the methods.add decorator to register a method to the list:

from jsonrpcserver import methods

def ping():
    return 'pong'

Add as many methods as needed, then serve the methods:

>>> methods.serve_forever()
 * Listening on port 5000

The built-in serve_forever() method is a cheap-and-nasty way of taking requests; ultimately you should use a more sophisticated server library (see examples in various frameworks).

For those, there’s a dispatch() method.


The dispatch function processes a JSON-RPC request and calls the appropriate method:

>>> response = methods.dispatch('{"jsonrpc": "2.0", "method": "ping", "id": 1}')
--> {"jsonrpc": "2.0", "method": "ping", "id": 1}
<-- {"jsonrpc": "2.0", "result": "pong", "id": 1}

The return value is a Response object.

>>> response
{'jsonrpc': '2.0', 'result': 'foo', 'id': 1}

Use str() to get a JSON-encoded string:

>>> str(response)
'{"jsonrpc": "2.0", "result": "foo", "id": 1}'

There’s also an HTTP status code if needed:

>>> response.http_status


If you need to pass some extra data to the methods, such as configuration settings, or the request object from the server framework, there’s a context param:

methods.dispatch(request, context={'feature_enabled': True})

The methods should receive this value (it must be named context):

def ping(context):


The following other options can be passed to dispatch


Attempts to clean up requests before processing, by changing the method and parameter names to snake case. Default is False.


If True, more information is included in error responses, such as an exception message. Default is False.


Notifications are not responded to in almost all cases, however if you prefer, notifications can receive error responses. Default is False.


Allows you to disable the validation of requests against the JSON-RPC schema. Default is True.


Methods can take arguments, positional or named (but not both, this is a limitation of JSON-RPC).

If an argument is unsatisfactory, raise InvalidParams:

from jsonrpcserver.exceptions import InvalidParams

def get_customer(**kwargs):
    if 'name' not in kwargs:
        raise InvalidParams('Name is required')

The dispatcher will catch the exception and give the appropriate response:

>>> methods.dispatch({'jsonrpc': '2.0', 'method': 'get', 'params': {}, 'id': 1})
{'jsonrpc': '2.0', 'error': {'code': -32602, 'message': 'Invalid params'}, 'id': 1}

To include the “Name is required” message in the response, pass debug=True to dispatch.


Asyncio is supported Python 3.5+, allowing requests to be dispatched to coroutines.

Import methods from jsonrpcserver.aio:

from jsonrpcserver.aio import methods

async def ping():
    return await some_long_running_task()

Then await the dispatch:

response = await methods.dispatch(request)

Disable logging

To disable the log entries:

import logging


See the list of exceptions raised by jsonrpcserver here.