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, 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
id – optional request id, generated if not provided. Default None.
data – Extra data to include in all requests. Default None.
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.request(url, body=..., method=...)
```
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'

get_params(*args, **kwargs)[source]¶: Create an array or positional or named parameters Mixing positional and named parameters in one call is not possible.

makeid()[source]¶: Can be re-implemented by your own Proxy

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:

extra_server_info(request, info)[source]¶

An internal method.

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

rpc_documentation(request)[source]¶: Documentation in restructured text.

rpc_echo(request, message='')[source]¶: Echo the server.

rpc_functions_list(request)[source]¶: List of (method name, method document) pair of all method exposed by this JSONRPC handler.

rpc_kill_actor(request, aid)[source]¶: Kill the actor with id equal to aid.

rpc_ping(request)[source]¶: Ping 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.