Merge pull request #21 from eccenca/feature/pluginActions-CMEM-5576

seebi · web-flow · commit 12152eb00033 · 2025-03-05T16:30:24.000+01:00
Add plugin actions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,8 +8,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ### Added
 
-- Added `explicit_schema` parameter to `FlexibleOutputSchema` (CMEM-6444).
-
+- Custom actions for Workflow plugins (CMEM-5576).
+- Added explicit_schema parameter to FlexibleOutputSchema (CMEM-6444).
 
 ## [4.9.0] 2025-02-20
 
diff --git a/cmem_plugin_base/dataintegration/description.py b/cmem_plugin_base/dataintegration/description.py
@@ -9,7 +9,8 @@
 from pkgutil import get_data
 from typing import Any, ClassVar
 
-from cmem_plugin_base.dataintegration.plugins import TransformPlugin, WorkflowPlugin
+from cmem_plugin_base.dataintegration.context import PluginContext
+from cmem_plugin_base.dataintegration.plugins import PluginBase, TransformPlugin, WorkflowPlugin
 from cmem_plugin_base.dataintegration.types import (
     ParameterType,
     ParameterTypes,
@@ -96,6 +97,84 @@ def __init__(  # noqa: PLR0913
         self.visible = visible
 
 
+class PluginAction:
+    """Custom plugin action.
+
+    Plugin actions provide additional functionality besides the default execution.
+    They can be triggered from the plugin UI.
+    Each action is based on a method on the plugin class. Besides the self parameter,
+    the method can have one additional parameter of type PluginContext.
+    The return value of the method will be converted to a string and displayed in the UI.
+    The string may use Markdown formatting.
+    The method may return None, in which case no output will be displayed.
+    It may raise an exception to signal an error to the user.
+
+    :param name: The name of the method.
+    :param label: A human-readable label of the action
+    :param description: A human-readable description of the action
+    :param icon: An optional custom icon.
+    """
+
+    def __init__(self, name: str, label: str, description: str, icon: Icon | None = None):
+        self.name = name
+        self.label = label
+        self.description = description
+        self.icon = icon
+        self.validated = False
+        self.provide_plugin_context = False  # Will be set by validate()
+
+    def validate(self, plugin_class: type) -> None:
+        """Validate the action and set the `provide_plugin_context` boolean.
+
+        :param plugin_class: The plugin class
+        """
+        # Get the method from the class.
+        try:
+            method = getattr(plugin_class, self.name)
+        except AttributeError:
+            raise TypeError(
+                f"Plugin class '{plugin_class.__name__}' does not have a method named '{self.name}'"
+            ) from None
+        if not callable(method):
+            raise TypeError(f"'{self.name}' in class '{plugin_class.__name__}' is not a function.")
+
+        # Check parameters
+        parameters = list(inspect.signature(method).parameters.values())
+        if len(parameters) == 1:
+            self.provide_plugin_context = False
+        elif len(parameters) - 1 == 1:
+            if parameters[1].annotation is PluginContext:
+                self.provide_plugin_context = True
+            else:
+                raise TypeError(
+                    f"Argument of method '{self.name}' in {plugin_class.__name__} must "
+                    f"be typed PluginContext (it's {parameters[1].annotation})."
+                )
+        else:
+            raise TypeError(
+                f"Method '{self.name}' in {plugin_class.__name__} has more than one"
+                f" argument (besides 'self')."
+            )
+        self.validated = True
+
+    def execute(self, plugin: PluginBase, context: PluginContext) -> str | None:
+        """Call the action.
+
+        :param plugin: The plugin instance on which the action is called.
+        :param context: The plugin context
+        :return: The result of the action as string
+        """
+        if not self.validated:
+            raise ValueError("Action must be validated before it can be executed.")
+        if self.provide_plugin_context:
+            result = getattr(plugin, self.name)(context)
+        else:
+            result = getattr(plugin, self.name)()
+        if result is None:
+            return None
+        return str(result)
+
+
 class PluginDescription:
     """A plugin description.
 
@@ -106,6 +185,7 @@ class PluginDescription:
     :param categories: The categories to which this plugin belongs to.
     :param parameters: Available plugin parameters
     :param icon: An optional custom plugin icon.
+    :param actions: Custom plugin actions.
     """
 
     def __init__(  # noqa: PLR0913
@@ -118,6 +198,7 @@ def __init__(  # noqa: PLR0913
         categories: list[str] | None = None,
         parameters: list[PluginParameter] | None = None,
         icon: Icon | None = None,
+        actions: list[PluginAction] | None = None,
     ) -> None:
         #  Set the type of the plugin. Same as the class name of the plugin
         #  base class, e.g., 'WorkflowPlugin'.
@@ -153,6 +234,12 @@ def __init__(  # noqa: PLR0913
         else:
             self.parameters = parameters
         self.icon = icon
+        if actions is None:
+            self.actions = []
+        else:
+            self.actions = actions
+        for action in self.actions:
+            action.validate(plugin_class)
 
 
 @dataclass
@@ -233,6 +320,7 @@ class Plugin:
     :param categories: The categories to which this plugin belongs to.
     :param parameters: Available plugin parameters.
     :param icon: Optional custom plugin icon.
+    :param actions: Custom plugin actions
     """
 
     plugins: ClassVar[list[PluginDescription]] = []
@@ -246,12 +334,14 @@ def __init__(  # noqa: PLR0913
         categories: list[str] | None = None,
         parameters: list[PluginParameter] | None = None,
         icon: Icon | None = None,
+        actions: list[PluginAction] | None = None,
     ):
         self.label = label
         self.description = description
         self.documentation = documentation
         self.plugin_id = plugin_id
         self.icon = icon
+        self.actions = actions
         if categories is None:
             self.categories = []
         else:
@@ -272,6 +362,7 @@ def __call__(self, func: type):
             categories=self.categories,
             parameters=self.retrieve_parameters(func),
             icon=self.icon,
+            actions=self.actions,
         )
         Plugin.plugins.append(plugin_desc)
         return func
diff --git a/tests/test_description.py b/tests/test_description.py
@@ -3,21 +3,24 @@
 import unittest
 from collections.abc import Sequence
 
-from cmem_plugin_base.dataintegration.description import Plugin
-from cmem_plugin_base.dataintegration.plugins import TransformPlugin
+from cmem_plugin_base.dataintegration.context import ExecutionContext, PluginContext
+from cmem_plugin_base.dataintegration.description import Plugin, PluginAction
+from cmem_plugin_base.dataintegration.entity import Entities
+from cmem_plugin_base.dataintegration.plugins import TransformPlugin, WorkflowPlugin
 from cmem_plugin_base.dataintegration.types import (
     BoolParameterType,
     FloatParameterType,
     StringParameterType,
 )
+from cmem_plugin_base.testing import TestPluginContext
 
 
 class PluginTest(unittest.TestCase):
     """Plugin Test Class"""
 
     def test__basic_parameters(self) -> None:
         """Test basic parameters"""
-        Plugin.plugins = []
+        Plugin.plugins = []  # Remove all previous plugins
 
         @Plugin(label="My Transform Plugin")
         class MyTransformPlugin(TransformPlugin):
@@ -38,7 +41,6 @@ def __init__(
             def transform(self, inputs: Sequence[Sequence[str]]) -> Sequence[str]:
                 return []
 
-        _ = MyTransformPlugin
         plugin = Plugin.plugins[0]
 
         no_default_par = plugin.parameters[0]
@@ -61,6 +63,58 @@ def transform(self, inputs: Sequence[Sequence[str]]) -> Sequence[str]:
         assert bool_par.param_type.name == BoolParameterType.name
         assert bool_par.default_value is True
 
+    def test__actions(self) -> None:
+        """Test plugin actions"""
+        Plugin.plugins = []  # Remove all previous plugins
+
+        @Plugin(
+            label="My Workflow Plugin",
+            actions=[
+                PluginAction(
+                    name="get_name",
+                    label="Get name",
+                    description="Returns the supplied name",
+                ),
+                PluginAction(
+                    name="get_project",
+                    label="Get project",
+                    description="Returns the current project.",
+                ),
+            ],
+        )
+        class MyWorkflowPlugin(WorkflowPlugin):
+            """Test workflow plugin"""
+
+            def __init__(self, name: str) -> None:
+                self.name = name
+
+            def execute(self, inputs: Sequence[Entities], context: ExecutionContext) -> Entities:
+                return inputs[0]
+
+            def get_name(self) -> str:
+                return self.name
+
+            def get_project(self, context: PluginContext) -> str:
+                return context.project_id
+
+        # Get plugin description
+        plugin = Plugin.plugins[0]
+
+        # There should be two actions
+        assert len(plugin.actions) == 2
+        action1 = plugin.actions[0]
+        action2 = plugin.actions[1]
+
+        # Check first action
+        assert action1.name == "get_name"
+        assert action1.label == "Get name"
+        assert action1.description == "Returns the supplied name"
+
+        # Call actions on a plugin instance
+        plugin_instance = MyWorkflowPlugin("My Name")
+        assert action1.execute(plugin_instance, TestPluginContext()) == "My Name"
+        assert action2.execute(plugin_instance, TestPluginContext(project_id="movies")) == "movies"
+
 
 if __name__ == "__main__":
     unittest.main()
