JSON-RPC

Asynchronous WSGI Remote Procedure Calls middleware. It implements a JSON-RPC server and client.

RPC server

To create a server first you create your rpc handler and (optional) subhandlers:

from pulsar.apps import rpc, wsgi

class Root(rpc.PulsarServerCommands):
    pass
    
class Calculator(rpc.JSONRPC):
    
    def rpc_add(self, request, a, b):
        return float(a) + float(b)
    
    def rpc_subtract(self, request, a, b):
        return float(a) - float(b)
    
    def rpc_multiply(self, request, a, b):
        return float(a) * float(b)
    
    def rpc_divide(self, request, a, b):
        return float(a) / float(b)

Then you create the WSGI middleware:

def server():
    root = Root().putSubHandler('calc',Calculator())
    return wsgi.WSGIServer(callable=rpc.RpcMiddleware(root))

if __name__ == '__main__':
    server().start()

API

RpcHandler

RpcMiddleware

class pulsar.apps.rpc.RpcMiddleware(handler, path=None)

A WSGI middleware for serving an RpcHandler.

handler

The RpcHandler to serve.

path

The path where the RPC is located

Default None

request_class

alias of Request

JSON RPC

class pulsar.apps.rpc.JSONRPC(subhandlers=None, title=None, documentation=None)

A RpcHandler for class for JSON-RPC services. Design to comply with the JSON-RPC 2.0 Specification.

get_method_and_args(data)

Overrides the RpcHandler:get_method_and_args() to obtain method data from the JSON data string.

dumps(id, version, result=None, error=None)

Modify JSON dumps method to comply with JSON-RPC Specification 2.0

JsonProxy

class pulsar.apps.rpc.JsonProxy(url, version=None, data=None, full_response=False, **kw)

A python Proxy class for JSONRPC Servers.

Parameters:

• url – server location
• version – JSONRPC server version. Default 2.0
• id – optional request id, generated if not provided. Default None.
• data – Extra data to include in all requests. Default None.
• http –

  optional http opener. If provided it must have the request method available which must be of the form:

  http.request(url, body=..., method=...)
  

  Default None.

Lets say your RPC server is running at http://domain.name.com/:

>>> a = JsonProxy('http://domain.name.com/')
>>> a.add(3,4)
7
>>> a.ping()
'pong'

makeid()

Can be re-implemented by your own Proxy

timeit(func, times, *args, **kwargs)

Usefull little utility for timing responses from server. The usage is simple:

>>> from pulsar.apps import rpc
>>> p = rpc.JsonProxy('http://127.0.0.1:8060')
>>> p.timeit('ping',10)
0.56...
>>> _

get_params(*args, **kwargs)

Create an array or positional or named parameters Mixing positional and named parameters in one call is not possible.

FromApi

pulsar.apps.rpc.FromApi(func, doc=None, format='json', request_handler=None)

A decorator which exposes a function func as an rpc function.

Parameters:

• func – The function to expose.
• doc – Optional doc string. If not provided the doc string of func will be used.
• format – Optional output format.
• request_handler – function which takes request, format and kwargs and return a new kwargs to be passed to func. It can be used to add additional parameters based on request and format.

Server Commands

class pulsar.apps.rpc.PulsarServerCommands(subhandlers=None, title=None, documentation=None)

Some useful commands to add to your JSONRPC handler to get you

started. It exposes the following functions:

ping()

Return pong.

server_info()

Return a dictionary of information regarding the server and workers. It invokes the extra_server_info() for adding custom information.

Return type:dict.

functions_list()

Return the list of functions available in the rpc handler

Return type:list.

kill_actor(aid)

Parameters:aid – pulsar.Actor.aid of the actor to kill

extra_server_info(request, info)

Add additional information to the info dictionary.