Client¶
pjrpc
client provides three main method invocation approaches:
using handmade
pjrpc.common.Request
class object
client = Client('http://server/api/v1')
response: pjrpc.Response = client.send(Request('sum', params=[1, 2], id=1))
print(f"1 + 2 = {response.result}")
using
__call__
method
client = Client('http://server/api/v1')
result = client('sum', a=1, b=2)
print(f"1 + 2 = {result}")
using proxy object
client = Client('http://server/api/v1')
result = client.proxy.sum(1, 2)
print(f"1 + 2 = {result}")
client = Client('http://server/api/v1')
result = client.proxy.sum(a=1, b=2)
print(f"1 + 2 = {result}")
Requests without id in JSON-RPC semantics called notifications. To send a notification to the server you need to send a request without id:
client = Client('http://server/api/v1')
response: pjrpc.Response = client.send(Request('sum', params=[1, 2]))
or use a special method pjrpc.client.AbstractClient.notify()
client = Client('http://server/api/v1')
client.notify('tick')
Asynchronous client api looks pretty much the same:
client = Client('http://server/api/v1')
result = await client.proxy.sum(1, 2)
print(f"1 + 2 = {result}")
Batch requests¶
Batch requests also supported. There are several approaches of sending batch requests:
using handmade
pjrpc.common.Request
class object. The result is apjrpc.common.BatchResponse
instance you can iterate over to get all the results or get each one by index:
client = Client('http://server/api/v1')
batch_response = client.batch.send(BatchRequest(
pjrpc.Request('sum', [2, 2], id=1),
pjrpc.Request('sub', [2, 2], id=2),
pjrpc.Request('div', [2, 2], id=3),
pjrpc.Request('mult', [2, 2], id=4),
))
print(f"2 + 2 = {batch_response[0].result}")
print(f"2 - 2 = {batch_response[1].result}")
print(f"2 / 2 = {batch_response[2].result}")
print(f"2 * 2 = {batch_response[3].result}")
using
__call__
method chain:
client = Client('http://server/api/v1')
result = client.batch('sum', 2, 2)('sub', 2, 2)('div', 2, 2)('mult', 2, 2).call()
print(f"2 + 2 = {result[0]}")
print(f"2 - 2 = {result[1]}")
print(f"2 / 2 = {result[2]}")
print(f"2 * 2 = {result[3]}")
using subscription operator:
client = Client('http://server/api/v1')
result = client.batch[
('sum', 2, 2),
('sub', 2, 2),
('div', 2, 2),
('mult', 2, 2),
]
print(f"2 + 2 = {result[0]}")
print(f"2 - 2 = {result[1]}")
print(f"2 / 2 = {result[2]}")
print(f"2 * 2 = {result[3]}")
using proxy chain call:
client = Client('http://server/api/v1')
result = client.batch.proxy.sum(2, 2).sub(2, 2).div(2, 2).mult(2, 2).call()
print(f"2 + 2 = {result[0]}")
print(f"2 - 2 = {result[1]}")
print(f"2 / 2 = {result[2]}")
print(f"2 * 2 = {result[3]}")
Which one to use is up to you but be aware that if any of the requests returns an error the result of the other ones will be lost. In such case the first approach can be used to iterate over all the responses and get the results of the succeeded ones like this:
import pjrpc
from pjrpc.client.backend import requests as pjrpc_client
client = pjrpc_client.Client('http://localhost/api/v1')
batch_response = client.batch.send(pjrpc.BatchRequest(
pjrpc.Request('sum', [2, 2], id=1),
pjrpc.Request('sub', [2, 2], id=2),
pjrpc.Request('div', [2, 2], id=3),
pjrpc.Request('mult', [2, 2], id=4),
))
for response in batch_response:
if response.is_success:
print(response.result)
else:
print(response.error)
Notifications also supported:
import pjrpc
from pjrpc.client.backend import requests as pjrpc_client
client = pjrpc_client.Client('http://localhost/api/v1')
client.batch.notify('tick').notify('tack').notify('tick').notify('tack').call()
Id generators¶
The library request id generator can also be customized. There are four generator types implemented in the library
see pjrpc.common.generators
. You can implement your own one and pass it to a client by id_gen
parameter.