Client

Misc

JSON-RPC client.

class pjrpc.client.AbstractClient(request_class=<class 'pjrpc.common.v20.Request'>, response_class=<class 'pjrpc.common.v20.Response'>, batch_request_class=<class 'pjrpc.common.v20.BatchRequest'>, batch_response_class=<class 'pjrpc.common.v20.BatchResponse'>, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>, id_gen_impl=<function sequential>, json_loader=<function loads>, json_dumper=<function dumps>, json_encoder=<class 'pjrpc.common.common.JSONEncoder'>, json_decoder=None, strict=True, request_args=None, tracers=(), retry_strategy=None)

Bases: BaseAbstractClient

Abstract synchronous JSON-RPC client.

Parameters:

• request_class (Type[Request]) –

• response_class (Type[Response]) –

• batch_request_class (Type[BatchRequest]) –

• batch_response_class (Type[BatchResponse]) –

• error_cls (Type[JsonRpcError]) –

• id_gen_impl (Callable[[...], Generator[Union[str, int], None, None]]) –

• json_loader (Callable[[...], Any]) –

• json_dumper (Callable[[...], str]) –

• json_encoder (Type[JSONEncoder]) –

• json_decoder (Optional[JSONDecoder]) –

• strict (bool) –

• request_args (Optional[Dict[str, Any]]) –

• tracers (Iterable[Tracer]) –

• retry_strategy (Optional[RetryStrategy]) –

property batch: Batch

Client batch wrapper.

notify(method, *args, _trace_ctx=namespace(), **kwargs)

Makes a notification request

Parameters:

• method (str) – method name

• args (Any) – method positional arguments

• kwargs (Any) – method named arguments

• _trace_ctx (SimpleNamespace) – tracers request context

Return type:

Optional[Response]

call(method, *args, _trace_ctx=namespace(), **kwargs)

Makes JSON-RPC call.

Parameters:

• method (str) – method name

• args (Any) – method positional arguments

• kwargs (Any) – method named arguments

• _trace_ctx (SimpleNamespace) – tracers request context

Returns:

response result

Return type:

Any

send(request, _trace_ctx=namespace(), _retry_strategy=UNSET, **kwargs)

Sends a JSON-RPC request.

Parameters:

• request (Request) – request instance

• kwargs (Any) – additional client request argument

• _trace_ctx (SimpleNamespace) – tracers request context

• _retry_strategy (Union[UnsetType, RetryStrategy]) – request retry strategy

Returns:

response instance

Return type:

Optional[Response]

class pjrpc.client.AbstractAsyncClient(request_class=<class 'pjrpc.common.v20.Request'>, response_class=<class 'pjrpc.common.v20.Response'>, batch_request_class=<class 'pjrpc.common.v20.BatchRequest'>, batch_response_class=<class 'pjrpc.common.v20.BatchResponse'>, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>, id_gen_impl=<function sequential>, json_loader=<function loads>, json_dumper=<function dumps>, json_encoder=<class 'pjrpc.common.common.JSONEncoder'>, json_decoder=None, strict=True, request_args=None, tracers=(), retry_strategy=None)

Bases: BaseAbstractClient

Abstract asynchronous JSON-RPC client.

Parameters:

• request_class (Type[Request]) –

• response_class (Type[Response]) –

• batch_request_class (Type[BatchRequest]) –

• batch_response_class (Type[BatchResponse]) –

• error_cls (Type[JsonRpcError]) –

• id_gen_impl (Callable[[...], Generator[Union[str, int], None, None]]) –

• json_loader (Callable[[...], Any]) –

• json_dumper (Callable[[...], str]) –

• json_encoder (Type[JSONEncoder]) –

• json_decoder (Optional[JSONDecoder]) –

• strict (bool) –

• request_args (Optional[Dict[str, Any]]) –

• tracers (Iterable[Tracer]) –

• retry_strategy (Optional[RetryStrategy]) –

property batch: AsyncBatch

Client batch wrapper.

async send(request, _trace_ctx=namespace(), _retry_strategy=UNSET, **kwargs)

Sends a JSON-RPC request.

Parameters:

• request (Request) – request instance

• kwargs (Any) – additional client request argument

• _trace_ctx (SimpleNamespace) – tracers request context

• _retry_strategy (Union[UnsetType, RetryStrategy]) – request retry strategy

Returns:

response instance

Return type:

Optional[Response]

async notify(method, *args, _trace_ctx=namespace(), **kwargs)

Makes a notification request

Parameters:

• method (str) – method name

• args (Any) – method positional arguments

• kwargs (Any) – method named arguments

• _trace_ctx (SimpleNamespace) – tracers request context

