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

Bases: ABC

JSON-RPC 2.0 abstract request.

class pjrpc.common.AbstractResponse

Bases: ABC

JSON-RPC 2.0 abstract response.

class pjrpc.common.BatchRequest(*requests)

Bases: AbstractRequest

JSON-RPC 2.0 batch request.

Parameters:

requests (tuple[pjrpc.common.request.Request, ...]) – requests to be added to the batch

classmethod from_json(data, check_ids=True)

Deserializes a batch request from json data.

Parameters:

• data (Any) – data the request to be deserialized from

• check_ids (bool) – check response ids for uniqueness

Returns:

batch request object

Return type:

BatchRequest

to_json()

Serializes the request to json data.

Returns:

json data

Return type:

Any

property is_notification: bool

Returns True if all requests in the batch are notifications.

class pjrpc.common.BatchResponse(responses=UnsetType.UNSET, error=UnsetType.UNSET)

Bases: AbstractResponse

JSON-RPC 2.0 batch response.

Parameters:

• responses (Union[UnsetType, tuple[pjrpc.common.response.Response, ...]]) – responses to be added to the batch

• error (Union[UnsetType, JsonRpcError]) –

classmethod from_json(data, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>, check_ids=True)

Deserializes a batch response from json data.

Parameters:

• data (Any) – data the response to be deserialized from

• error_cls (type[pjrpc.common.exceptions.JsonRpcError]) – error class

• check_ids (bool) – check response ids for uniqueness

Returns:

batch response object

Return type:

BatchResponse

to_json()

Serializes the batch response to json data.

Returns:

json data

Return type:

Any

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 whole batch request failed, whereas has_error indicates that one of the requests in the batch failed.

property has_error: bool

Returns True if any response has an error.

unwrap_results()

Returns the batch result as a tuple. If any response of the batch has an error raises an exception related to the first errored response.

Return type:

tuple[Union[pjrpc.common.common.UnsetType, Any], …]

unwrap_result()

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

Return type:

Any

unwrap_error()

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

Return type:

JsonRpcError

pjrpc.common.DEFAULT_CONTENT_TYPE = 'application/json'

default JSON-RPC client/server content type

class pjrpc.common.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

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)

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 super().default(o)

Parameters:

o (Any) –

Return type:

Any

exception pjrpc.common.JsonRpcError(code, message, data=UnsetType.UNSET)

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.

Return type:

None

classmethod from_json(json_data)

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

Parameters:

json_data (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()

Serializes the error into a dict.

Returns:

serialized error

Return type:

Any

pjrpc.common.JsonT

alias of Any

class pjrpc.common.Request(method, params=None, id=None)

Bases: AbstractRequest

JSON-RPC 2.0 request.

Parameters:

• method (str) – method name

• params (Optional[Union[list[Union[str, int, float, bool, NoneType, list[Any], tuple[Any, ...], dict[str, Any]]], tuple[Union[str, int, float, bool, NoneType, list[Any], tuple[Any, ...], dict[str, Any]], ...], dict[str, Union[str, int, float, bool, NoneType, list[Any], tuple[Any, ...], dict[str, Any]]]]]) – method parameters

• id (Optional[Union[str, int]]) – request identifier

classmethod from_json(data)

Deserializes a request from json data.

Parameters:

data (Any) – data the request to be deserialized from

Returns:

request object

Raises:

pjrpc.common.exceptions.DeserializationError if format is incorrect

Return type:

Request

to_json()

Serializes the request to json data.

Returns:

json data

Return type:

Any

property is_notification: bool

Returns True if the request is a notification e.g. response will not be sent.

pjrpc.common.REQUEST_CONTENT_TYPES = ('application/json', 'application/json-rpc', 'application/jsonrequest')

allowed JSON-RPC server requests content types

class pjrpc.common.Response(id=None, result=UnsetType.UNSET, error=UnsetType.UNSET)

Bases: AbstractResponse

JSON-RPC 2.0 response.

Parameters:

• id (Optional[Union[str, int]]) – response identifier

• result (Union[UnsetType, Any]) – response result

• error (Union[UnsetType, JsonRpcError]) – response error

classmethod from_json(data, error_cls=<class 'pjrpc.common.exceptions.JsonRpcError'>)

Deserializes a response from json data.

Parameters:

• data (Any) – data the response to be deserialized from

• error_cls (type[pjrpc.common.exceptions.JsonRpcError]) – error class

Returns:

response object

Raises:

pjrpc.common.exceptions.DeserializationError if format is incorrect

Return type:

Response

property is_success: bool

Returns True if the response has succeeded.

property is_error: bool

Returns True if the response has not succeeded.

unwrap_result()

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

Return type:

Any

unwrap_error()

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

Return type:

JsonRpcError

to_json()

Serializes the response to json data.

Returns:

json data

Return type:

Any

pjrpc.common.RESPONSE_CONTENT_TYPES = ('application/json', 'application/json-rpc')

allowed JSON-RPC client responses content types

class pjrpc.common.UnsetType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Sentinel object. Used to distinct unset (missing) values from None ones.

Types

pjrpc.common.typedefs.JsonRpcParamsT

JSON-RPC parameters type

alias of Union[list[Union[str, int, float, bool, None, list[JsonT], tuple[JsonT, …], dict[str, JsonT]]], tuple[Union[str, int, float, bool, None, list[JsonT], tuple[JsonT, …], dict[str, JsonT]], …], dict[str, Union[str, int, float, bool, None, list[JsonT], tuple[JsonT, …], dict[str, JsonT]]]]

pjrpc.common.typedefs.JsonRpcRequestIdT

JSON-RPC identifier type

alias of Union[str, int]

pjrpc.common.typedefs.JsonT

JSON type

alias of Union[str, int, float, bool, None, list[JsonT], tuple[JsonT, …], dict[str, JsonT]]

Exceptions

Definition of package exceptions and JSON-RPC protocol errors.

exception pjrpc.common.exceptions.BaseError

Bases: Exception

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

exception pjrpc.common.exceptions.ProtocolError

Bases: BaseError

Raised when JSON-RPC protocol is violated.

exception pjrpc.common.exceptions.IdentityError

Bases: ProtocolError

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

exception pjrpc.common.exceptions.DeserializationError

Bases: ProtocolError, ValueError

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

exception pjrpc.common.exceptions.JsonRpcError(code, message, data=UnsetType.UNSET)

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.

Return type:

None

classmethod from_json(json_data)

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

Parameters:

json_data (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()

Serializes the error into a dict.

Returns:

serialized error

Return type:

Any

class pjrpc.common.exceptions.ParseError

Bases: object

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

class pjrpc.common.exceptions.InvalidRequestError

Bases: object

The JSON sent is not a valid request object.

class pjrpc.common.exceptions.MethodNotFoundError

Bases: object

The method does not exist / is not available.

class pjrpc.common.exceptions.InvalidParamsError

Bases: object

Invalid method parameter(s).

class pjrpc.common.exceptions.InternalError

Bases: object

Internal JSON-RPC error.

class pjrpc.common.exceptions.ServerError

Bases: object

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=1, step=1)

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)

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')

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()

UUID id generator. Returns random UUIDs.

Return type:

Generator[UUID, None, None]