radioviz.tools.tool_api

Tool API module for RadioViz application.

This module provides the core API for implementing tools within the RadioViz application. It defines the base classes and interfaces that tools can use to interact with the application environment, manage sessions, and access various services such as window management, overlay rendering, and color handling.

The main components include: - BaseToolSession for managing tool execution lifecycle - ToolContext for providing application-facing APIs to tools

Classes

BaseToolSession(tool_controller, ...[, parent])	Base class for tool execution sessions.
ToolContext()	Application-facing API exposed to tools.
ToolSessionResult(session_id, payload)	Data class representing the result of a tool session execution.
WorkspaceRestoreContext()	Context manager for tracking tool sessions during workspace restoration.

class radioviz.tools.tool_api.BaseToolSession(tool_controller: T_Tool_Controller, window_controller: T_SubWindowController, parent: QObject | None = None)

Bases: QObject, Generic[T_Tool_Controller, T_SubWindowController]

Base class for tool execution sessions.

This class manages the lifecycle of a tool session, including starting, canceling, and finishing operations. It provides a common interface for tool implementations to handle their execution state.

Variables:

• finished – Signal emitted when the session finishes successfully

• canceled – Signal emitted when the session is canceled

Initialize a new tool session.

Parameters:

• tool_controller (ToolController) – The controller managing this tool session

• window_controller (SubWindowController[Any]) – The window controller associated with this session

• parent (QObject, optional) – Parent QObject for Qt ownership management

assign_payload(payload: Any) → None

Assign a payload to the tool session.

This method stores the provided payload which will be included in the session result when the session finishes.

Parameters:

payload (Any) – The data to be stored as the session’s result payload

cancel(reason: str = '') → None

Cancel the tool session.

If the session is not active, this method does nothing. Otherwise, it sets the session as inactive, calls the on_cancel method, and emits the canceled signal.

Parameters:

reason (str) – Reason for cancellation

finish() → None

Finish the tool session.

If the session is not active, this method does nothing. Otherwise, it sets the session as inactive, calls the on_finish method, and emits the finished signal.

is_active() → bool

Check if the session is currently active.

Returns:

True if the session is active, False otherwise

Return type:

bool

abstract on_cancel(reason: str) → None

Handle session cancellation event.

This method must be implemented by subclasses to define what happens when a session is cancelled.

Parameters:

reason (str) – Reason for cancellation

abstract on_finish() → None

Handle session finish event.

This method must be implemented by subclasses to define what happens when a session finishes.

abstract on_start() → None

Handle session start event.

This method must be implemented by subclasses to define what happens when a session starts.

start() → None

Start the tool session.

If the session is already active, this method does nothing. Otherwise, it sets the session as active and calls the on_start method.

class radioviz.tools.tool_api.ToolContext

Bases: QObject

Application-facing API exposed to tools.

This class provides a comprehensive API for tools to interact with the RadioViz application environment. It offers access to window management, overlay systems, color services, and other application-level features.

Variables:

message_requested – Signal emitted when a message needs to be shown

Initialize the tool context with application services.

_on_active_changed(image_controller: SubWindowController[Any] | None) → None

Internal handler for active window changes.

Parameters:

image_controller (SubWindowController[Any]) – The new active window controller

activate_image(window_controller: SubWindowController[Any]) → None

Activate a specific image window.

Parameters:

window_controller (SubWindowController[Any]) – The window controller to activate

active_image() → 'SubWindowController[Any]' | None

Get the currently active window controller.

Returns:

The active window controller or None if no window is active

Return type:

Union[SubWindowController[Any], None]

all_images() → list['SubWindowController[Any]']

Get a list of all available image windows.

Returns:

List of all image window controllers

Return type:

list[SubWindowController[Any]]

clear_active_tool(controller: ToolController[Any, Any]) → None

Clear the active tool if it matches the given controller.

Parameters:

controller (ToolController) – Tool controller to clear.

clear_tool_controllers() → None

Clear all registered tool controllers.

collect_dependency_counts(image_ids: list[UUID]) → dict[UUID, dict[str, int]]

Collect dependency counts for the specified image IDs.

Parameters:

image_ids (list[UUID]) – Image controller UUIDs to check

Returns:

Mapping of image_id to per-tool dependency counts

Return type:

dict[UUID, dict[str, int]]

get_color_service() → ColorService