Return type:

Optional[Response]

async call(method, *args, _trace_ctx=namespace(), **kwargs)

Makes JSON-RPC call.

Parameters:

• method (str) – method name

• args (Any) – method positional arguments

• kwargs (Any) – method named arguments

• _trace_ctx (SimpleNamespace) – tracers request context

Returns:

response result

Return type:

Any

class pjrpc.client.AsyncBatch(client)

Bases: BaseBatch

Asynchronous batch wrapper. Used to make asynchronous JSON-RPC batch requests.

Parameters:

client (AbstractAsyncClient) –

class Proxy(batch)

Bases: BaseProxy

Parameters:

batch (AsyncBatch) –

async call(_trace_ctx=namespace())

Makes an RPC call.

Parameters:

_trace_ctx (SimpleNamespace) – tracers request context

Return type:

Any

property proxy: Proxy

Batch request proxy object.

async call(_trace_ctx=namespace())

Makes a JSON-RPC request.

Parameters:

_trace_ctx (SimpleNamespace) – tracers request context

Returns:

request results as a tuple

Return type:

Optional[Any]

async send(request, _trace_ctx=namespace(), **kwargs)

Sends a JSON-RPC batch request.

Parameters:

• request (BatchRequest) – request instance

• kwargs (Any) – additional client request argument

• _trace_ctx (SimpleNamespace) – tracers request context

Returns:

response instance

Return type:

Optional[BatchResponse]

class pjrpc.client.BaseBatch(client)

Bases: ABC

Base batch wrapper. Implements some methods to wrap multiple JSON-RPC requests into a single batch request.

Parameters:

client (BaseAbstractClient) – JSON-RPC client instance

class BaseProxy(batch)

Bases: ABC

Proxy object. Provides syntactic sugar to make method calls using dot notation.

Parameters:

batch (BaseBatch) – batch wrapper

abstract call(_trace_ctx=namespace())

Makes an RPC call.

Parameters:

_trace_ctx (SimpleNamespace) – tracers request context

Return type:

Union[Awaitable[Any], Any]

abstract property proxy: BaseProxy

Batch request proxy object.

abstract call(_trace_ctx=namespace())

Makes a JSON-RPC request.

Parameters:

_trace_ctx (SimpleNamespace) – tracers request context

Returns:

request results as a tuple

Return type:

Union[Awaitable[Any], Any]

abstract send(request, _trace_ctx=namespace(), **kwargs)

Sends a JSON-RPC batch request.

Parameters:

• request (BatchRequest) – request instance

• kwargs (Any) – additional client request argument

• _trace_ctx (SimpleNamespace) – tracers request context

Returns:

response instance

Return type:

Optional[Union[Awaitable[Optional[BatchResponse]], BatchResponse]]

add(method, *args, **kwargs)

Adds the method call to the batch.

Parameters:

• method (str) – method name

• args (Any) – method positional arguments

• kwargs (Any) – method named arguments

Returns:

self

Return type:

BaseBatch

notify(method, *args, **kwargs)

Adds a notification request to the batch.

Parameters:

• method (str) – method name

• args (Any) – method positional arguments

• kwargs (Any) – method named arguments

Return type:

BaseBatch

class pjrpc.client.BaseAbstractClient(request_class=<class 'pjrpc.common.v20.Request'>, response_class=<class 'pjrpc.common.v20.Response'>, batch_request_class=<class 'pjrpc.common.v20.BatchRequest'>, batch_response_class=<class 'pjrpc.common.v20.BatchResponse'>, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>, id_gen_impl=<function sequential>, json_loader=<function loads>, json_dumper=<function dumps>, json_encoder=<class 'pjrpc.common.common.JSONEncoder'>, json_decoder=None, strict=True, request_args=None, tracers=(), retry_strategy=None)

Bases: ABC

Base abstract JSON-RPC client.

Parameters:

• request_class (Type[Request]) – request class

• response_class (Type[Response]) – response class

• batch_request_class (Type[BatchRequest]) – batch request class

• batch_response_class (Type[BatchResponse]) – batch response class

• error_cls (Type[JsonRpcError]) – JSON-RPC error base class

• id_gen_impl (Callable[[...], Generator[Union[str, int], None, None]]) – identifier generator

• json_loader (Callable[[...], Any]) – json loader

• json_dumper (Callable[[...], str]) – json dumper

• json_encoder (Type[JSONEncoder]) – json encoder

• json_decoder (Optional[JSONDecoder]) – json decoder

• strict (bool) – if True checks that a request and a response identifiers match

• request_args (Optional[Dict[str, Any]]) – backend request argument

• tracers (Iterable[Tracer]) – request tracers list

