penguin.plugin_manager module¶

plugin_manager.py - IGLOO Plugin Manager for Penguin

This module provides the IGLOOPluginManager and Plugin base class for the Penguin emulation environment.

It is responsible for:

Discovering, loading, and unloading plugin classes.
Managing plugin lifecycles and dependencies.
Providing a singleton plugins object for global plugin access.
Registering, subscribing, and publishing plugin events.
Supporting both legacy PyPlugin and new Plugin interfaces.
Providing utility functions for plugin name resolution and file discovery.

Arguments¶

panda (Panda): The Panda emulation object.
args (dict): Dictionary of arguments and configuration for plugins.

Plugin Interface¶

Plugins should subclass Plugin and will be automatically discovered and managed. Plugins can register, subscribe, and publish events using the plugins singleton:

plugins.register(plugin_instance, "event_name")
plugins.subscribe(other_plugin, "event_name", callback)
plugins.publish(plugin_instance, "event_name", *args, **kwargs)

Plugins can be loaded by name or class, and arguments can be passed via the plugin manager.

Overall Purpose¶

The plugin manager provides a flexible, extensible, and event-driven system for managing plugins in the Penguin emulation environment, enabling modular analysis, automation, and extension of the emulation workflow.

class penguin.plugin_manager.ArgsBox(args)[source]¶

Bases: object

Parameters:: args (Dict[str, Any])

args¶

get(key, default=None)[source]¶

Parameters:

key (str)
default (Any | None)

Return type:

Any

get_bool(key, default=False)[source]¶

Get a boolean argument value by name.

Parameters:

key (str) – The argument name.
default (bool) – Default value if the argument is not set.

Returns:

The argument value interpreted as a boolean.

Return type:

bool

class penguin.plugin_manager.IGLOOPluginManager[source]¶

Bases: object

Singleton class that manages the loading, unloading, and interaction with plugins.

Provides event registration, subscription, publishing, and plugin lifecycle management.

Return type:: IGLOOPluginManager

aliases: Dict[str, str]¶

get_arg(arg_name)[source]¶

Get an argument value by name.

Parameters:: arg_name (str) – The argument name.
Returns:: The argument value or None if not set.
Return type:: Any

get_arg_bool(arg_name, default=False)[source]¶

Returns True if the argument is set and has a truthy value.

Parameters:

arg_name (bool) – The name of the argument to retrieve.
default (bool) – The default value to return if the argument is not set.

Returns:

True if the argument exists and has a truthy value, False otherwise.

Return type:

bool

Raises:

ValueError – If the argument exists but has an unsupported type.

get_plugin_by_name(plugin_name)[source]¶

Retrieve a loaded plugin by name.

Parameters:: plugin_name (str) – Name of the plugin.
Returns:: The plugin instance if found, else None.
Return type:: Plugin or None

initialize(panda, args)[source]¶

Initialize the plugin manager with a Panda instance and arguments.

Parameters:

panda (Panda) – The Panda instance.
args (Dict[str, Any]) – Dictionary of arguments.

Return type:

None

instance = <penguin.plugin_manager.IGLOOPluginManager object>¶

load(pluginclasses, args=None)[source]¶

Load one or more plugin classes.

Parameters:

pluginclasses (Union[Type[T], List[Type[T]], Tuple[str, List[str]]]) – Plugin class(es) or (file, classnames) tuple.
args (Dict[str, Any], optional) – Arguments to pass to the plugins.

Return type:

None

load_all(plugin_file, args=None)[source]¶

Load all Plugin classes from a Python file. If no Plugin classes are found, load as ScriptingPlugin.

Parameters:

plugin_file (str) – Path to the Python file.
args (Optional[Dict[str, Any]]) – Arguments to pass to the Plugin.

Returns:

List of Plugin class names loaded from the file.

Return type:

List[str]

Raises:

ValueError – If the plugin file cannot be loaded.

load_plugin(plugin_name, extra_args=None)[source]¶

Load a plugin by name.

Parameters:

plugin_name (str) – Name of the plugin to load.
extra_args (Dict[str, Any] | None)

Raises:

ValueError – If plugin loading fails.

Return type:

None

load_plugins(conf_plugins)[source]¶

Load multiple plugins from a list of names.

Parameters:: conf_plugins (List[str]) – List of plugin names to load.
Return type:: None

plugin_cbs: Dict[Plugin, Dict[str, List[Callable]]]¶

plugins: Dict[str, Plugin]¶

portal_publish(plugin, event, *args, **kwargs)[source]¶

Publish an event to all registered callbacks for a plugin event, handling generators properly.

Parameters:

plugin (Plugin) – The plugin instance.
event (str) – Event name.
args (Any) – Positional arguments for callbacks.
kwargs (Any) – Keyword arguments for callbacks.

Return type:

Iterator

publish(plugin, event, *args, **kwargs)[source]¶

Publish an event to all registered callbacks for a plugin event.

Parameters:

