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:
-
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:
-
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 uniqueid
:>>> Request('cat') {'jsonrpc': '2.0', 'method': 'cat', 'id': 2}
Use
request_id
to specify theid
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))