Common#

Misc#

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.AbstractRequest[source]#

Bases: ABC

JSON-RPC version 2.0 abstract request.

class pjrpc.common.AbstractResponse[source]#

Bases: ABC

JSON-RPC version 2.0 abstract response.

class pjrpc.common.Request(method, params=None, id=None)[source]#

Bases: AbstractRequest

JSON-RPC version 2.0 request.

Parameters:

method (str) – method name
params (Optional[JsonRpcParams]) – method parameters
id (Optional[JsonRpcRequestId]) – request identifier

classmethod from_json(json_data)[source]#

Deserializes a request from json data.

Parameters:: json_data (Optional[Union[List[Any], Tuple[Any, ...], Set[Any], Dict[str, Any]]]) – data the request to be deserialized from
Returns:: request object
Raises:: pjrpc.common.exceptions.DeserializationError if format is incorrect
Return type:: Request

property id: Optional[Union[str, int]]#: Request identifier.

property method: str#: Request method name.

property params: Optional[Union[List[Any], Tuple[Any, ...], Dict[str, Any]]]#: Request method parameters.

to_json()[source]#

Serializes the request to json data.

Returns:: json data
Return type:: Optional[Union[List[Any], Tuple[Any, …], Set[Any], Dict[str, Any]]]

property is_notification: bool#: Returns True if the request is a notification e.g. id is None.

class pjrpc.common.Response(id, result=UNSET, error=UNSET)[source]#

Bases: AbstractResponse

JSON-RPC version 2.0 response.

Parameters:

id (Optional[JsonRpcRequestId]) – response identifier
result (MaybeSet[Any]) – response result
error (MaybeSet[JsonRpcError]) – response error

classmethod from_json(json_data, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>)[source]#

Deserializes a response from json data.

Parameters:

json_data (Optional[Union[List[Any], Tuple[Any, ...], Set[Any], Dict[str, Any]]]) – data the response to be deserialized from
error_cls (Type[JsonRpcError]) – error class

Returns:

response object

Raises:

pjrpc.common.exceptions.DeserializationError if format is incorrect

Return type:

Response

property id: Optional[Union[str, int]]#: Response identifier.

property result: Any#: Response result. If the response has not succeeded raises an exception deserialized from the error field.

property error: Union[UnsetType, JsonRpcError]#: Response error. If the response has succeeded returns pjrpc.common.common.UNSET.

property is_success: bool#: Returns True if the response has succeeded.

property is_error: bool#: Returns True if the response has not succeeded.

property related: Optional[Request]#: Returns the request related response object if the response has been received from the server otherwise returns None.

get_error()[source]#

Returns error. If error is not set raises and exception.

Return type:: JsonRpcError

to_json()[source]#

Serializes the response to json data.

Returns:: json data
Return type:: Optional[Union[List[Any], Tuple[Any, …], Set[Any], Dict[str, Any]]]

class pjrpc.common.BatchRequest(*requests, strict=True)[source]#

Bases: AbstractRequest

JSON-RPC 2.0 batch request.

Parameters:

requests (Request) – requests to be added to the batch
strict (bool) – if True checks response identifier uniqueness

classmethod from_json(data)[source]#

Deserializes a batch request from json data.

Parameters:: data (Optional[Union[List[Any], Tuple[Any, ...], Set[Any], Dict[str, Any]]]) – data the request to be deserialized from
Returns:: batch request object
Return type:: BatchRequest

append(request)[source]#

Appends a request to the batch.

Parameters:: request (Request) –
Return type:: None

extend(requests)[source]#

Extends a batch with requests.

Parameters:: requests (Iterable[Request]) –
Return type:: None

to_json()[source]#

Serializes the request to json data.

Returns:: json data
Return type:: Optional[Union[List[Any], Tuple[Any, …], Set[Any], Dict[str, Any]]]

property is_notification: bool#: Returns True if all the request in the batch are notifications.

class pjrpc.common.BatchResponse(*responses, error=UNSET, strict=True)[source]#

Bases: AbstractResponse

JSON-RPC 2.0 batch response.

Parameters:

responses (Response) – responses to be added to the batch
strict (bool) – if True checks response identifier uniqueness
error (MaybeSet[JsonRpcError]) –

classmethod from_json(json_data, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>)[source]#

Deserializes a batch response from json data.

Parameters:

json_data (Optional[Union[List[Any], Tuple[Any, ...], Set[Any], Dict[str, Any]]]) – data the response to be deserialized from
error_cls (Type[JsonRpcError]) – error class

Returns:

batch response object

Return type:

BatchResponse

property error: Union[UnsetType, JsonRpcError]#: Response error. If the response has succeeded returns pjrpc.common.common.UNSET.

property is_success: bool#: Returns True if the response has succeeded.

property is_error: bool#: Returns True if the request has not succeeded. Note that it is not the same as pjrpc.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.

property has_error: bool#: Returns True if any response has an error.

property result: Tuple[Any, ...]#: Returns the batch result as a tuple. If any response of the batch has an error raises an exception of the first errored response.

property related: Optional[BatchRequest]#: Returns the request related response object if the response has been received from the server otherwise returns None.

get_error()[source]#

Returns error. If error is not set raises and exception.

Return type:: JsonRpcError

append(response)[source]#

Appends a response to the batch.

Parameters:: response (Response) –
Return type:: None

extend(responses)[source]#

Extends the batch with the responses.

Parameters:: responses (Iterable[Response]) –
Return type:: None

to_json()[source]#

Serializes the batch response to json data.

Returns:: json data
Return type:: Optional[Union[List[Any], Tuple[Any, …], Set[Any], Dict[str, Any]]]

class pjrpc.common.UnsetType[source]#

