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 (itsrequest_id
isNone
), otherwiseFalse
.
-
-
class
aiorpcx.
RPCRequestOut
¶ An outgoing RPC request that is not a notification. A subclass of
RPCRequest
andasyncio.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 itsresult()
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 anRPCError
theirrequest_id
attributes will match.
-
-
class
aiorpcx.
RPCError
¶ Represents an error, either in an
RPCResponse
object if an error occurred processing a request, or in aRPCRequest
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 anRPCRequest
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
andasyncio.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 anRPCRequestOut
object that can be independently waited on or cancelled. Notification items areRPCRequest
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()
orset_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 codeINTERNAL_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 codeINVALID_ARGS
with the given error message and a request ID ofNone
.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 codeINVALID_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:
-