This page contains only API docs. For more info, visit jsonrpyc on GitHub.

Minimal python RPC implementation in a single file based on the JSON-RPC 2.0 specs from http://www.jsonrpc.org/specification.


class jsonrpyc.RPC(target=None, stdin=None, stdout=None, **kwargs)

The main class of jsonrpyc. Instances of this class basically wrap an input stream stdin and an output stream stdout in order to communicate with other services. A service is not even forced to be written in Python as long as it strictly implements the JSON-RPC 2.0 specs. RPC instances may wrap a target object. Incomming requests will be routed to methods of this object whose result might be sent back as a response. Example implementation:


import jsonrpyc

class MyTarget(object):

    def greet(self, name):
        return "Hi, %s!" % name



import jsonrpyc
from subprocess import Popen, PIPE

p = Popen(["python", "server.py"], stdin=PIPE, stdout=PIPE)
rpc = jsonrpyc.RPC(stdout=p.stdin, stdin=p.stdout)

# non-blocking remote procedure call with callback, js-like signature
def cb(err, res=None):
    if err:
        throw err
    print("callback got: " + res)

rpc("greet", args=("John",), callback=cb)

# cb is called asynchronously which prints
# => "callback got: Hi, John!"

# blocking remote procedure call with 0.1s polling
print(rpc("greet", args=("John",), block=0.1))
# => "Hi, John!"

The wrapped target object. Might be None when no object is wrapped, e.g. for the client RPC instance.


The input stream, re-opened with "rb".


The output stream, re-opened with "wb".


The Watchdog instance that watches stdin.

call(method, args=(), kwargs=None, callback=None, block=0)

Performs an actual remote procedure call by writing a request representation (a string) to the output stream. The remote RPC instance uses method to route to the actual method to call with args and kwargs. When callback is set, it will be called with the result of the remote call. When block is larger than 0, the calling thread is blocked until the result is received. In this case, block will be the poll interval. This mechanism emulates synchronuous return value behavior. When both, callback is None and block is 0 or less, the request is considered a notification and the remote RPC instance will not send a response.


class jsonrpyc.Spec

This class wraps methods that create JSON-RPC 2.0 compatible string representations of requests, responses, and errors. All methods are class members, so you might never want to create an instance of this class, but rahter use the methods directly:

Spec.request("my_method", 18)
# => '{"jsonrpc": "2.0", "method": "my_method", "id": 18}'

Spec.response(18, "some_result")
# => '{"jsonrpc": "2.0", "id": 18, "result": "some_result"}'

Spec.error(18, -32603)
# => '{"jsonrpc": "2.0", "id": 18, "error": {"code": -32603, "message": "Internal error"}}'
classmethod check_code(code)

Value check for code entries. Raises a TypeError when code is not an interger, or a KeyError when there is no RPCError derivative registered for that code.

classmethod check_id(id, allow_empty=False)

Value check for id entries. When allow_empty is True, id is allowed to be None. Raises a TypeError when id is not an interger and no string.

classmethod check_method(method)

Value check for method entries. Raises a TypeError when method is not a string.

classmethod error(id, code, data=None)

Creates the string representation of an error that occured while processing a request with id. code must lead to a registered RPCError. data might contain additional, detailed error information.

classmethod request(method, id=None, params=None)

Creates the string representation of a request that calls method with optional params. When id is None, the request is considered a notification.

classmethod response(id, result)

Creates the string representation of a respons that was triggered by a request with id. result is required.


class jsonrpyc.Watchdog(rpc, name='watchdog', interval=0.1, daemon=False, start=True)

This class represents a thread that watches the input stream for incomming content.


The RPC instance.


The thread’s name.


The polling interval of the run loop.


The thread’s daemon flag.


Starts with thread’s activity.


Stops with thread’s activity.


exception jsonrpyc.RPCError(data=None)

Base class for RPC errors.


The message of this error, i.e., "<title> (<code>)[, data: <data>]".


Additional data of this error. Setting the data attribute will also change the message attribute.


Decorator that registers a new RPC error derived from RPCError. The purpose of error registration is to have a mapping of error codes/code ranges to error classes for faster lookups during error creation.

class MyCustomRPCError(RPCError):
    code = ...
    title = "My custom error"

Returns the RPC error class that was previously registered to code. None is returned when no class could be found.

RPC errors

exception jsonrpyc.RPCParseError(data=None)
code = -32700
title = 'Parse error'
exception jsonrpyc.RPCInvalidRequest(data=None)
code = -32600
title = 'Invalid Request'
exception jsonrpyc.RPCMethodNotFound(data=None)
code = -32601
title = 'Method not found'
exception jsonrpyc.RPCInvalidParams(data=None)
code = -32602
title = 'Invalid params'
exception jsonrpyc.RPCInternalError(data=None)
code = -32603
title = 'Internal error'
exception jsonrpyc.RPCServerError(data=None)
code = (-32099, -32000)
title = 'Server error'