jsonrpcclient over ZeroMQ¶

Send JSON-RPC requests over ZeroMQ.

Installation¶

$ pip install jsonrpcclient pyzmq

Usage¶

Set the server details:

from jsonrpcclient.zmq_server import ZMQServer
server = ZMQServer('tcp://localhost:5555')

Send a request with send():

>>> server.send({'jsonrpc': '2.0', 'method': 'cat', 'id': 1})

Sending a request is easier with request(). It takes the method, followed by the arguments to the method:

>>> server.request('cat', name='Mittens')

When sending a single request, the return value is the payload (the result part of the JSON-RPC response message).

If you’re not interested in a response, use notify() instead of request().

Batch requests¶

Send multiple requests in one message:

>>> server.send([{'jsonrpc': '2.0', 'method': 'cat'}, {'jsonrpc': '2.0', 'method': 'dog'}])

Send multiple Request objects:

>>> server.send([Request('cat'), Request('dog')])

Using list comprehension to get the cube of ten numbers:

>>> server.send([Request('cube', i) for i in range(10)])

Unlike single requests, batch requests return the whole JSON-RPC response object, i.e. a list of responses for each request that had an id member.

Note

The server may not support batch requests.

Exceptions¶

In the event of a communications problem, pyzmq raises zmq.ZMQError:

try:
    server.request('go')
except zmq.ZMQError as e:
    print(str(e))

The jsonrpcclient library also raises exceptions, for example if the server responded with an error message. The full list of exceptions are here.

Logging¶

To see the JSON-RPC messages going back and forth, set the logging level to INFO:

import logging
logging.getLogger('jsonrpcclient').setLevel(logging.INFO)

Then add a basic handler:

logging.getLogger('jsonrpcclient').addHandler(logging.StreamHandler())

Or use custom handlers and formats:

request_format = '%(endpoint)s --> %(message)s'
response_format = '%(endpoint)s <-- %(message)s'

# Request log
request_handler = logging.StreamHandler()
request_handler.setFormatter(logging.Formatter(fmt=request_format))
logging.getLogger('jsonrpcclient.server.request').addHandler(
    request_handler)

# Response log
response_handler = logging.StreamHandler()
response_handler.setFormatter(logging.Formatter(fmt=response_format))
logging.getLogger('jsonrpcclient.server.response').addHandler(
    response_handler)

The request format has these fields:

endpoint:	The server endpoint, eg. `http://localhost:5555`.
message:	The JSON request (the body).

The response format has these fields:

endpoint:	The server endpoint, eg. `http://localhost:5555`.
message:	The JSON response (the body).

Examples¶

ZeroMQ Client using PyZMQ

Back home