jsonrpcclient API¶
Request¶
-
Server.
request
(method_name, *args, **kwargs)¶ Send a request, by passing the method and arguments. This is the main public method.
>>> server.request('cat', name='Mittens') --> {"jsonrpc": "2.0", "method": "cat", "params": {"name": "Mittens"}, "id": 1} <-- {"jsonrpc": "2.0", "result": "meow", "id": 1} 'meow'
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).
If you’re not interested in a response, use notify()
instead of
request()
.
Send¶
-
Server.
send
(request, **kwargs)¶ Send a request, passing the whole JSON-RPC request object.
>>> server.send({'jsonrpc': '2.0', 'method': 'ping', 'id': 1}) --> {"jsonrpc": "2.0", "method": "ping", "id": 1} <-- {"jsonrpc": "2.0", "result": "pong", "id": 1} 'pong'
Parameters: - request (string or a JSON serializable object) – The JSON-RPC request.
- kwargs – For HTTPServer, these are passed on to requests.Session.send().
Returns: The payload (i.e. the
result
part of the response, orNone
in the case of a Notification).Return type: Raises: - ParseResponseError – The response was not valid JSON.
- ValidationError – The response was valid JSON, but not valid JSON-RPC.
- ReceivedErrorResponse – The server responded with a JSON-RPC error object.
Request class¶
from jsonrpcclient import Request
-
class
request.
Request
(method, *args, **kwargs)¶ Create a JSON-RPC request object.
>>> Request('cat', name='Mittens') {'jsonrpc': '2.0', 'method': 'cat', {'params': {'name': 'Mittens'}}, 'id': 1}
Parameters: - method – The
method
name. - args – Positional arguments added to
params
. - kwargs – Keyword arguments added to
params
. Userequest_id=x
to force theid
to use.
Returns: The JSON-RPC request in dictionary form.
-
id_iterator
= None¶
- method – The
Send a Request
object:
>>> server.send(Request('ping'))
--> {"jsonrpc": "2.0", "method": "ping", "id": 1}
<-- {"jsonrpc": "2.0", "result": "pong", "id": 1}
'pong'
The request()
method is a wrapper around
send(Request())
.
If you’re not interested in a response, use the Notification
class instead
of Request
.
Batch requests¶
This JSON-RPC feature allows you to send multiple requests in a single message:
server.send([
{'jsonrpc': '2.0', 'method': 'cat', 'id': 1}, \
{'jsonrpc': '2.0', 'method': 'dog', 'id': 2}])
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 - a list of responses for each request that had an id
member.
The server may not support batch requests.
Configuration¶
Some options can be configured in the config
module. Import it and modify
the attributes, for example:
from jsonrpcclient import config
config.validate = False
-
config.
validate
= True¶ Validate responses against the JSON-RPC schema. Disable to speed up processing.
-
config.
ids
= 'decimal'¶ Configure the
id
part of requests. Can be “decimal”, “hex”, “random” or “uuid”.
Configuring the Requests library¶
HTTPServer makes use of Kenneth Reitz’s Requests library. The Session is available so you can configure it before sending any requests.
For example, Basic Auth:
server.session.auth = ('user', 'pass')
SSL authentication:
server.session.verify = '/path/to/certificate'
Custom HTTP headers:
server.session.headers.update({'Content-Type': 'application/json-rpc'})
You can also configure some Requests options when calling
send()
:
server.send(req, verify=True, cert='/path/to/certificate', \
headers={'Content-Type': 'application/json-rpc'})
As in the Requests library, any dictionaries passed to send in named arguments will be merged with the session-level values that are set. The method-level parameters override session parameters.