Skip to content

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