Developer Interface¶
Extensible JSON-RPC client/server library.
Common¶
Client and server common functions, types and classes that implements JSON-RPC protocol itself and agnostic to any transport protocol layer (http, socket, amqp) and server-side implementation.
-
class
pjrpc.common.
Request
(method: str, params: Union[list, dict, None] = None, id: Union[int, str, None] = None)¶ JSON-RPC version 2.0 request.
Parameters: - method – method name
- params – method parameters
- id – request identifier
-
classmethod
from_json
(json_data: Union[Json, str, int, float, dict, bool, list, tuple, set, None]) → pjrpc.common.v20.Request¶ Deserializes a request from json data.
Parameters: json_data – data the request to be deserialized from Returns: request object Raises: pjrpc.common.exception.DeserializationError
if format is incorrect
-
id
¶ Request identifier.
-
is_notification
¶ Returns
True
if the request is a notification e.g. id isNone
.
-
method
¶ Request method name.
-
params
¶ Request method parameters.
-
to_json
() → Union[Union[Json, str, int, float, dict, bool, list, tuple, set, None], str, int, float, dict, bool, list, tuple, set, None]¶ Serializes the request to json data.
Returns: json data
-
class
pjrpc.common.
Response
(id: Union[int, str, None], result: Union[pjrpc.common.common.UnsetType, Any] = UNSET, error: Union[pjrpc.common.common.UnsetType, pjrpc.common.exceptions.JsonRpcError] = UNSET)¶ JSON-RPC version 2.0 response.
Parameters: - id – response identifier
- result – response result
- error – response error
-
error
¶ Response error. If the response has succeeded returns
pjrpc.common.UNSET
.
-
classmethod
from_json
(json_data: Union[Json, str, int, float, dict, bool, list, tuple, set, None], error_cls: Type[pjrpc.common.exceptions.JsonRpcError] = <class 'pjrpc.common.exceptions.JsonRpcError'>) → pjrpc.common.v20.Response¶ Deserializes a response from json data.
Parameters: - json_data – data the response to be deserialized from
- error_cls – error class
Returns: response object
Raises: pjrpc.common.exception.DeserializationError
if format is incorrect
-
id
¶ Response identifier.
-
is_error
¶ Returns
True
if the response has not succeeded.
-
is_success
¶ Returns
True
if the response has succeeded.
Returns the request related response object if the response has been received from the server otherwise returns
None
.
-
result
¶ Response result. If the response has not succeeded raises an exception deserialized from the error field.
-
to_json
() → Union[Union[Json, str, int, float, dict, bool, list, tuple, set, None], str, int, float, dict, bool, list, tuple, set, None]¶ Serializes the response to json data.
Returns: json data
-
class
pjrpc.common.
BatchRequest
(*requests, strict: bool = True)¶ JSON-RPC 2.0 batch request.
Parameters: - requests – requests to be added to the batch
- strict – if
True
checks response identifier uniqueness
-
append
(request: pjrpc.common.v20.Request) → None¶ Appends a request to the batch.
-
extend
(requests: Iterable[pjrpc.common.v20.Request]) → None¶ Extends a batch with requests.
-
classmethod
from_json
(data: Union[Json, str, int, float, dict, bool, list, tuple, set, None]) → pjrpc.common.v20.BatchRequest¶ Deserializes a batch request from json data.
Parameters: data – data the request to be deserialized from Returns: batch request object
-
is_notification
¶ Returns
True
if all the request in the batch are notifications.
-
to_json
() → Union[Union[Json, str, int, float, dict, bool, list, tuple, set, None], str, int, float, dict, bool, list, tuple, set, None]¶ Serializes the request to json data.
Returns: json data
-
class
pjrpc.common.
BatchResponse
(*responses, error: Union[pjrpc.common.common.UnsetType, pjrpc.common.exceptions.JsonRpcError] = UNSET, strict: bool = True)¶ JSON-RPC 2.0 batch response.
Parameters: - responses – responses to be added to the batch
- strict – if
True
checks response identifier uniqueness
-
append
(response: pjrpc.common.v20.Response) → None¶ Appends a response to the batch.
-
error
¶ Response error. If the response has succeeded returns
pjrpc.common.UNSET
.
-
extend
(responses: Iterable[pjrpc.common.v20.Response]) → None¶ Extends the batch with the responses.
-
classmethod
from_json
(json_data: Union[Json, str, int, float, dict, bool, list, tuple, set, None], error_cls: Type[pjrpc.common.exceptions.JsonRpcError] = <class 'pjrpc.common.exceptions.JsonRpcError'>) → pjrpc.common.v20.BatchResponse¶ Deserializes a batch response from json data.
Parameters: - json_data – data the response to be deserialized from
- error_cls – error class
Returns: batch response object
-
has_error
¶ Returns
True
if any response has an error.
-
is_error
¶ Returns
True
if the request has not succeeded. Note that it is not the same aspjrpc.common.BatchResponse.has_error
. is_error indicates that the batch request failed at all, while has_error indicates that one of the requests in the batch failed.
-
is_success
¶ Returns
True
if the response has succeeded.
Returns the request related response object if the response has been received from the server otherwise returns
None
.
-
result
¶ Returns the batch result as a tuple. If any response of the batch has an error raises an exception of the first errored response.
-
to_json
() → Union[Union[Json, str, int, float, dict, bool, list, tuple, set, None], str, int, float, dict, bool, list, tuple, set, None]¶ Serializes the batch response to json data.
Returns: json data
-
class
pjrpc.common.
UnsetType
¶ Sentinel object. Used to distinct unset (missing) values from
None
ones.
-
class
pjrpc.common.
JSONEncoder
(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶ Library default JSON encoder. Encodes request, response and error objects to be json serializable. All custom encoders should be inherited from it.
-
default
(o: Any) → Any¶ Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return JSONEncoder.default(self, o)
-
Exceptions¶
Definition of package exceptions and JSON-RPC protocol errors.
-
exception
pjrpc.common.exceptions.
BaseError
¶ Base package error. All package errors are inherited from it.
-
exception
pjrpc.common.exceptions.
ClientError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ Raised when a client sent an incorrect request.
-
exception
pjrpc.common.exceptions.
DeserializationError
¶ Request/response deserializatoin error. Raised when request/response json has incorrect format.
-
exception
pjrpc.common.exceptions.
IdentityError
¶ Raised when a batch requests/responses identifiers are not unique or missing.
-
exception
pjrpc.common.exceptions.
InternalError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ Internal JSON-RPC error.
-
exception
pjrpc.common.exceptions.
InvalidParamsError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ Invalid method parameter(s).
-
exception
pjrpc.common.exceptions.
InvalidRequestError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ The JSON sent is not a valid request object.
-
exception
pjrpc.common.exceptions.
JsonRpcError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ JSON-RPC protocol error. For more information see Error object. All JSON-RPC protocol errors are inherited from it.
Parameters: - code – number that indicates the error type
- message – short description of the error
- data – value that contains additional information about the error. May be omitted.
-
classmethod
from_json
(json_data: Union[Json, str, int, float, dict, bool, list, tuple, set, None]) → pjrpc.common.exceptions.JsonRpcError¶ Deserializes an error from json data. If data format is not correct
ValueError
is raised.Parameters: json_data – json data the error to be deserialized from Returns: deserialized error Raises: pjrpc.common.exception.DeserializationError
if format is incorrect
-
to_json
() → Union[Union[Json, str, int, float, dict, bool, list, tuple, set, None], str, int, float, dict, bool, list, tuple, set, None]¶ Serializes the error to a dict.
Returns: serialized error
-
class
pjrpc.common.exceptions.
JsonRpcErrorMeta
¶ pjrpc.common.exceptions.JsonRpcError
metaclass. Builds a mapping from an error code number to an error class inherited from apjrpc.common.exceptions.JsonRpcError
.
-
exception
pjrpc.common.exceptions.
MethodNotFoundError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ The method does not exist / is not available.
-
exception
pjrpc.common.exceptions.
ParseError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-
exception
pjrpc.common.exceptions.
ServerError
(code: Optional[int] = None, message: Optional[str] = None, data: Union[pjrpc.common.common.UnsetType, Any] = UNSET)¶ Reserved for implementation-defined server-errors. Codes from -32000 to -32099.
Identifier generators¶
Builtin request id generators. Implements several identifier types and generation strategies.
-
pjrpc.common.generators.
randint
(a: int, b: int) → Generator[int, None, None]¶ Random integer id generator. Returns random integers between a and b.
-
pjrpc.common.generators.
random
(length: int = 8, chars: str = '0123456789abcdefghijklmnopqrstuvwxyz') → Generator[str, None, None]¶ Random string id generator. Returns random strings of length length using alphabet chars.
-
pjrpc.common.generators.
sequential
(start: int = 1, step: int = 1) → Generator[int, None, None]¶ Sequential id generator. Returns consecutive values starting from start with step step.
-
pjrpc.common.generators.
uuid
() → Generator[uuid.UUID, None, None]¶ UUID id generator. Returns random UUIDs.
Client¶
JSON-RPC client.
-
class
pjrpc.client.
AbstractClient
(request_class: Type[pjrpc.common.v20.Request] = <class 'pjrpc.common.v20.Request'>, response_class: Type[pjrpc.common.v20.Response] = <class 'pjrpc.common.v20.Response'>, batch_request_class: Type[pjrpc.common.v20.BatchRequest] = <class 'pjrpc.common.v20.BatchRequest'>, batch_response_class: Type[pjrpc.common.v20.BatchResponse] = <class 'pjrpc.common.v20.BatchResponse'>, error_cls: Type[pjrpc.common.exceptions.JsonRpcError] = <class 'pjrpc.common.exceptions.JsonRpcError'>, id_gen_impl: Callable[[...], Generator[Union[int, str], None, None]] = <function sequential>, json_loader: Callable = <function loads>, json_dumper: Callable = <function dumps>, json_encoder: Type[pjrpc.common.common.JSONEncoder] = <class 'pjrpc.common.common.JSONEncoder'>, json_decoder: Optional[json.decoder.JSONDecoder] = None, strict: bool = True, request_args: Optional[Dict[str, Any]] = None, tracers: Iterable[pjrpc.client.tracer.Tracer] = ())¶ Abstract JSON-RPC client.
Parameters: - request_class – request class
- response_class – response class
- batch_request_class – batch request class
- batch_response_class – batch response class
- id_gen_impl – identifier generator
- json_loader – json loader
- json_dumper – json dumper
- json_encoder – json encoder
- json_decoder – json decoder
- error_cls – JSON-RPC error base class
- strict – if
True
checks that a request and a response identifiers match
-
class
Proxy
(client: pjrpc.client.client.AbstractClient)¶ Proxy object. Provides syntactic sugar to make method call using dot notation.
Parameters: client – JSON-RPC client instance
-
batch
¶ Client batch wrapper.
-
call
(method: str, *args, _trace_ctx: types.SimpleNamespace = namespace(), **kwargs) → Optional[pjrpc.common.v20.Response]¶ Makes JSON-RPC call.
Parameters: - method – method name
- args – method positional arguments
- kwargs – method named arguments
- _trace_ctx – tracers request context
Returns: response result
-
notify
(method: str, *args, _trace_ctx=namespace(), **kwargs)¶ Makes a notification request
Parameters: - method – method name
- args – method positional arguments
- kwargs – method named arguments
- _trace_ctx – tracers request context
-
proxy
¶ Clint proxy object.
-
send
(request: pjrpc.common.v20.Request, _trace_ctx: types.SimpleNamespace = namespace(), **kwargs) → Optional[pjrpc.common.v20.Response]¶ Sends a JSON-RPC request.
Parameters: - request – request instance
- kwargs – additional client request argument
- _trace_ctx – tracers request context
Returns: response instance
-
class
pjrpc.client.
AbstractAsyncClient
(request_class: Type[pjrpc.common.v20.Request] = <class 'pjrpc.common.v20.Request'>, response_class: Type[pjrpc.common.v20.Response] = <class 'pjrpc.common.v20.Response'>, batch_request_class: Type[pjrpc.common.v20.BatchRequest] = <class 'pjrpc.common.v20.BatchRequest'>, batch_response_class: Type[pjrpc.common.v20.BatchResponse] = <class 'pjrpc.common.v20.BatchResponse'>, error_cls: Type[pjrpc.common.exceptions.JsonRpcError] = <class 'pjrpc.common.exceptions.JsonRpcError'>, id_gen_impl: Callable[[...], Generator[Union[int, str], None, None]] = <function sequential>, json_loader: Callable = <function loads>, json_dumper: Callable = <function dumps>, json_encoder: Type[pjrpc.common.common.JSONEncoder] = <class 'pjrpc.common.common.JSONEncoder'>, json_decoder: Optional[json.decoder.JSONDecoder] = None, strict: bool = True, request_args: Optional[Dict[str, Any]] = None, tracers: Iterable[pjrpc.client.tracer.Tracer] = ())¶ Abstract asynchronous JSON-RPC client.
-
batch
¶ Client batch wrapper.
-
call
(method: str, *args, _trace_ctx: types.SimpleNamespace = namespace(), **kwargs) → Any¶ Makes JSON-RPC call.
Parameters: - method – method name
- args – method positional arguments
- kwargs – method named arguments
- _trace_ctx – tracers request context
Returns: response result
-
send
(request: pjrpc.common.v20.Request, _trace_ctx: types.SimpleNamespace = namespace(), **kwargs) → Optional[pjrpc.common.v20.Response]¶ Sends a JSON-RPC request.
Parameters: - request – request instance
- kwargs – additional client request argument
- _trace_ctx – tracers request context
Returns: response instance
-
-
class
pjrpc.client.
LoggingTracer
(logger: logging.Logger = <RootLogger root (WARNING)>, level: int = 10)¶ JSON-RPC client logging tracer.
-
on_error
(trace_context: types.SimpleNamespace, request: Union[pjrpc.common.v20.Request, pjrpc.common.v20.BatchRequest], error: BaseException) → None¶ Handler called when JSON-RPC request failed.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- error – raised exception
-
on_request_begin
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request) → None¶ Handler called before JSON-RPC request begins.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
-
on_request_end
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request, response: pjrpc.common.v20.Response) → None¶ Handler called after JSON-RPC request ends.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- response – JSON-RPC response
-
-
class
pjrpc.client.
Tracer
¶ JSON-RPC client tracer.
-
on_error
(trace_context: types.SimpleNamespace, request: Union[pjrpc.common.v20.Request, pjrpc.common.v20.BatchRequest], error: BaseException) → None¶ Handler called when JSON-RPC request failed.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- error – raised exception
-
on_request_begin
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request) → None¶ Handler called before JSON-RPC request begins.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
-
on_request_end
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request, response: pjrpc.common.v20.Response) → None¶ Handler called after JSON-RPC request ends.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- response – JSON-RPC response
-
Backends¶
-
class
pjrpc.client.backend.requests.
Client
(url: str, session: Optional[requests.sessions.Session] = None, **kwargs)¶ Requests library client backend.
Parameters: - url – url to be used as JSON-RPC endpoint.
- session – custom session to be used instead of
requests.Session
- kwargs – parameters to be passed to
pjrpc.client.AbstractClient
-
close
() → None¶ Closes the current http session.
-
class
pjrpc.client.backend.aiohttp.
Client
(url: str, session_args: Optional[Dict[str, Any]] = None, session: Optional[aiohttp.client.ClientSession] = None, **kwargs)¶ Aiohttp library client backend.
Parameters: - url – url to be used as JSON-RPC endpoint
- session_args – additional
aiohttp.ClientSession
arguments - session – custom session to be used instead of
aiohttp.ClientSession
-
close
() → None¶ Closes current http session.
-
class
pjrpc.client.backend.kombu.
Client
(broker_url: str, queue_name: Optional[str] = None, conn_args: Optional[Dict[str, Any]] = None, exchange_name: Optional[str] = None, exchange_args: Optional[Dict[str, Any]] = None, routing_key: Optional[str] = None, result_queue_name: Optional[str] = None, result_queue_args: Optional[Dict[str, Any]] = None, **kwargs)¶ kombu based JSON-RPC client. Note: the client is not thread-safe.
Parameters: - broker_url – broker connection url
- conn_args – broker connection arguments.
- queue_name – queue name to publish requests to
- exchange_name – exchange to publish requests to. If
None
default exchange is used - exchange_args – exchange arguments
- routing_key – reply message routing key. If
None
queue name is used - result_queue_name – result queue name. If
None
random exclusive queue is declared for each request - conn_args – additional connection arguments
- kwargs – parameters to be passed to
pjrpc.client.AbstractClient
-
close
() → None¶ Closes the current broker connection.
-
class
pjrpc.client.backend.aio_pika.
Client
(broker_url: str, queue_name: Optional[str] = None, conn_args: Optional[Dict[str, Any]] = None, exchange_name: Optional[str] = None, exchange_args: Optional[Dict[str, Any]] = None, routing_key: Optional[str] = None, result_queue_name: Optional[str] = None, result_queue_args: Optional[Dict[str, Any]] = None, **kwargs)¶ aio_pika based JSON-RPC client.
Parameters: - broker_url – broker connection url
- conn_args – broker connection arguments.
- queue_name – queue name to publish requests to
- exchange_name – exchange to publish requests to. If
None
default exchange is used - exchange_args – exchange arguments
- routing_key – reply message routing key. If
None
queue name is used - result_queue_name – result queue name. If
None
random exclusive queue is declared for each request - conn_args – additional connection arguments
- kwargs – parameters to be passed to
pjrpc.client.AbstractClient
-
close
() → None¶ Closes current broker connection.
-
connect
() → None¶ Opens a connection to the broker.
Tracer¶
-
class
pjrpc.client.tracer.
LoggingTracer
(logger: logging.Logger = <RootLogger root (WARNING)>, level: int = 10)¶ JSON-RPC client logging tracer.
-
on_error
(trace_context: types.SimpleNamespace, request: Union[pjrpc.common.v20.Request, pjrpc.common.v20.BatchRequest], error: BaseException) → None¶ Handler called when JSON-RPC request failed.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- error – raised exception
-
on_request_begin
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request) → None¶ Handler called before JSON-RPC request begins.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
-
on_request_end
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request, response: pjrpc.common.v20.Response) → None¶ Handler called after JSON-RPC request ends.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- response – JSON-RPC response
-
-
class
pjrpc.client.tracer.
Tracer
¶ JSON-RPC client tracer.
-
on_error
(trace_context: types.SimpleNamespace, request: Union[pjrpc.common.v20.Request, pjrpc.common.v20.BatchRequest], error: BaseException) → None¶ Handler called when JSON-RPC request failed.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- error – raised exception
-
on_request_begin
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request) → None¶ Handler called before JSON-RPC request begins.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
-
on_request_end
(trace_context: types.SimpleNamespace, request: pjrpc.common.v20.Request, response: pjrpc.common.v20.Response) → None¶ Handler called after JSON-RPC request ends.
Parameters: - trace_context – request trace context
- request – JSON-RPC request
- response – JSON-RPC response
-
Integrations¶
Server¶
JSON-RPC server package.
-
class
pjrpc.server.
AsyncDispatcher
(*, request_class: Type[pjrpc.common.v20.Request] = <class 'pjrpc.common.v20.Request'>, response_class: Type[pjrpc.common.v20.Response] = <class 'pjrpc.common.v20.Response'>, batch_request: Type[pjrpc.common.v20.BatchRequest] = <class 'pjrpc.common.v20.BatchRequest'>, batch_response: Type[pjrpc.common.v20.BatchResponse] = <class 'pjrpc.common.v20.BatchResponse'>, json_loader: Callable = <function loads>, json_dumper: Callable = <function dumps>, json_encoder: Type[pjrpc.server.dispatcher.JSONEncoder] = <class 'pjrpc.server.dispatcher.JSONEncoder'>, json_decoder: Optional[Type[json.decoder.JSONDecoder]] = None, middlewares: Iterable[Callable] = ())¶ Asynchronous method dispatcher.
-
dispatch
(request_text: str, context: Optional[Any] = None) → Optional[str]¶ Deserializes request, dispatches it to the required method and serializes the result.
Parameters: - request_text – request text representation
- context – application context (if supported)
Returns: response text representation
-
-
class
pjrpc.server.
Dispatcher
(*, request_class: Type[pjrpc.common.v20.Request] = <class 'pjrpc.common.v20.Request'>, response_class: Type[pjrpc.common.v20.Response] = <class 'pjrpc.common.v20.Response'>, batch_request: Type[pjrpc.common.v20.BatchRequest] = <class 'pjrpc.common.v20.BatchRequest'>, batch_response: Type[pjrpc.common.v20.BatchResponse] = <class 'pjrpc.common.v20.BatchResponse'>, json_loader: Callable = <function loads>, json_dumper: Callable = <function dumps>, json_encoder: Type[pjrpc.server.dispatcher.JSONEncoder] = <class 'pjrpc.server.dispatcher.JSONEncoder'>, json_decoder: Optional[Type[json.decoder.JSONDecoder]] = None, middlewares: Iterable[Callable] = ())¶ Method dispatcher.
Parameters: - request_class – JSON-RPC request class
- response_class – JSON-RPC response class
- batch_request – JSON-RPC batch request class
- batch_response – JSON-RPC batch response class
- json_loader – request json loader
- json_dumper – response json dumper
- json_encoder – response json encoder
- json_decoder – request json decoder
-
add
(method: Callable, name: Optional[str] = None, context: Optional[Any] = None) → None¶ Adds method to the registry.
Parameters: - method – method
- name – method name
- context – application context name
-
add_methods
(*methods) → None¶ Adds methods to the registry.
Parameters: methods – method list. Each method may be an instance of pjrpc.server.MethodRegistry
,pjrpc.server.Method
or plain function
-
dispatch
(request_text: str, context: Optional[Any] = None) → Optional[str]¶ Deserializes request, dispatches it to the required method and serializes the result.
Parameters: - request_text – request text representation
- context – application context (if supported)
Returns: response text representation
-
view
(view: Type[pjrpc.server.dispatcher.ViewMixin]) → None¶ Adds class based view to the registry.
Parameters: view – view to be added
-
class
pjrpc.server.
JSONEncoder
(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶ Server JSON encoder. All custom server encoders should be inherited from it.
-
default
(o: Any) → Any¶ Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return JSONEncoder.default(self, o)
-
-
class
pjrpc.server.
Method
(method: Callable, name: Optional[str] = None, context: Optional[Any] = None)¶ JSON-RPC method wrapper. Stores method itself and some metainformation.
Parameters: - method – method
- name – method name
- context – context name
-
class
pjrpc.server.
MethodRegistry
(prefix: Optional[str] = None)¶ Method registry.
Parameters: prefix – method name prefix to be used for naming containing methods -
add
(maybe_method: Optional[Callable] = None, name: Optional[str] = None, context: Optional[Any] = None) → Callable¶ Decorator adding decorated method to the registry.
Parameters: - maybe_method – method or None
- name – method name to be used instead of __name__ attribute
- context – parameter name to be used as an application context
Returns: decorated method or decorator
-
add_methods
(*methods) → None¶ Adds methods to the registry.
Parameters: methods – methods to be added. Each one can be an instance of pjrpc.server.Method
or plain method
-
get
(item: str) → Optional[pjrpc.server.dispatcher.Method]¶ Returns a method from the registry by name.
Parameters: item – method name Returns: found method or None
-
merge
(other: pjrpc.server.dispatcher.MethodRegistry) → None¶ Merges two registries.
Parameters: other – registry to be merged in the current one
-
view
(maybe_view: Optional[Type[pjrpc.server.dispatcher.ViewMixin]] = None, context: Optional[Any] = None, prefix: Optional[str] = None) → Union[pjrpc.server.dispatcher.ViewMixin, Callable]¶ Methods view decorator.
Parameters: - maybe_view – view class instance or None
- context – application context name
- prefix – view methods prefix
Returns: decorator or decorated view
-
-
class
pjrpc.server.
ViewMixin
¶ Class based method handler mixin.
Integrations¶
aiohttp¶
aiohttp JSON-RPC server integration.
-
class
pjrpc.server.integration.aiohttp.
Application
(path: str = '', app: Optional[aiohttp.web_app.Application] = None, **kwargs)¶ aiohttp based JSON-RPC server.
Parameters: - path – JSON-RPC handler base path
- app_args – arguments to be passed to
aiohttp.web.Application
- kwargs – arguments to be passed to the dispatcher
pjrpc.server.AsyncDispatcher
-
app
¶ aiohttp application.
-
dispatcher
¶ JSON-RPC method dispatcher.
-
rpc_handle
(http_request: aiohttp.web_request.Request) → aiohttp.web_response.Response¶ Handles JSON-RPC request.
Parameters: http_request – aiohttp.web.Response
Returns: aiohttp.web.Request
flask¶
Flask JSON-RPC extension.
-
class
pjrpc.server.integration.flask.
JsonRPC
(path: str, **kwargs)¶ Flask framework JSON-RPC extension class.
Parameters: - path – JSON-RPC handler base path
- kwargs – arguments to be passed to the dispatcher
pjrpc.server.Dispatcher
-
dispatcher
¶ JSON-RPC method dispatcher.
-
init_app
(app: flask.app.Flask) → None¶ Initializes flask application with JSON-RPC extension.
Parameters: app – flask application instance
kombu¶
kombu JSON-RPC server integration.
-
class
pjrpc.server.integration.kombu.
Executor
(broker_url: str, queue_name: str, conn_args: Optional[Dict[str, Any]] = None, queue_args: Optional[Dict[str, Any]] = None, publish_args: Optional[Dict[str, Any]] = None, prefetch_count: int = 0, **kwargs)¶ kombu based JSON-RPC server.
Parameters: - broker_url – broker connection url
- queue_name – requests queue name
- conn_args – additional connection arguments
- queue_args – queue arguments
- publish_args – message publish additional arguments
- prefetch_count – worker prefetch count
- kwargs – dispatcher additional arguments
-
dispatcher
¶ JSON-RPC method dispatcher.
aio_pika¶
-
class
pjrpc.server.integration.aio_pika.
Executor
(broker_url: str, queue_name: str, prefetch_count: int = 0, **kwargs)¶ aio_pika based JSON-RPC server.
Parameters: - broker_url – broker connection url
- queue_name – requests queue name
- prefetch_count – worker prefetch count
- kwargs – dispatcher additional arguments
-
dispatcher
¶ JSON-RPC method dispatcher.
-
shutdown
() → None¶ Stops executor.
-
start
(queue_args: Optional[Dict[str, Any]] = None) → None¶ Starts executor.
Parameters: queue_args – queue arguments
werkzeug¶
-
class
pjrpc.server.integration.werkzeug.
JsonRPC
(path: str = '', **kwargs)¶ werkzeug server JSON-RPC integration.
Parameters: - path – JSON-RPC handler base path
- kwargs – arguments to be passed to the dispatcher
pjrpc.server.Dispatcher
-
dispatcher
¶ JSON-RPC method dispatcher.
Validators¶
JSON-RPC method parameters validators.
-
class
pjrpc.server.validators.
BaseValidator
¶ Base method parameters validator. Uses
inspect.signature()
for validation.-
bind
(signature: inspect.Signature, params: Union[list, dict, None]) → inspect.BoundArguments¶ Binds parameters to method. :param signature: method to bind parameters to :param params: parameters to be bound
Raises: ValidationError is parameters binding failed Returns: bound parameters
-
signature
¶ Returns method signature.
Parameters: - method – method to get signature of
- exclude – parameters to be excluded
Returns: signature
-
validate
(maybe_method: Optional[Callable] = None, **kwargs) → Callable¶ Decorator marks a method the parameters of which to be validated when calling it using JSON-RPC protocol.
Parameters: - maybe_method – method the parameters of which to be validated or
None
if called as @validate(…) - kwargs – validator arguments
- maybe_method – method the parameters of which to be validated or
-
validate_method
(method: Callable, params: Union[list, dict, None], exclude: Iterable[str] = (), **kwargs) → Dict[str, Any]¶ Validates params against method signature.
Parameters: - method – method to validate parameters against
- params – parameters to be validated
- exclude – parameter names to be excluded from validation
- kwargs – additional validator arguments
Raises: Returns: bound method parameters
-
-
exception
pjrpc.server.validators.
ValidationError
¶ Method parameters validation error. Raised when parameters validation failed.
jsonschema¶
-
class
pjrpc.server.validators.jsonschema.
JsonSchemaValidator
(**kwargs)¶ Parameters validator based on jsonschema library.
Parameters: kwargs – default jsonschema validator arguments -
validate_method
(method: Callable, params: Union[list, dict, None], exclude: Iterable[str] = (), **kwargs) → Dict[str, Any]¶ Validates params against method using
pydantic
validator.Parameters: - method – method to validate parameters against
- params – parameters to be validated
- exclude – parameter names to be excluded from validation
- kwargs – jsonschema validator arguments
Raises:
-
pydantic¶
-
class
pjrpc.server.validators.pydantic.
PydanticValidator
(coerce: bool = True, **config_args)¶ Parameters validator based on pydantic library. Uses python type annotations for parameters validation.
Parameters: coerce – if True
returns converted (coerced) parameters according to parameter type annotation otherwise returns parameters as is-
build_validation_schema
¶ Builds pydantic model based validation schema from method signature.
Parameters: signature – method signature to build schema for Returns: validation schema
-
validate_method
(method: Callable, params: Union[list, dict, None], exclude: Iterable[str] = (), **kwargs) → Dict[str, Any]¶ Validates params against method using
pydantic
validator.Parameters: - method – method to validate parameters against
- params – parameters to be validated
- exclude – parameter names to be excluded from validation
Returns: coerced parameters if coerce flag is
True
otherwise parameters as isRaises: ValidationError
-