Plugin

PluginManager

Singleton class for managing plugins.

Attributes:

Name	Type	Description
plugins		A list of loaded plugins.
previously_discovered_plugins		A dictionary of previously discovered plugins.
_lock		A lock to ensure thread safety.

discover_plugins()

Unload or load plugins based on the discovered plugins.

emit_event(event_type, data=None) async

Propagate an event to all registered event callbacks.

Parameters:

Name	Type	Description	Default
event_type	str	The type of event to emit.	required
data	dict	The data associated with the event.	None

get_federation_config()

Get the federation configuration for all loaded plugins.

get_federation_integration_test_config()

Get the federation integration testing configuration for all loaded plugins.

get_federation_unit_test_config()

Get the federation unit testing configuration for all loaded plugins.

get_plugin_for_capability(capability)

Get the plugin that provides the given capability.

get_plugin_names()

Get the names of all loaded plugins.

get_plugins()

Get all loaded plugins.

get_prepared_bootstrap_assets()

Get the bootstrap assets for all loaded plugins.

register_event_callback(event_type, callback)

Register a callback for a specific event type.

Parameters:

Name	Type	Description	Default
event_type	str	The type of event to register the callback for.	required
callback	Callable	The callback function to be called when the event is emitted.	required

unregister_event_callback(event_type, callback)

Unregister a callback for a specific event type.

Parameters:

Name	Type	Description	Default
event_type	str	The type of event to unregister the callback for.	required
callback	Callable	The callback function to be removed.	required

Plugin

Bases: Protocol

This is the base class for all plugins. All plugins should adhere to this interface to ensure compatibility with whitebox.

Attributes:

Name	Type	Description
whitebox		Instance of the standard API wrapper provided by whitebox.
plugin_template	Optional[str]	Path to the template file for the plugin.
plugin_css	List[str]	List of paths to the CSS file(s) for the plugin.
plugin_js	List[str]	List of paths to the JavaScript file(s) for the plugin.
devices	List[str]	List of device classes that the plugin contributes to the device list.

get_bootstrap_assets()

Return a mapping of assets to be bootstrapped immediately on page load, that should be accessible globally. They are picked up from the [tool.whitebox-plugin.plugin] section's bootstrap-assets key in the plugin's pyproject.toml file.

Returns:

Name	Type	Description
dict	dict[str, list[str]]	A dictionary where the keys are the asset types (js and css are currently supported) and the values are lists of asset paths.

Example

Here's an example of how the returned dictionary might look, containing CSS and JS assets for a winter magic effect:

{
    "css": [
        "/static/whitebox_plugin_new_year/css/newyear.css",
    ],
    "js": [
        "/static/whitebox_plugin_new_year/js/newyear.js",
    ],
}

get_css()

Return the path to the CSS file(s) for the plugin.

get_device_classes()

Return the list of device classes that the plugin contributes to the device list.

get_exposed_component_map()

Return a mapping of exposed components by capability type to their corresponding component paths.

get_js()

Return the path to the JavaScript file(s) for the plugin.

get_provider_template(capability)

Return the path to the HTML template file for the provider of a specific capability, if it exists.

get_provider_template_context(capability)

Return the context to be passed to the provider template renderer.

get_slot_component_map()

Return a mapping of slots to their corresponding component paths.

WhiteboxStandardAPI

This class provides a standard API for plugins to interact with whitebox.

Attributes:

Name	Type	Description
api		Instance of the standard API provided by whitebox.

Methods:

Name	Description
register_event_callback	Register an event callback for a specific event type.

emit_event(event_type, data=None) async

Emit an event to all registered listeners.

Parameters:

Name	Type	Description	Default
event_type	str	The type of event to emit.	required
data	dict	The data to send with the event.	None

Example

import whitebox

class MyPlugin(whitebox.Plugin):
    def some_method(self):
        self.whitebox.emit_event("my_event", {"key": "value"})

register_event_callback(event_type, callback) staticmethod

Register an event callback for a specific event type. This allows a plugin to listen for events triggered by the

Parameters:

Name	Type	Description	Default
event_type	str	The type of event to listen for.	required
callback	Callable	The function to call when the event is triggered.	required

Example

import whitebox

class MyPlugin(whitebox.Plugin):
    def __init__(self):
        self.whitebox.register_event_callback("location_update", self.on_location_update)

    def on_location_update(data):
        print(f"location_update event received: {data}")

unregister_event_callback(event_type, callback)

Unregister an event callback for a specific event type.

Parameters:

Name	Type	Description	Default
event_type	str	The type of event to unregister the callback for.	required
callback	Callable	The callback function to be removed.	required

Example

import whitebox

class MyPlugin(whitebox.Plugin):
    def __init__(self):
        self.whitebox.unregister_event_callback("location_update", self.on_location_update)

    def on_location_update(data):
        print(f"location_update event received: {data}")