Long Running Commands API

This module provides a convenience client API for invoking long running commands.

class LrcCallback(*args, **kwargs)

Expected LRC callback signature for typing.

The LrcCallback will be called with some combination of the following arguments:

• status: TaskStatus

• progress: int

• result: Any

• error: tuple[DevError]

Each of the above arguments is optional and the callback must check which are present by testing them for None. The callback cannot assume that only one argument will be provided per call.

It must accept a generic **kwargs parameter for forwards compatibility.

class LrcSubscriptions(command_id: str, unsubscribe_lrc_events: Callable[[], None], protocol_version: int)

LRC event subscriptions that is returned by invoke_lrc.

Unsubscribes from all events when the instance is deleted.

property command_id: str

The command ID.

Returns:

the command ID.

property protocol_version: int

The LRC client-server protocol version used.

Returns:

the protocol version.

invoke_lrc(lrc_callback: LrcCallback, proxy: DeviceProxy, command: str, command_args: tuple[Any] | None = None, logger: Logger | None = None) → LrcSubscriptions

Invoke a long running command (LRC) and monitor its progress with callbacks.

Subscribe to the relevant LRC attributes and inform the client about change events via the provided lrc_callback with either the status, progress, result or error.

Parameters:

• lrc_callback – Client LRC callback to call whenever the LRC’s state changes.

• proxy – Tango DeviceProxy.

• command – Name of command to invoke.

• command_args – Optional arguments for the command, defaults to None.

• logger – Logger to use for logging exceptions. If not provided, then a default module logger will be used.

Returns:

LrcSubscriptions class instance, containing the command ID. A reference to the instance must be kept until the command is completed or the client is not interested in its events anymore, as deleting the instance unsubscribes from the LRC change events and thus stops any further callbacks.

Raises:

• CommandError – If the command is rejected.

• ResultCodeError – If the command returns an unexpected result code.

• ValueError – If the lrc_callback does not accept **kwargs.

• RuntimeError – If the supported client-server protocol versions do not overlap.