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.
-
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
-
is_notification
¶ Returns
True
if the request is a notification e.g. id isNone
.
-
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
-
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.
-
result
¶ Response result. If the response has not succeeded raises an exception deserialized from the error field.
-
error
¶ Response error. If the response has succeeded returns
pjrpc.common.UNSET
.
-
is_success
¶ Returns
True
if the response has succeeded.
-
is_error
¶ Returns
True
if the response has not succeeded.
Returns the request related response object if the response has been received from the server otherwise returns
None
.
-
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
-
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
-
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.
-
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
-
is_notification
¶ Returns
True
if all the request in the batch are notifications.
-
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
-
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
-
error
¶ Response error. If the response has succeeded returns
pjrpc.common.UNSET
.
-
is_success
¶ Returns
True
if the response has succeeded.
-
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.
-
has_error
¶ Returns
True
if any response has an error.
-
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.
Returns the request related response object if the response has been received from the server otherwise returns
None
.
-
append
(response: pjrpc.common.v20.Response) → None¶ Appends a response to the batch.
-
extend
(responses: Iterable[pjrpc.common.v20.Response]) → None¶ Extends the batch with the responses.
-
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.
IdentityError
¶ Raised when a batch requests/responses identifiers are not unique or missing.
-
exception
pjrpc.common.exceptions.
DeserializationError
¶ Request/response deserializatoin error. Raised when request/response json has incorrect format.
-
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.
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
-
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
-
proxy
¶ Clint proxy object.
-
batch
¶ Client batch wrapper.
-
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
-
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
-
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_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
-
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
-
-
class
pjrpc.client.
Tracer
¶ JSON-RPC client tracer.
-
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
-
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
-
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.
Tracer
¶ JSON-RPC client tracer.
-
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
-
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
-
-
class
pjrpc.client.tracer.
LoggingTracer
(logger: logging.Logger = <RootLogger root (WARNING)>, level: int = 10)¶ JSON-RPC client logging tracer.
-
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
-
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
-
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
-
view
(view: Type[pjrpc.server.dispatcher.ViewMixin]) → None¶ Adds class based view to the registry.
Parameters: view – view to be added
-
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.
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 -
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
-
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
-
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
-
merge
(other: pjrpc.server.dispatcher.MethodRegistry) → None¶ Merges two registries.
Parameters: other – registry to be merged in the current one
-
-
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.-
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
-
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
-
-
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-
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
-
build_validation_schema
¶ Builds pydantic model based validation schema from method signature.
Parameters: signature – method signature to build schema for Returns: validation schema
-