Plugin

PluginDependencyHelper

sort_plugins_by_dependencies(plugin_names) classmethod

Sort plugins based on their capability dependencies using topological sorting.

Parameters:

Name	Type	Description	Default
plugin_names	list[str]	List of plugin names to sort	required

Returns:

Type	Description
list[str]	List of plugin names sorted in dependency order

Raises:

Type	Description
PluginDependencyCycleError	If there are circular dependencies
PluginDependencyMissingCapabilityError	If a required capability is not provided by any plugin

verify_plugin_dependencies(plugin_names) classmethod

Verify that all plugins have their dependencies satisfied.

Parameters:

Name	Type	Description	Default
plugin_names	list[str]	List of plugin names to verify	required

Returns:

Name	Type	Description
bool	bool	True if dependencies form a valid acyclic graph, False otherwise.

PluginInfo

Class representing information about a plugin.

Attributes:

Name	Type	Description
name		The name of the plugin.
plugin_type		The type of the plugin (e.g. WHITEBOX_PLUGIN, DJANGO_APP_PLUGIN, HYBRID_PLUGIN).
module		The module containing the plugin class, if applicable.
app_config		The Django app configuration for the plugin, if applicable.
is_loaded		A boolean indicating whether the plugin is loaded.

PluginManager

Singleton class for managing plugins.

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_django_app_plugins()

Get a list of all discovered Django app plugins.

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_by_name(name)

Get a plugin by its name.

Parameters:

Name	Type	Description	Default
name	str	The name of the plugin to retrieve.	required

Returns:

Type	Description
Plugin | None	The plugin instance if found, otherwise None.

get_plugin_for_capability(capability)

Get the plugin that provides the given capability.

get_plugin_info()

Get information about all discovered plugins.

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.

get_prepared_url_map()

Get the URL map 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

PluginType

Bases: Enum

Enum representing plugin types.

get_django_plugin_app_names()

Get the names of all Django app plugins.

get_django_plugin_app_urls()

Get the URLs of all Django app plugins.

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_event_map()

Return a mapping of event types to their corresponding handlers that the plugin contributes to the Whitebox plugin system.

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_model_classes_map()

Return a mapping of model classes that the plugin contributes to the Whitebox plugin system.

get_plugin_classes_map()

Return a mapping of plugin classes that the plugin contributes to the Whitebox plugin system.

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.

get_state_store_map()

Return a mapping of state stores to their corresponding JS file paths.

get_url_map()

Return a mapping of URL patterns that the plugin contributes to the Whitebox plugin system.

on_load()

This method is called when the plugin is loaded. It can be used to perform any initialization tasks that the plugin needs to perform when it is loaded into the Whitebox system, such as registering event callbacks.

on_unload()

This method is called when the plugin is unloaded. It can be used to perform any cleanup tasks that the plugin needs to perform when it is unloaded from the Whitebox system, such as unregistering event callbacks.

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}")