Bases: object

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)[source]#

Bases: JSONEncoder

Library default JSON encoder. Encodes request, response and error objects to be json serializable. All custom encoders should be inherited from it.

default(o)[source]#

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

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)

Parameters:: o (Any) –
Return type:: Any

pjrpc.common.DEFAULT_CONTENT_TYPE = 'application/json'#: default JSON-RPC client/server content type

pjrpc.common.REQUEST_CONTENT_TYPES = ('application/json', 'application/json-rpc', 'application/jsonrequest')#: allowed JSON-RPC server requests content types

pjrpc.common.RESPONSE_CONTENT_TYPES = ('application/json', 'application/json-rpc')#: allowed JSON-RPC client responses content types

pjrpc.common.set_default_content_type(content_type)[source]#

Sets default json-rpc client request / json-rpc server response content type.

Parameters:: content_type (str) –
Return type:: None

Types#

pjrpc.common.typedefs.JsonRpcParams#

JSON-RPC params type

alias of Union[List[Any], Tuple[Any, …], Dict[str, Any]]

pjrpc.common.typedefs.JsonRpcRequestId#

JSON-RPC identifier type

alias of Union[str, int]

pjrpc.common.typedefs.Json#

JSON type

alias of Optional[Union[List[Any], Tuple[Any, …], Set[Any], Dict[str, Any]]]

pjrpc.common.typedefs.MethodType#

Method type

alias of Callable[[…], Any]

pjrpc.common.typedefs.Func#

Function type

alias of TypeVar(‘Func’, bound=Callable[[…], Any])

Exceptions#

Definition of package exceptions and JSON-RPC protocol errors.

exception pjrpc.common.exceptions.BaseError[source]#

Bases: Exception

Base package error. All package errors are inherited from it.

exception pjrpc.common.exceptions.IdentityError[source]#

Bases: BaseError

Raised when a batch requests/responses identifiers are not unique or missing.

exception pjrpc.common.exceptions.DeserializationError[source]#

Bases: BaseError, ValueError

Request/response deserializatoin error. Raised when request/response json has incorrect format.

class pjrpc.common.exceptions.JsonRpcErrorMeta(name, bases, dct)[source]#

Bases: type

pjrpc.common.exceptions.JsonRpcError metaclass. Builds a mapping from an error code number to an error class inherited from a pjrpc.common.exceptions.JsonRpcError.

Parameters:

name (str) –
bases (Tuple[type, ...]) –
dct (Dict[str, Any]) –

Return type:

Type[JsonRpcError]

exception pjrpc.common.exceptions.JsonRpcError(code=None, message=None, data=UNSET)[source]#

Bases: BaseError

JSON-RPC protocol error. For more information see Error object. All JSON-RPC protocol errors are inherited from it.

Parameters:

code (int) – number that indicates the error type
message (str) – short description of the error
data (Union[UnsetType, Any]) – value that contains additional information about the error. May be omitted.

classmethod from_json(json_data)[source]#

Deserializes an error from json data. If data format is not correct ValueError is raised.

Parameters:: json_data (Optional[Union[List[Any], Tuple[Any, ...], Set[Any], Dict[str, Any]]]) – json data the error to be deserialized from
Returns:: deserialized error
Raises:: pjrpc.common.exceptions.DeserializationError if format is incorrect
Return type:: JsonRpcError

to_json()[source]#

Serializes the error to a dict.

Returns:: serialized error
Return type:: Optional[Union[List[Any], Tuple[Any, …], Set[Any], Dict[str, Any]]]

exception pjrpc.common.exceptions.ClientError(code=None, message=None, data=UNSET)[source]#

Bases: JsonRpcError

Raised when a client sent an incorrect request.

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

exception pjrpc.common.exceptions.ParseError(code=None, message=None, data=UNSET)[source]#

Bases: ClientError

Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

exception pjrpc.common.exceptions.InvalidRequestError(code=None, message=None, data=UNSET)[source]#

Bases: ClientError

The JSON sent is not a valid request object.

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

exception pjrpc.common.exceptions.MethodNotFoundError(code=None, message=None, data=UNSET)[source]#

Bases: ClientError

The method does not exist / is not available.

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

exception pjrpc.common.exceptions.InvalidParamsError(code=None, message=None, data=UNSET)[source]#

Bases: ClientError

Invalid method parameter(s).

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

exception pjrpc.common.exceptions.InternalError(code=None, message=None, data=UNSET)[source]#

Bases: JsonRpcError

Internal JSON-RPC error.

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

exception pjrpc.common.exceptions.ServerError(code=None, message=None, data=UNSET)[source]#

Bases: JsonRpcError

Reserved for implementation-defined server-errors. Codes from -32000 to -32099.

Parameters:

code (int) –
message (str) –
data (Union[UnsetType, Any]) –

Identifier generators#

Builtin request id generators. Implements several identifier types and generation strategies.

pjrpc.common.generators.sequential(start=1, step=1)[source]#

Sequential id generator. Returns consecutive values starting from start with step step.

Parameters:

start (int) – starting number
step (int) – step

Return type:

Generator[int, None, None]

pjrpc.common.generators.randint(a, b)[source]#

Random integer id generator. Returns random integers between a and b.

Parameters:

a (int) – from
b (int) – to

Return type:

Generator[int, None, None]

pjrpc.common.generators.random(length=8, chars='0123456789abcdefghijklmnopqrstuvwxyz')[source]#

Random string id generator. Returns random strings of length length using alphabet chars.

Parameters:

length (int) – string length
chars (str) – string characters

Return type:

Generator[str, None, None]

pjrpc.common.generators.uuid()[source]#

UUID id generator. Returns random UUIDs.

Return type:: Generator[UUID, None, None]