plugin (Plugin) – The plugin instance.
event (str) – Event name.
args (Any) – Positional arguments for callbacks.
kwargs (Any) – Keyword arguments for callbacks.

Return type:

None

register(plugin, event, register_notify=None)[source]¶

Parameters:

plugin (Plugin) – The plugin instance.
event (str) – Event name.
register_notify (Callable, optional) – Optional callback for registration notification.

Return type:

None

registered_cbs: Dict[Tuple[Plugin, str], Callable]¶

property resources: str¶

Returns the path to the plugin resources directory.

Returns:: Path to the resources directory.
Return type:: str

subscribe(plugin, event, callback=None)[source]¶

Subscribe a callback to a plugin event. Can also be used as a decorator if callback is not provided.

Parameters:

plugin (Plugin) – The plugin instance.
event (str) – Event name.
callback (Callable, optional) – Callback function.

Return type:

Callable | None

Usage:

@plugins.subscribe(plugin, "event_name")
def handler(...):
    ...

# or

plugins.subscribe(plugin, "event_name", handler)

unload(pluginclass)[source]¶

Unload a plugin by class or name.

Parameters:: pluginclass (Union[Type[Plugin], Type[PyPlugin], str]) – Plugin class or name.
Raises:: ValueError – If the argument is not a loaded plugin.
Return type:: None

unload_all()[source]¶

Unload all loaded plugins in reverse order of load time.

Return type:: None

class penguin.plugin_manager.Plugin[source]¶

Bases: object

Base class for all IGLOO plugins.

Plugins should inherit from this class to be managed by the plugin manager. Provides argument access, logging, and Panda instance access.

get_arg(arg_name)[source]¶

Get an argument value by name.

Parameters:: arg_name (str) – The argument name.
Returns:: The argument value or None if not set.
Return type:: Any

get_arg_bool(arg_name, default=False)[source]¶

Returns True if the argument is set and has a truthy value.

Parameters:

arg_name (bool) – The name of the argument to retrieve.
default (bool) – The default value to return if the argument is not set.

Returns:

True if the argument exists and has a truthy value, False otherwise.

Return type:

bool

Raises:

ValueError – If the argument exists but has an unsupported type.

property name: str¶

Returns the name of this plugin, which is its class name.

Returns:: The class name of this plugin.
Return type:: str

class penguin.plugin_manager.ScriptingPlugin(*args, **kwargs)[source]¶

Bases: Plugin

A plugin that loads and executes a Python script as its __init__.

The script will have access to plugins and self (the plugin instance).

Parameters:

args (Any)
kwargs (Any)

property name: str¶

Returns the name of this plugin, which is its class name.

Returns:: The class name of this plugin.
Return type:: str

script: str | None = None¶

uninit()[source]¶

Uninitialize the plugin, if needed.

This method can be overridden by subclasses to perform cleanup.

Return type:: None

penguin.plugin_manager.camel_to_snake(name)[source]¶

Convert CamelCase to snake_case.

Parameters:: name (str) – The CamelCase string to convert
Returns:: The converted snake_case string
Return type:: str

penguin.plugin_manager.find_local_plugins(plugin_names, proj_dir)[source]¶

Find all local plugin files for a given list of plugin names.

Parameters:

plugin_names (List[str]) – List of plugin names to search for.
proj_dir (str) – The project directory.

Returns:

List of valid local file paths for the discovered plugins.

Return type:

List[str]

penguin.plugin_manager.find_plugin_by_name(plugin_name, proj_dir, plugin_path)[source]¶

Find a plugin file by name, trying various naming conventions.

Parameters:

plugin_name (str) – The name of the plugin to find
proj_dir (str) – The project directory
plugin_path (str) – The plugin path

Returns:

Tuple of (file_path, is_local_plugin)

Return type:

Tuple[str, bool]

Raises:

ValueError – If the plugin cannot be found

penguin.plugin_manager.gen_search_locations(plugin_name, proj_dir, plugin_path)[source]¶

Generate a list of possible file paths to look for a plugin.

Parameters:

plugin_name (str) – The name of the plugin to search for
proj_dir (str) – The project directory
plugin_path (str) – The plugin path

Returns:

List of possible file paths to search for the plugin

Return type:

List[str]

penguin.plugin_manager.interpret_bool(val)[source]¶

Interpret a value as a boolean, supporting bool, str, and int types.

Parameters:: val (Any) – The value to interpret.
Returns:: The interpreted boolean value.
Return type:: bool
Raises:: ValueError – If the value has an unsupported type.

penguin.plugin_manager.resolve_bound_method_from_class(f, manager=None)[source]¶

Resolve a method from a class given a function reference.

Parameters:

f (Callable) – The function reference to resolve.
manager (Any | None)

Returns:

The resolved method or the original function if not found.

Return type:

Callable

penguin.plugin_manager.snake_to_camel(name)[source]¶

Convert snake_case to CamelCase.

Parameters:: name (str) – The snake_case string to convert
Returns:: The converted CamelCase string
Return type:: str