• retry_strategy (Optional[RetryStrategy]) – request retry strategy

class Proxy(client)

Bases: object

Proxy object. Provides syntactic sugar to make method call using dot notation.

Parameters:

client (BaseAbstractClient) – JSON-RPC client instance

property proxy: Proxy

Clint proxy object.

class pjrpc.client.Batch(client)

Bases: BaseBatch

Batch wrapper. Implements some methods to wrap multiple JSON-RPC requests into a single batch request.

Parameters:

client (AbstractClient) – JSON-RPC client instance

class Proxy(batch)

Bases: BaseProxy

Parameters:

batch (Batch) –

call(_trace_ctx=namespace())

Makes an RPC call.

Parameters:

_trace_ctx (SimpleNamespace) – tracers request context

Return type:

Any

property proxy: Proxy

Batch request proxy object.

call(_trace_ctx=namespace())

Makes a JSON-RPC request.

Parameters:

_trace_ctx (SimpleNamespace) – tracers request context

Returns:

request results as a tuple

Return type:

Optional[Any]

send(request, _trace_ctx=namespace(), **kwargs)

Sends a JSON-RPC batch request.

Parameters:

• request (BatchRequest) – request instance

• kwargs (Any) – additional client request argument

• _trace_ctx (SimpleNamespace) – tracers request context

Returns:

response instance

Return type:

Optional[BatchResponse]

class pjrpc.client.LoggingTracer(logger=<Logger pjrpc.client (WARNING)>, level=10)

Bases: Tracer

JSON-RPC client logging tracer.

Parameters:

• logger (Logger) –

• level (int) –

on_request_begin(trace_context, request)

Handler called before JSON-RPC request begins.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

Return type:

None

on_request_end(trace_context, request, response)

Handler called after JSON-RPC request ends.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• response (Optional[AbstractResponse]) – JSON-RPC response

Return type:

None

on_error(trace_context, request, error)

Handler called when JSON-RPC request failed.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• error (BaseException) – raised exception

Return type:

None

class pjrpc.client.Tracer

Bases: object

JSON-RPC client tracer.

on_request_begin(trace_context, request)

Handler called before JSON-RPC request begins.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

Return type:

None

on_request_end(trace_context, request, response)

Handler called after JSON-RPC request ends.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• response (Optional[AbstractResponse]) – JSON-RPC response

Return type:

None

on_error(trace_context, request, error)

Handler called when JSON-RPC request failed.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• error (BaseException) – raised exception

Return type:

None

Backends

class pjrpc.client.backend.requests.Client(url, session=None, **kwargs)

Bases: AbstractClient

Requests library client backend.

Parameters:

• url (str) – url to be used as JSON-RPC endpoint.

• session (Optional[Session]) – custom session to be used instead of requests.Session

• kwargs (Any) – parameters to be passed to pjrpc.client.AbstractClient

close()

Closes the current http session.

Return type:

None

class pjrpc.client.backend.aiohttp.Client(url, session_args=None, session=None, **kwargs)

Bases: AbstractAsyncClient

Aiohttp library client backend.

Parameters:

• url (str) – url to be used as JSON-RPC endpoint

• session_args (Optional[Dict[str, Any]]) – additional aiohttp.ClientSession arguments

• session (Optional[ClientSession]) – custom session to be used instead of aiohttp.ClientSession

• kwargs (Any) –

async close()

Closes current http session.

Return type:

None

class pjrpc.client.backend.kombu.Client(broker_url, queue_name=None, conn_args=None, exchange_name=None, exchange_args=None, routing_key=None, result_queue_name=None, result_queue_args=None, **kwargs)

Bases: AbstractClient

kombu based JSON-RPC client. Note: the client is not thread-safe.

Parameters:

• broker_url (str) – broker connection url

• conn_args (Optional[Dict[str, Any]]) – broker connection arguments.

• queue_name (Optional[str]) – queue name to publish requests to

• exchange_name (Optional[str]) – exchange to publish requests to. If None default exchange is used

• exchange_args (Optional[Dict[str, Any]]) – exchange arguments

• routing_key (Optional[str]) – reply message routing key. If None queue name is used

• result_queue_name (Optional[str]) – result queue name. If None random exclusive queue is declared for each request

• conn_args – additional connection arguments

• kwargs (Any) – parameters to be passed to pjrpc.client.AbstractClient

• result_queue_args (Optional[Dict[str, Any]]) –

close()

Closes the current broker connection.

Return type:

None

class pjrpc.client.backend.aio_pika.Client(broker_url, queue_name=None, conn_args=None, exchange_name=None, exchange_args=None, routing_key=None, result_queue_name=None, result_queue_args=None, **kwargs)

