RPC items

The aiorpcx module defines some classes, instances of which will be returned by some of its APIs. You should not need to instantiate these objects directly.

An instance of one of these classes is called an item.

class aiorpcx.RPCRequest

An RPC request or notification that has been received, or an outgoing notification.

Outgoing requests are represented by RPCRequestOut objects.

method

The RPC method being invoked, a string.

If an incoming request is ill-formed, so that, e.g., its method could not be determined, then this will be an RPCError instance that describes the error.

args

The arguments passed to the RPC method. This is a list or a dictionary, a dictionary if the arguments were passed by parameter name.

request_id

The ID given to the request so that responses can be associated with requests. Normally an integer, or None if the request is a notification. Rarely it might be a floating point number or string.

is_notification()

Returns True if the request is a notification (its request_id is None), otherwise False.

class aiorpcx.RPCRequestOut

An outgoing RPC request that is not a notification. A subclass of RPCRequest and asyncio.Future.

When an outgoing request is created, typically via the send_request() method of a client or server session, you can specify a callback to be called when the request is done. The callback is passed the request object, and the result can be obtained via its result() method.

A request can also be await-ed. Currently the result of await-ing is the same as calling result() on the request but this may change in future.

class aiorpcx.RPCResponse

An incoming or outgoing response. Outgoing response objects are automatically created by the framework when a request handler returns its result.

result

The response result, a Python object. If an error occurred this will be an RPCError object describing the error.

request_id

The ID of the request this is a repsonse to. Notifications do not get responses so this will never be None.

If result in an RPCError their request_id attributes will match.

class aiorpcx.RPCError

Represents an error, either in an RPCResponse object if an error occurred processing a request, or in a RPCRequest if an incoming request was ill-formed.

message

The error message as a string.

code

The error code, an integer.

request_id

The ID of the request that gave an error if it could be determined, otherwise None.

class aiorpcx.RPCBatch

Represents an incoming or outgoing RPC response batch, or an incoming RPC request batch.

items

A list of the items in the batch. The list cannot be empty, and each item will be an RPCResponse object for a response batch, and an RPCRequest object for a request batch.

Notifications and requests can be mixed together.

Batches are iterable through their items, and taking their length returns the length of the items list.

requests()

A generator that yields non-notification items of a request batch, or each item for a response batch.

request_ids()

A frozenset of all request IDs in the batch, ignoring notifications.

is_request_batch()

Return True if the batch is a request batch.

class aiorpcx.RPCBatchOut

An outgoing RPC batch. A subclass of RPCBatch and asyncio.Future.

When an outgoing request batch is created, typically via the new_batch() method of a client or server session, you can specify a callback to be called when the batch is done. The callback is passed the batch object.

Each non-notification item in an RPCBatchOut object is itself an RPCRequestOut object that can be independently waited on or cancelled. Notification items are RPCRequest objects. Since batches are responded to as a whole, all member requests will be completed simultaneously. The order of callbacks of member requests, and of the batch itself, is unspecified.

Cancelling a batch, or calling its set_result() or set_exception() methods cancels all its requests.

add_request(method, args=None, on_done=None)

Add a request to the batch. A callback can be specified that will be called when the request completes. Returns the RPCRequestOut request that was added to the batch.

add_notification(method, args=None)

Add a notification to the batch.

RPC Protocol Classes

RPC protocol classes should inherit from RPCProtocolBase. The base class provides a few utility functions returning RPCError objects. The derived class should redefine some constant class attributes.

class aiorpcx.RPCProtocolBase

INTERNAL_ERROR

The integer error code to use for an internal error.

INVALID_ARGS

The integer error code to use when an RPC request passes invalid arguments.

INVALID_REQUEST

The integer error code to use when an RPC request is invalid.

METHOD_NOT_FOUND

The integer error code to use when an RPC request is for a non-existent method.

classmethod JSONRPC.internal_error(request_id)

Return an RPCError object with error code INTERNAL_ERROR for the given request ID. The error message will be "internal error processing request".

Parameters:request_id – the request ID, normally an integer or string Returns:the error object Return type:RPCError

classmethod JSONRPC.args_error(message)

Return an RPCError object with error code INVALID_ARGS with the given error message and a request ID of None.

Parameters:message (str) – the error message Returns:the error object Return type:RPCError

classmethod JSONRPC.invalid_request(message, request_id=None)

Return an RPCError object with error code INVALID_REQUEST with the given error message and request ID.

Parameters:

• message (str) – the error message
• request_id – the request ID, normally an integer or string

Returns:

the error object

Return type:

RPCError

classmethod JSONRPC.method_not_found(message)

Return an RPCError object with error code METHOD_NOT_FOUND with the given error message and a request ID None.

Parameters:message (str) – the error message Returns:the error object Return type:RPCError