Get the application’s color service.

Returns:

The color service instance

Return type:

ColorService

get_reference_by_id(obj_id: UUID) → object

Retrieve an object by its unique identifier from the workspace reference manager.

This method fetches an object that was previously registered with the given ID. If no object is found with the specified ID, this method will raise a KeyError.

Parameters:

obj_id (UUID) – The unique identifier of the object to retrieve

Returns:

The registered object

Return type:

object

iter_tool_controllers() → tuple['ToolController[Any, Any]', ...]

Return all registered tool controllers.

Returns:

A tuple of registered controllers

Return type:

tuple[ToolController, …]

on_active_image_changed(callback: Callable[[SubWindowController[Any] | None], None]) → None

Register a callback for active image change events.

Parameters:

callback (Callable) – Function to call when active image changes

on_list_changed(callback: Callable[[], None]) → None

Register a callback for window list change events.

Parameters:

callback (Callable) – Function to call when window list changes

register_new_overlay(overlay_type: str, overlay_role: OverlayRole, renderer: Callable[[OverlayModel, Axes], list[Artist]]) → None

Register a new overlay type with the application.

Parameters:

• overlay_type (str) – The identifier for the new overlay type

• overlay_role (OverlayRole) – The role this overlay plays

• renderer (RendererFn) – The renderer function for this overlay

register_new_window_type(kind: str, view_cls: type[SubWindowProtocol], overwrite: bool = False) → None

Register a new window type with the application.

Parameters:

• kind (str) – The identifier for the new window type

• view_cls (type[SubWindowProtocol]) – The window class to register

• overwrite (bool) – Whether to overwrite existing registration

register_tool_controller(controller: ToolController[Any, Any]) → None

Register a tool controller in this context.

Parameters:

controller (ToolController) – Tool controller instance

register_workspace_reference(obj_id: UUID, obj: object) → None

Register an object with a unique identifier in the workspace reference manager.

This method allows tools to store objects with a specific ID so they can be retrieved later using the ID. This is useful for maintaining references to objects across different tool sessions or operations.

Parameters:

• obj_id (UUID) – The unique identifier for the object

• obj (object) – The object to register

request_redraw() → None

Request a redraw of the active image window.

This method triggers a canvas update on the currently active image window.

request_tool_activation(controller: ToolController[Any, Any]) → None

Request activation of the given tool controller.

If another tool is active, it is deactivated before the new controller becomes active. This enforces a single active tool at any time.

Parameters:

controller (ToolController) – Tool controller requesting activation.

show_message(text: str, level: Literal['info', 'warning', 'error'], timeout_ms: int = 3000) → None

Show a message in the application UI.

Parameters:

• text (str) – The message text to display

• level (Literal['info', 'warning', 'error']) – The severity level of the message

• timeout_ms (int) – Timeout in milliseconds before message disappears

property active_tool_controller: ToolController[Any, Any] | None

Return the currently active tool controller.

Returns:

Active tool controller or None when no tool is active.

Return type:

ToolController | None

class radioviz.tools.tool_api.ToolSessionResult(session_id: UUID, payload: Any)

Bases: object

Data class representing the result of a tool session execution.

This class encapsulates the session identifier and the payload returned by a tool session upon completion. It serves as a container for communication between tool sessions and their callers.

Variables:

• session_id (UUID) – Unique identifier for the tool session

• payload (Any) – Result data returned by the tool session

class radioviz.tools.tool_api.WorkspaceRestoreContext

Bases: QObject

Context manager for tracking tool sessions during workspace restoration.

This class coordinates the restoration of multiple tool sessions by tracking their completion status. It ensures that a restoration process is only considered complete when all registered sessions have finished executing.

It also acts as a container for running sessions avoiding a session to be garbage collected when its variable goes out of scope.

Variables:

finished – Signal emitted when all tracked sessions have completed

Initialize the workspace restore context.

_on_session_finished(session_id: UUID) → None

Internal handler for session completion events.

This method removes a completed session from tracking and decrements the pending count. When all sessions are complete, it emits the finished signal.

Parameters:

session_id (UUID) – The unique identifier of the completed session

register_session(session: ToolSessionProtocol) → None

Register a new tool session for tracking.

This method adds a session to the tracking list and increments the pending count. The session will be monitored until it completes.

Parameters:

session (ToolSessionProtocol) – The tool session to register