Remote procedure calls - mushroom.rpc

Engine

class mushroom.rpc.Engine(transport, rpc_handler)

Transport neutral message factory and mapper between requests and responses. This is the heart of all RPC handling.

handle_message(message)

Handle message received from the transport.

Parameters:message – message to be handled
next_message_id()

Generate the next message id for outbound messages.

Returns: the next message id

notify(method, data=None, **kwargs)

Send a notification.

Parameters:
  • method – name of the method to be called
  • data – data for the method being called
  • kwargs – transport specific arguments
request(method, data=None, timeout=None, **kwargs)

Send a request and wait for the response or timeout. If no response for the given method is received within timeout seconds a RequestTimeout exception is raised.

Parameters:
  • method – name of the method to be called
  • data – data for the method being called
  • timeout – timeout in seconds for this request
  • kwargs – transport specific arguments
send(message, **kwargs)

Hand message over to the transport.

Parameters:
  • message – message to be sent
  • kwargs – transport specific arguments

RPC handlers

class mushroom.rpc.MethodDispatcher(obj, prefix='rpc_', suffix='')

Dispatcher implementation that calls methods on an object with a specific prefix and/or suffix. This makes it possible to define objects that provides a set of methods which can then be called by the client.

Note: Using an empty prefix, _ or __ is highly discouraged as it allows the client to call methods like methods like __del__. The same holds true for the suffix. If you really want to dispatch methods without a prefix or suffix it is a good idea to write a custom dispatcher that implements some checks for this.

__call__(request)

The Engine calls the request handler like it was a function that takes the request as sole argument and returns the response. This function implements the adapter for this interface and makes it possible to use this class as handler for the Engine.

Parameters:request – request object
mushroom.rpc.dummy_rpc_handler(request)

Dummy RPC handler that raises a MethodNotFound exception for all calls. This is useful for applications that do not need do receive any data from the client but only publish data.

Exceptions

exception mushroom.rpc.RpcError(message='')

Base class for all exceptions raised from by the Engine.

exception mushroom.rpc.MethodNotFound(method_name)

This error is raised when a method for a Request or Notification message is not found. This can either happen when a connected client tries to call a server method or the server tries to call a method on the client side.

exception mushroom.rpc.RequestException(data)

This exception is raised when a Request message is answered with an Error message.

exception mushroom.rpc.RequestTimeout(message='')

This error is raised when a Request message is not answered within a specified timeout value. By default the value is set to infinite can be set do a different value when making the request.

Message classes

class mushroom.rpc.Message

Base class for all messages.

static from_list(l)

Parse a list as defined in the protocol into a message object.

Parameters:l – list to be parsed
class mushroom.rpc.Heartbeat(last_message_id)

Heartbeat message

code = 0
static from_list(l)

Parse list into a heartbeat message

Parameters:l – list to be parsed
to_list()

Serialize this message into a list

class mushroom.rpc.Notification(message_id, method, data=None)

Notification message

code = 1
static from_list(l)

Parse list into a notification message

Parameters:l – list to be parsed
to_list()

Serialize this message into a list

class mushroom.rpc.Request(message_id, method, data=None)

Request message

code = 2
static from_list(l)

Parse list into a request message

Parameters:l – list to be parsed
get_response(block=True, timeout=None)

Get response for this request.

Parameters:
  • block (bool) – block until response is available
  • timeout (int or None) – seconds to wait before raising a mushroom.rpc.RequestTimeout error
Return type:

mushroom.rpc.Response or mushroom.rpc.Error
Raises:

mushroom.rpc.RequestTimeout
response
to_list()
class mushroom.rpc.Response(message_id, request_message_id, data=None)

Response message

code = 3
static for_request(message_id, request, data=None)

Named constructor when the request is known. Some transports need the reference to the original request object when sending the reply for a request. Therefore the Engine generates all responses using this method.

Parameters:
  • request – the request which caused this response
  • data – response data of the method which was called
  • message_id – id of this message
static from_list(l)

Parse list into a response message

Parameters:l – list to be parsed
to_list()

Serialize this message into a list

class mushroom.rpc.Error(message_id, request_message_id, data=None)

Error message

This is the message class and not the exception. The RpcEngine will raise a RequestException upon receiving this message type.

code = 4
static for_request(message_id, request, data=None)

Named constructor when the request is known. Some transports need the reference to the original request object when sending the reply for a request. Therefore the RpcEngine generates all errors using this method.

Parameters:
  • request – the request which caused this response
  • data – response data of the method which was called
  • message_id – id of this message
static from_list(l)

Parse list into a error message

Parameters:l – list to be parsed
to_list()

Serialize this message into a list

class mushroom.rpc.Disconnect

Disconnect message

code = -1
static from_list(l)

Parse list into a disconnect message

Parameters:l – list to be parsed
to_list()

Serialize this message into a list