Bases: AbstractAsyncClient

aio_pika based JSON-RPC client.

Parameters:

• broker_url (URL) – broker connection url

• conn_args (Optional[Dict[str, Any]]) – broker connection arguments.

• queue_name (Optional[str]) – queue name to publish requests to

• exchange_name (Optional[str]) – exchange to publish requests to. If None default exchange is used

• exchange_args (Optional[Dict[str, Any]]) – exchange arguments

• routing_key (Optional[str]) – reply message routing key. If None queue name is used

• result_queue_name (Optional[str]) – result queue name. If None random exclusive queue is declared for each request

• conn_args – additional connection arguments

• kwargs (Any) – parameters to be passed to pjrpc.client.AbstractClient

• result_queue_args (Optional[Dict[str, Any]]) –

async connect()

Opens a connection to the broker.

Return type:

None

async close()

Closes current broker connection.

Return type:

None

Tracer

class pjrpc.client.tracer.Tracer

Bases: object

JSON-RPC client tracer.

on_request_begin(trace_context, request)

Handler called before JSON-RPC request begins.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

Return type:

None

on_request_end(trace_context, request, response)

Handler called after JSON-RPC request ends.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• response (Optional[AbstractResponse]) – JSON-RPC response

Return type:

None

on_error(trace_context, request, error)

Handler called when JSON-RPC request failed.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• error (BaseException) – raised exception

Return type:

None

class pjrpc.client.tracer.LoggingTracer(logger=<Logger pjrpc.client (WARNING)>, level=10)

Bases: Tracer

JSON-RPC client logging tracer.

Parameters:

• logger (Logger) –

• level (int) –

on_request_begin(trace_context, request)

Handler called before JSON-RPC request begins.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

Return type:

None

on_request_end(trace_context, request, response)

Handler called after JSON-RPC request ends.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• response (Optional[AbstractResponse]) – JSON-RPC response

Return type:

None

on_error(trace_context, request, error)

Handler called when JSON-RPC request failed.

Parameters:

• trace_context (SimpleNamespace) – request trace context

• request (AbstractRequest) – JSON-RPC request

• error (BaseException) – raised exception

Return type:

None

Retry

class pjrpc.client.retry.Backoff(attempts, jitter=<function Backoff.<lambda>>)

Bases: object

JSON-RPC request retry strategy.

Parameters:

• attempts (int) – retries number

• jitter (Callable[[], float]) – retry delay jitter generator

class pjrpc.client.retry.PeriodicBackoff(attempts, jitter=<function Backoff.<lambda>>, interval=1.0)

Bases: Backoff

Periodic request retry strategy.

Parameters:

• interval (float) – retry delay

• attempts (int) –

• jitter (Callable[[], float]) –

class pjrpc.client.retry.ExponentialBackoff(attempts, jitter=<function Backoff.<lambda>>, base=1.0, factor=2.0, max_value=None)

Bases: Backoff

Exponential request retry strategy.

Parameters:

• base (float) – exponentially growing delay base

• factor (float) – exponentially growing delay factor (multiplier)

• max_value (Optional[float]) – delay max value

• attempts (int) –

• jitter (Callable[[], float]) –

class pjrpc.client.retry.FibonacciBackoff(attempts, jitter=<function Backoff.<lambda>>, multiplier=1.0, max_value=1.0)

Bases: Backoff

Fibonacci request retry strategy.

Parameters:

• multiplier (float) – fibonacci interval sequence multiplier

• max_value (float) – delay max value

• attempts (int) –

• jitter (Callable[[], float]) –

class pjrpc.client.retry.RetryStrategy(backoff, codes=None, exceptions=None)

Bases: object

JSON-RPC request retry strategy.

Parameters:

• backoff (Backoff) – backoff delay generator

• codes (Optional[Set[int]]) – JSON-RPC response codes receiving which the request will be retried

• exceptions (Optional[Set[Type[Exception]]]) – exceptions catching which the request will be retried

pjrpc.client.retry.retry(func, retry_strategy)

Synchronous function retry decorator.

Parameters:

• func (Callable[[...], AbstractResponse]) – function to be retried

• retry_strategy (RetryStrategy) – retry strategy to be applied

Returns:

decorated function

Return type:

Callable[[…], AbstractResponse]

pjrpc.client.retry.retry_async(func, retry_strategy)

Asynchronous function retry decorator.

Parameters:

• func (Callable[[...], Awaitable[AbstractResponse]]) – function to be retried

• retry_strategy (RetryStrategy) – retry strategy to be applied

Returns:

decorated function

Return type:

Callable[[…], Awaitable[AbstractResponse]]

Integrations