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
-
static
-
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: Raises:
-
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
-