ss-tools/docs/plugin_dev.md

Plugin Development Guide

This guide explains how to create new plugins for the Superset Tools application.

1. Plugin Structure

A plugin is a single Python file located in the backend/src/plugins/ directory. Each plugin file must contain a class that inherits from PluginBase.

2. Implementing PluginBase

The PluginBase class is an abstract base class that defines the interface for all plugins. You must implement the following properties and methods:

• id: A unique string identifier for your plugin (e.g., "my-cool-plugin").
• name: A human-readable name for your plugin (e.g., "My Cool Plugin").
• description: A brief description of what your plugin does.
• version: The version of your plugin (e.g., "1.0.0").
• get_schema(): A method that returns a JSON schema dictionary defining the input parameters for your plugin. This schema is used to automatically generate a form in the frontend.
• execute(params: Dict[str, Any]): An async method that contains the main logic of your plugin. The params argument is a dictionary containing the input data from the user, validated against the schema you defined.

3. Example Plugin

Here is an example of a simple "Hello World" plugin:

# backend/src/plugins/hello.py
# [DEF:HelloWorldPlugin:Plugin]
# @SEMANTICS: hello, world, example, plugin
# @PURPOSE: A simple "Hello World" plugin example.
# @LAYER: Domain (Plugin)
# @RELATION: Inherits from PluginBase
# @PUBLIC_API: execute

from typing import Dict, Any
from ..core.plugin_base import PluginBase

class HelloWorldPlugin(PluginBase):
    @property
    def id(self) -> str:
        return "hello-world"

    @property
    def name(self) -> str:
        return "Hello World"

    @property
    def description(self) -> str:
        return "A simple plugin that prints a greeting."

    @property
    def version(self) -> str:
        return "1.0.0"

    def get_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "title": "Name",
                    "description": "The name to greet.",
                    "default": "World",
                }
            },
            "required": ["name"],
        }

    async def execute(self, params: Dict[str, Any]):
        name = params["name"]
        print(f"Hello, {name}!")

4. Logging

You can use the global logger instance to log messages from your plugin. The logger is available in the superset_tool.utils.logger module.

from superset_tool.utils.logger import SupersetLogger

logger = SupersetLogger()

async def execute(self, params: Dict[str, Any]):
    logger.info("My plugin is running!")

5. Testing

To test your plugin, simply run the application and navigate to the web UI. Your plugin should appear in the list of available tools.