# 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`