mobly.snippet.callback_handler_base module¶

Module for the base class to handle Mobly Snippet Lib’s callback events.

class mobly.snippet.callback_handler_base.CallbackHandlerBase(callback_id, event_client, ret_value, method_name, device, rpc_max_timeout_sec, default_timeout_sec=120)[source]¶

Bases: ABC

Base class for handling Mobly Snippet Lib’s callback events.

All the events handled by a callback handler are originally triggered by one async RPC call. All the events are tagged with a callback_id specific to a call to an async RPC method defined on the server side.

The raw message representing an event looks like:

{
  'callbackId': <string, callbackId>,
  'name': <string, name of the event>,
  'time': <long, epoch time of when the event was created on the
    server side>,
  'data': <dict, extra data from the callback on the server side>
}

Each message is then used to create a CallbackEvent object on the client side.

ret_value¶: any, the direct return value of the async RPC call.

__init__(callback_id, event_client, ret_value, method_name, device, rpc_max_timeout_sec, default_timeout_sec=120)[source]¶

Initializes a callback handler base object.

Parameters:

callback_id – str, the callback ID which associates with a group of callback events.
event_client – SnippetClientV2, the client object used to send RPC to the server and receive response.
ret_value – any, the direct return value of the async RPC call.
method_name – str, the name of the executed Async snippet function.
device – DeviceController, the device object associated with this handler.
rpc_max_timeout_sec – float, maximum time for sending a single RPC call.
default_timeout_sec – float, the default timeout for this handler. It must be no longer than rpc_max_timeout_sec.

abstractmethod callEventGetAllRpc(callback_id, event_name)[source]¶

Calls snippet lib’s RPC to get all existing snippet events.

Override this method to use this class with various snippet lib implementations.

This function gets all existing events in the server with the specified identifier without waiting.

Parameters:

callback_id – str, the callback identifier.
event_name – str, the callback name.

Returns:

A list of event dictionaries.

abstractmethod callEventWaitAndGetRpc(callback_id, event_name, timeout_sec)[source]¶

Calls snippet lib’s RPC to wait for a callback event.

Override this method to use this class with various snippet lib implementations.

This function waits and gets a CallbackEvent with the specified identifier from the server. It will raise a timeout error if the expected event does not occur within the time limit.

Parameters:

callback_id – str, the callback identifier.
event_name – str, the callback name.
timeout_sec – float, the number of seconds to wait for the event. It is already checked that this argument is no longer than the max timeout of a single RPC.

Returns:

The event dictionary.

Raises:

errors.CallbackHandlerTimeoutError – Raised if the expected event does not occur within the time limit.

property callback_id¶: The callback ID which associates a group of callback events.

property default_timeout_sec¶: Default timeout used by this callback handler.

getAll(event_name)[source]¶

Gets all existing events in the server with the specified identifier.

This is a non-blocking call.

Parameters:: event_name – str, the name of the event to get.
Returns:: A list of CallbackEvent, each representing an event from the Server side.

property rpc_max_timeout_sec¶: Maximum time for sending a single RPC call.

waitAndGet(event_name, timeout=None)[source]¶

Waits and gets a CallbackEvent with the specified identifier.

It will raise a timeout error if the expected event does not occur within the time limit.

Parameters:

event_name – str, the name of the event to get.
timeout – float, the number of seconds to wait before giving up. If None, it will be set to self.default_timeout_sec.

Returns:

CallbackEvent, the oldest entry of the specified event.

Raises:

errors.CallbackHandlerBaseError – If the specified timeout is longer than the max timeout supported.
errors.CallbackHandlerTimeoutError – The expected event does not occur within the time limit.

waitForEvent(event_name, predicate, timeout=None, message=None)[source]¶

Waits for an event of the specific name that satisfies the predicate.

This call will block until the expected event has been received or time out.

The predicate function defines the condition the event is expected to satisfy. It takes an event and returns True if the condition is satisfied, False otherwise.

Note all events of the same name that are received but don’t satisfy the predicate will be discarded and not be available for further consumption.

Parameters:

event_name (str) – str, the name of the event to wait for.
predicate (Callable[[CallbackEvent], bool]) – function, the predicate used to test events.
timeout (float | None) – float, the number of seconds to wait before giving up. If None, it will be set to self.default_timeout_sec.
message (str | None) – str, an optional error message to include if there is a timeout.

Return type:

CallbackEvent

Returns:

CallbackEvent, the event that satisfies the predicate if received.

Raises:

errors.CallbackHandlerTimeoutError – raised if no event that satisfies the predicate is received after timeout seconds.