radioviz.tools.tool_discovery

Tool discovery utilities for RadioViz.

This module discovers Tool implementations via Python entry points and fallback built-ins. External developers can register tools using the “radioviz.tools” entry point group.

Functions

discover_tools([include_builtins, ...])

Discover and instantiate tools.
radioviz.tools.tool_discovery._instantiate_tool(obj: object, tools: list[ToolProtocol], seen_ids: set[str], source: str) → None[source]

Instantiate obj as a Tool and register it.

obj may be a concrete subclass of Tool or a callable factory that returns a Tool instance. The function ensures that the resulting tool has a unique tool_id; duplicates are ignored with a warning.

Parameters:

  • obj – The object to instantiate (class or factory).

  • tools – List to which a successfully instantiated tool is appended.

  • seen_ids – Set tracking already‑registered tool_id values.

  • source – Human‑readable description of the origin (used in warnings).

radioviz.tools.tool_discovery._iter_entry_points(group: str) → Iterable[EntryPoint][source]

Retrieve entry points for the specified group.

This helper abstracts the differences between the modern select API (available in Python 3.10+) and the legacy dict-based API, returning an iterable of importlib.metadata.EntryPoint objects.

Parameters:

group – The entry‑point group name (e.g. "radioviz.tools").

Returns:

An iterable of matching EntryPoint objects; empty if none.

radioviz.tools.tool_discovery._load_tool_from_ep(ep: EntryPoint, tools: list[ToolProtocol], seen_ids: set[str]) → None[source]

Load a tool from an entry point and add it to tools if valid.

The function attempts to import the object referenced by ep. On success, the object is passed to _instantiate_tool() for validation and registration. Errors during loading are reported via _warn().

Parameters:

  • ep – The entry point to load.

  • tools – The mutable list collecting instantiated tools.

  • seen_ids – Set of already‑registered tool identifiers to avoid duplicates.

radioviz.tools.tool_discovery._load_tool_from_path(path: str, tools: list[ToolProtocol], seen_ids: set[str]) → None[source]

Load a built‑in tool from a module:attribute path and add it to tools.

The function imports the specified module, retrieves the attribute, and forwards the resulting object to _instantiate_tool(). If the object is a subclass of Tool that has already been seen, the function returns early to avoid duplication.

Parameters:

  • path – String in the form "module.submodule:ClassName".

  • tools – The mutable list collecting instantiated tools.

  • seen_ids – Set of already‑registered tool identifiers.

radioviz.tools.tool_discovery._warn(message: str) → None[source]

Prints a message to the standard error.

This helper function is invoked during the tool loading phase and thus the normal error handling interface might be not yet ready.

radioviz.tools.tool_discovery.discover_tools(include_builtins: bool = True, include_entry_points: bool = True, progress_cb: Callable[[str, int, int], None] | None = None) → list[ToolProtocol][source]

Discover and instantiate tools.

Tools can be provided either as subclasses of Tool or as callables returning a Tool instance.

Parameters:

  • include_builtins – Whether to include built-in tools as fallback

  • include_entry_points – Whether to load entry-point tools

  • progress_cb – Optional callback invoked as tools are loaded

Returns:

List of instantiated tools

radioviz.tools.tool_discovery._BUILTIN_TOOL_PATHS = ['radioviz.tools.level_tool:LevelTool', 'radioviz.tools.profile_tool:ProfileTool', 'radioviz.tools.region_tool:RegionTool', 'radioviz.tools.measurement_tool:MeasurementTool', 'radioviz.tools.autocrop_tool:AutocropTool', 'radioviz.tools.manual_crop_tool:ManualCropTool', 'radioviz.tools.align_image_tool:AlignImageTool', 'radioviz.tools.flip_image_tool:FlipImageTool']

List of built-ins tools.