rpc.message

import rpc

Everything here is re-exported by rpc, so import rpc is enough and the names are called as rpc.*. Importing rpc.message on its own works too and reaches the same definitions.

The messages JSON-RPC 2.0 exchanges, a Request, a Notification and a Response, and turning them to and from JSON.

Every message is a JSON object whose jsonrpc member is the string '2.0'. A request names a method, may carry params, and has an id its response is matched to. A notification is a request without an id, and nothing answers it. A response carries the id of the request it answers and either a result or an error, never both. A message may also be a batch: a JSON array of messages sent and answered together.

Re-exported by rpc.

Functions

read()

rpc.read(value) -> Request|Notification|Response|list

Reads a value decoded from JSON as a message: a Request, a Notification or a Response.

A batch, a list, comes back as a list holding, for each of its entries in order, the message it holds or the RpcError saying why it does not hold one, so every entry can be answered on its own. An empty batch is not a message.

Parameters

• value (any) — A value as json.decode() returns it.

Returns Request|Notification|Response|list

Raises RpcError with code INVALID_REQUEST when value is not a message, or is an empty batch.

decode()

rpc.decode(text: string) -> Request|Notification|Response|list

Decodes the JSON text of a message, or of a batch, and reads it as read() does.

import rpc

var call = rpc.decode('{"jsonrpc": "2.0", "id": 7, "method": "ping"}')
echo call.method  # ping
echo call.id      # 7

Parameters

• text (string) — The message’s JSON text.

Returns Request|Notification|Response|list

Raises RpcError with code PARSE_ERROR when text is not valid JSON, or code INVALID_REQUEST when it is not a message.

encode()

rpc.encode(message) -> string

The JSON text of a message, or of a list of messages sent as a batch.

Parameters

• message (Request|Notification|Response|list)

Returns string

Classes

Request

class rpc.Request

A call that expects an answer: the method to run, its params, and the id the answer comes back with.

import rpc

var call = rpc.Request('add', [2, 3], 1)
echo rpc.encode(call)  # {"jsonrpc":"2.0","id":1,"method":"add","params":[2,3]}

• printable — has a @to_string(), so echo and print() show something useful

Constructor

rpc.Request(method: string, params, id)

Returns a new Request.

Parameters

• method (string) — The method to call.
• params (list|dict|nil) — Its parameters, by position as a list or by name as a dictionary; nil sends none.
• id (string|number) — What the answer will be matched by.

Raises ValueError when params is not a list, a dictionary or nil.

Request.to_dict()

rpc.Request.to_dict() -> dict

The request as the dictionary JSON-RPC sends.

Returns dict

Request.to_string()

rpc.Request.to_string() -> string

This request as Request(method #id).

Returns string

Notification

class rpc.Notification

A call that expects no answer: the method to run and its params. Nothing comes back from a notification, not even an error.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

rpc.Notification(method: string, params)

Returns a new Notification.

Parameters

• method (string) — The method to call.
• params (list|dict|nil) — Its parameters, by position as a list or by name as a dictionary; nil sends none.

Raises ValueError when params is not a list, a dictionary or nil.

Notification.to_dict()

rpc.Notification.to_dict() -> dict

The notification as the dictionary JSON-RPC sends.

Returns dict

Notification.to_string()

rpc.Notification.to_string() -> string

This notification as Notification(method).

Returns string

Response

class rpc.Response

The answer to a Request: its id, and either the result the method returned or the error it failed with.

The id is nil only for an answer to a message whose id could not be read, such as one that was not valid JSON.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

rpc.Response(id, result, error)

Returns a new Response. success() and failure() say which kind more plainly.

Parameters

• id (string|number|nil) — The id of the request answered.
• result (any) — What the method returned; ignored when error is given.
• error (?RpcError) — What the method failed with, or nil for a success.

Response.success()

rpc.Response.success(id, result) -> Response

A response answering request id with result.

Parameters

• id (string|number)
• result (any)

Returns Response

Response.failure()

rpc.Response.failure(id, error) -> Response

A response answering request id with error.

Parameters

• id (string|number|nil)
• error (RpcError)

Returns Response

Response.is_error()

rpc.Response.is_error() -> bool

True when the response carries an error rather than a result.

Returns bool

Response.to_dict()

rpc.Response.to_dict() -> dict

The response as the dictionary JSON-RPC sends.

Returns dict

Response.to_string()

rpc.Response.to_string() -> string

This response as Response(#id ok) or Response(#id error code).

Returns string

2026, Richard Ore and Zuri contributors