API¶

HTTPServer¶

An HTTP server to communicate with, for example:

HTTPServer('http://example.com/api').request('go')

class http_server.HTTPServer(endpoint)¶

Parameters:	endpoint – The server address. kwargs – HTTP headers and other options passed on to the requests module.

notify(method_name, *args, **kwargs)¶

Send a JSON-RPC request, without expecting a response.

Parameters:	method_name – The remote procedure’s method name. args – Positional arguments passed to the remote procedure. kwargs – Keyword arguments passed to the remote procedure.
Returns:	The payload (i.e. the `result` part of the response.)

request(method_name, *args, **kwargs)¶

Send a JSON-RPC request, and get a response.

Parameters:	method_name – The remote procedure’s method name. args – Positional arguments passed to the remote procedure. kwargs – Keyword arguments passed to the remote procedure.
Returns:	The payload (i.e. the `result` part of the response.)

send(request, **kwargs)¶

Send a request or batch of requests.

Parameters:	request – The request to send. If a string, must be valid JSON (double quotes around the identifiers!). Otherwise it must be a json serializable object (list or dict).
Raises:	jsonrpcclient.ParseResponseError – The response was not valid JSON. (doc) jsonschema.ValidationError – The response was not a valid JSON-RPC response. (doc) jsonrpcclient.ReceivedErrorResponse – The server responded with an error message. (doc)

validate = True¶

ZMQServer¶

A ZeroMQ server to communicate with, for example:

ZMQServer('tcp://hostname:5555').request('go')

class zmq_server.ZMQServer(endpoint, socket_type=3)¶

Parameters:	endpoint – The server address. socket_type – The zeromq socket type. Default is zmq.REQ.

notify(method_name, *args, **kwargs)¶

Send a JSON-RPC request, without expecting a response.

Parameters:	method_name – The remote procedure’s method name. args – Positional arguments passed to the remote procedure. kwargs – Keyword arguments passed to the remote procedure.
Returns:	The payload (i.e. the `result` part of the response.)

request(method_name, *args, **kwargs)¶

Send a JSON-RPC request, and get a response.

Parameters:	method_name – The remote procedure’s method name. args – Positional arguments passed to the remote procedure. kwargs – Keyword arguments passed to the remote procedure.
Returns:	The payload (i.e. the `result` part of the response.)

send(request, **kwargs)¶

Send a request or batch of requests.

Parameters:	request – The request to send. If a string, must be valid JSON (double quotes around the identifiers!). Otherwise it must be a json serializable object (list or dict).
Raises:	jsonrpcclient.ParseResponseError – The response was not valid JSON. (doc) jsonschema.ValidationError – The response was not a valid JSON-RPC response. (doc) jsonrpcclient.ReceivedErrorResponse – The server responded with an error message. (doc)

validate = True¶

Requests¶

These classes make it easy to create JSON-RPC Request objects.

request.Notification¶

A JSON-RPC Request object, with no id member (meaning no payload data is wanted):

>>> from jsonrpcclient import Notification
>>> Notification('cat')
{'jsonrpc': '2.0', 'method': 'cat'}

The first argument is the method; everything else is arguments to the method:

>>> Notification('cat', 'Mittens', 5)
{'jsonrpc': '2.0', 'method': 'cat', params: ['Mittens', 5]}

Keyword arguments are also acceptable:

>>> Notification('cat', name='Mittens', age=5)
{'jsonrpc': '2.0', 'method': 'cat', 'params': {'name': 'Mittens', 'age': 5}}

If you prefer, call the method as though it was a class attribute:

>>> Notification.cat(name='Mittens', age=5)
{'jsonrpc': '2.0', 'method': 'cat', 'params': {'name': 'Mittens', 'age': 5}}

Parameters:	method – The method name. args – Positional arguments. kwargs – Keyword arguments.
Returns:	The JSON-RPC request in dictionary form.

request.Request¶

A JSON-RPC Request object, with an id member (meaning payload data is wanted):

>>> Request('cat')
{'jsonrpc': '2.0', 'method': 'cat', 'id': 1}

An auto-incremented id is used, so each request has a unique id:

>>> Request('cat')
{'jsonrpc': '2.0', 'method': 'cat', 'id': 2}

Use request_id to specify the id to use:

>>> Request('cat', request_id='Request #1')
{'jsonrpc': '2.0', 'method': 'cat', 'id': 'Request #1'}

Parameters:	method – The method name. args – Positional arguments. kwargs – Keyword arguments.
Returns:	The JSON-RPC request in dictionary form.

ID Iterators¶

By default the request id is a decimal number which increments for each request. Use a different format by setting Request.id_iterator:

>>> from jsonrpcclient.request import Request
>>> from jsonrpcclient.id_iterators import random_iterator
>>> Request.id_iterator = random_iterator()
>>> Request('go')
{'jsonrpc': '2.0', 'method': 'go', 'id': 'fubui5e6'}

id_iterators.hex_iterator(start=1)¶

Incremental hexadecimal numbers.

e.g. ‘1’, ‘2’ .. ‘9’, ‘a’, ‘b’, etc.

Request.id_iterator = hex_iterator()

id_iterators.uuid_iterator()¶

Unique uuid ids.

e.g. ‘9bfe2c93-717e-4a45-b91b-55422c5af4ff’

Request.id_iterator = uuid_iterator()

id_iterators.random_iterator(length=8, chars='0123456789abcdefghijklmnopqrstuvwxyz')¶

A random string. Not unique, but has around 1 in a million chance of collision with default values.

e.g. ‘fubui5e6’

Request.id_iterator = random_iterator(16, 'abc123')

Parameters:	length – Length of the random string. chars – The characters to randomly choose from.

Exceptions¶

These exceptions are raised when processing responses from the server. For example, if the response was garbage and could not be parsed, ParseResponseError is raised.

To handle them, use a try-block when calling notify or request:

try:
    server.notify('go')
except JsonRpcClientError as e:
    print(str(e))

exception jsonrpcclient.exceptions.JsonRpcClientError¶

Bases: Exception

Base class for the other exceptions.

exception jsonrpcclient.exceptions.ParseResponseError¶

Bases: jsonrpcclient.exceptions.JsonRpcClientError

The response was not valid JSON.

exception jsonrpcclient.exceptions.ReceivedErrorResponse(code, message, data)¶

Bases: jsonrpcclient.exceptions.JsonRpcClientError

Raised if a single JSON-RPC error response object is received. This is not raised for batch requests.

This error means one of two things:

There was a problem with the request.
There was a problem with the application at the receiving end.

To see information about the error, catch the exception:

from jsonrpcclient.exceptions import JsonRpcClientError, \
    ReceivedErrorResponse
try:
    server.notify('go')
except ReceivedErrorResponse as e:
    print(e.code, e.message, e.data)
except JsonRpcClientError as e:
    print(str(e))