JSON-RPC

Asynchronous WSGI Remote Procedure Calls middleware. It implements a JSON-RPC server and client. Check out the json-rpc tutorial if you want to get started quickly with a working example.

To quickly setup a server:

class MyRpc(rpc.JSONRPC):

    def rpc_ping(self, request):
        return 'pong'


class Wsgi(wsgi.LazyWsgi):

    def handler(self, environ=None):
        app = wsgi.Router('/',
                          post=MyRpc(),
                          response_content_types=['application/json'])
        return wsgi.WsgiHandler([app])

if __name__ == '__main__':
    wsgi.WSGIServer(Wsgi()).start()
  • The MyRpc handles the requests
  • Routing is delegated to the Router which handle only post requests with content type application/json.

API

RpcHandler

class pulsar.apps.rpc.handlers.RpcHandler(subhandlers=None, title=None, documentation=None)[source]

Base class for classes to handle remote procedure calls.

serve_as = 'rpc'

Prefix for class methods providing remote services. Default: rpc.

separator = '.'

HTTP method allowed by this handler.

parent

The parent RpcHandler or None if this is the root handler.

root

The root RpcHandler or self if this is the root handler.

isroot()[source]

True if this is the root handler.

putSubHandler(prefix, handler)[source]

Add a sub RpcHandler with prefix prefix.

Parameters:
  • prefix – a string defining the prefix of the subhandler
  • handler – the sub-handler.
getSubHandler(prefix)[source]

Get a sub RpcHandler at prefix.

rpc method decorator

pulsar.apps.rpc.handlers.rpc_method(func, doc=None, format='json', request_handler=None)[source]

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.

JSON RPC

class pulsar.apps.rpc.jsonrpc.JSONRPC(subhandlers=None, title=None, documentation=None)[source]

An RpcHandler for JSON-RPC services.

Design to comply with the JSON-RPC 2.0 Specification.

JSON-RPC is a lightweight remote procedure call protocol designed to be simple. A remote method is invoked by sending a request to a remote service, the request is a single object serialised using JSON.

JsonProxy

class pulsar.apps.rpc.jsonrpc.JsonProxy(url, version=None, data=None, headers=None, full_response=False, http=None, timeout=None, sync=False, loop=None, encoding='ascii', **kw)[source]

A python Proxy class for JSONRPC Servers.

Parameters:
  • url – server location
  • version – JSON-RPC server version. Default 2.0
  • data – Extra data to include in all requests. Default None
  • headers – optional HTTP headers to send with requests
  • full_response – return the full Http response rather than just the content.
  • http

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

    http.post(url, data=..., headers=...)
    

    Default None.

  • encoding – encoding of the request. Default ascii.

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()[source]

Can be re-implemented by your own Proxy

get_params(*args, **kwargs)[source]

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

Server Commands

class pulsar.apps.rpc.mixins.PulsarServerCommands(subhandlers=None, title=None, documentation=None)[source]

Useful commands to add to your JSONRPC handler.

It exposes the following functions:

rpc_ping(request)[source]

Ping the server.

rpc_echo(request, message='')[source]

Echo the server.

rpc_server_info(request)[source]

Return a dictionary of information regarding the server and workers.

It invokes the extra_server_info() for adding custom information.

rpc_functions_list(request)[source]

List of (method name, method document) pair of all method exposed by this JSONRPC handler.

rpc_documentation(request)[source]

Documentation in restructured text.

rpc_kill_actor(request, aid)[source]

Kill the actor with id equal to aid.

extra_server_info(request, info)[source]

An internal method.

Used by the rpc_server_info() method to add additional information to the info dictionary.