feat(lab-3537): handle events as handlers for plugin (#1878)

florianlega · josselinbuils · web-flow · commit c399cfa62a53 · 2025-04-01T14:33:18.000+02:00
Co-authored-by: Josselin BUILS &lt;josselin.buils@gmail.com&gt;
diff --git a/src/kili/core/graphql/operations/plugin/mutations.py b/src/kili/core/graphql/operations/plugin/mutations.py
@@ -14,11 +14,13 @@
 
 GQL_CREATE_PLUGIN_RUNNER = """
 mutation(
+  $eventMatcher: [String!]
   $handlerTypes: [PluginHandlerType!]
   $pluginName: String!
   ) {
   data: createPluginRunner(
     data: {
+      eventMatcher: $eventMatcher
       handlerTypes: $handlerTypes
       pluginName: $pluginName
     }
@@ -28,13 +30,15 @@
 
 GQL_CREATE_WEBHOOK = """
 mutation(
+  $eventMatcher: [String!]
   $handlerTypes: [PluginHandlerType!]
   $pluginName: String!
   $webhookUrl: String!
   $header: String
   ) {
   data: createWebhook(
     data: {
+      eventMatcher: $eventMatcher
       handlerTypes: $handlerTypes
       header: $header
       pluginName: $pluginName
@@ -58,11 +62,13 @@
 
 GQL_UPDATE_PLUGIN_RUNNER = """
 mutation(
+  $eventMatcher: [String!]
   $handlerTypes: [PluginHandlerType!]
   $pluginName: String!
   ) {
   data: updatePluginRunner(
     data: {
+      eventMatcher: $eventMatcher
       handlerTypes: $handlerTypes
       pluginName: $pluginName
     }
@@ -72,13 +78,15 @@
 
 GQL_UPDATE_WEBHOOK = """
 mutation(
+  $eventMatcher: [String!]
   $handlerTypes: [PluginHandlerType!]
   $pluginName: String!
   $webhookUrl: String!
   $header: String
   ) {
   data: updateWebhook(
     data: {
+      eventMatcher: $eventMatcher
       handlerTypes: $handlerTypes
       header: $header
       pluginName: $pluginName
diff --git a/src/kili/entrypoints/mutations/plugins/__init__.py b/src/kili/entrypoints/mutations/plugins/__init__.py
@@ -26,6 +26,7 @@ def upload_plugin(
         plugin_path: Optional[str] = None,
         plugin_name: Optional[str] = None,
         verbose: bool = True,
+        event_matcher: Optional[List[str]] = None,
         **kwargs,  # pylint: disable=missing-param-doc
     ) -> LiteralString:
         """Uploads a plugin.
@@ -36,6 +37,7 @@ def upload_plugin(
                 - a folder containing a main.py (mandatory) and a requirements.txt (optional)
                 - a .py file
             plugin_name: name of your plugin, if not provided, it will be the name from your file
+            event_matcher: List of events for which the plugin should be called.
             verbose: If false, minimal logs are displayed
 
         Returns:
@@ -60,6 +62,7 @@ def upload_plugin(
             plugin_name,
             verbose,
             self.http_client,
+            event_matcher,
         ).create_plugin()
 
     @typechecked
@@ -70,6 +73,7 @@ def create_webhook(
         header: Optional[str] = None,
         verbose: bool = True,
         handler_types: Optional[List[str]] = None,
+        event_matcher: Optional[List[str]] = None,
     ) -> str:
         # pylint: disable=line-too-long,too-many-arguments
         """Create a webhook linked to Kili's events.
@@ -92,6 +96,7 @@ def create_webhook(
             handler_types: List of actions for which the webhook should be called.
                 Possible variants: `onSubmit`, `onReview`.
                 By default, is [`onSubmit`, `onReview`].
+            event_matcher: List of events for which the webhook should be called.
 
         Returns:
             A string which indicates if the mutation was successful,
@@ -107,6 +112,7 @@ def create_webhook(
             header,
             verbose,
             handler_types,
+            event_matcher,
         ).create_webhook()
 
     @typechecked
@@ -117,6 +123,7 @@ def update_webhook(
         new_header: Optional[str] = None,
         verbose: bool = True,
         handler_types: Optional[List[str]] = None,
+        event_matcher: Optional[List[str]] = None,
     ) -> str:
         # pylint: disable=line-too-long,too-many-arguments
         """Update a webhook linked to Kili's events.
@@ -131,6 +138,7 @@ def update_webhook(
             handler_types: List of actions for which the webhook should be called.
                 Possible variants: `onSubmit`, `onReview`.
                 By default, is [`onSubmit`, `onReview`]
+            event_matcher: List of events for which the webhook should be called.
 
         Returns:
             A string which indicates if the mutation was successful,
@@ -146,6 +154,7 @@ def update_webhook(
             new_header,
             verbose,
             handler_types,
+            event_matcher,
         ).update_webhook()
 
     @typechecked
@@ -203,6 +212,7 @@ def update_plugin(
         plugin_path: Optional[str] = None,
         plugin_name: Optional[str] = None,
         verbose: bool = True,
+        event_matcher: Optional[List[str]] = None,
         **kwargs,  # pylint: disable=missing-param-doc
     ) -> LiteralString:
         """Update a plugin with new code.
@@ -213,6 +223,7 @@ def update_plugin(
                 - a folder containing a main.py (mandatory) and a requirements.txt (optional)
                 - a .py file
             plugin_name: Name of the plugin
+            event_matcher: List of events names and/or globs for which the plugin should be called.
             verbose: If false, minimal logs are displayed
 
         Returns:
@@ -240,4 +251,5 @@ def update_plugin(
             plugin_name,
             verbose,
             self.http_client,
+            event_matcher,
         ).update_plugin()
diff --git a/src/kili/entrypoints/queries/plugins/__init__.py b/src/kili/entrypoints/queries/plugins/__init__.py
@@ -113,6 +113,7 @@ def get_plugin_status(
             plugin_name,
             verbose,
             self.http_client,
+            event_matcher=None,
         ).get_plugin_runner_status()
 
     @typechecked
diff --git a/src/kili/services/plugins/model.py b/src/kili/services/plugins/model.py
@@ -21,6 +21,7 @@ class PluginCore:
         on_custom_interface_click(self, label: Dict, asset_id: str)
         on_project_updated(self, settings_updated: List[Dict])
         on_send_back_to_queue(self, asset_id: str)
+        on_event(self, payload: Dict)
 
     !!! warning
         if using a custom init, be sure to call super().__init__()
@@ -192,3 +193,15 @@ def on_send_back_to_queue(self, asset_id: str):
         """
         # pylint: disable=unused-argument
         self.logger.warning("Handler is in active development.")
+
+    def on_event(
+        self,
+        payload: Dict,
+    ) -> None:
+        """Handler for all events, triggered when an event is triggered.
+
+        Args:
+            payload: Dict.
+        """
+        # pylint: disable=unused-argument
+        self.logger.warning("Method not implemented. Define a custom on_event on your plugin")
diff --git a/src/kili/services/plugins/upload.py b/src/kili/services/plugins/upload.py
@@ -74,8 +74,13 @@ def check_file_is_txt(path: Path, verbose: bool = True) -> bool:
     return check_file_mime_type(path, mime_extensions_for_txt_files, verbose)
 
 
-def check_file_contains_handler(path: Path) -> Tuple[bool, Optional[List[str]]]:
-    """Return true if the file contain PluginHandler Class."""
+def check_file_contains_handler(path: Path) -> Tuple[bool, Optional[List[str]], bool]:
+    """Test if the file is a python file with the right content.
+
+    Return true if the file contain PluginHandler Class.
+    Return the list of handlers or None if they are present in the file.
+    Return true if the file contains on_event method.
+    """
     with path.open(encoding="utf-8") as file:
         module = ast.parse(file.read())
     for node in module.body:
@@ -85,8 +90,12 @@ def check_file_contains_handler(path: Path) -> Tuple[bool, Optional[List[str]]]:
                 for child in node.body
                 if isinstance(child, ast.FunctionDef) and child.name in POSSIBLE_HANDLERS
             ]
-            return True, handlers
-    return False, None
+            has_on_event = any(
+                isinstance(child, ast.FunctionDef) and child.name == "on_event"
+                for child in node.body
+            )
+            return (True, handlers, has_on_event) if handlers else (True, None, has_on_event)
+    return False, None, False
 
 
 class WebhookUploader:
@@ -101,17 +110,20 @@ def __init__(
         header: Optional[str],
         verbose: bool,
         handler_types: Optional[List[str]],
+        event_matcher: Optional[List[str]],
     ) -> None:
         self.kili = kili
         self.webhook_url = webhook_url
         self.plugin_name = plugin_name or self.webhook_url
         self.header = header
         self.verbose = verbose
         self.handler_types = handler_types
+        self.event_matcher = event_matcher
 
     def create_webhook(self) -> str:
         """Create a webhook receiving Kili events."""
         variables = {
+            "eventMatcher": self.event_matcher,
             "handlerTypes": self.handler_types,
             "pluginName": self.plugin_name,
             "webhookUrl": self.webhook_url,
@@ -125,6 +137,7 @@ def create_webhook(self) -> str:
     def update_webhook(self) -> str:
         """Update a webhook receiving Kili events."""
         variables = {
+            "eventMatcher": self.event_matcher,
             "handlerTypes": self.handler_types,
             "pluginName": self.plugin_name,
             "webhookUrl": self.webhook_url,
@@ -147,10 +160,12 @@ def __init__(
         plugin_name: Optional[str],
         verbose: bool,
         http_client: HttpClient,
+        event_matcher: Optional[List[str]],
     ) -> None:
         self.kili = kili
         self.plugin_path = Path(plugin_path)
         self.http_client = http_client
+        self.event_matcher = event_matcher
 
         if (not self.plugin_path.is_dir()) and (not self.plugin_path.is_file()):
             raise FileNotFoundError(
@@ -173,10 +188,16 @@ def _retrieve_plugin_src(self) -> List[Path]:
                 raise FileNotFoundError(
                     f"No main.py file in the provided folder: {self.plugin_path.absolute()}"
                 )
-            contains_handler, handler_types = check_file_contains_handler(file_path)
+            contains_handler, handler_types, has_on_event = check_file_contains_handler(file_path)
             if not contains_handler:
                 raise ValueError("PluginHandler class is not present in your main.py file.")
 
+            if has_on_event and not self.event_matcher:
+                raise ValueError("Event matcher is required for plugins with on_event method.")
+
+            if handler_types and self.event_matcher:
+                raise ValueError("Cannot have both handler types and event matcher.")
+
             self.handler_types = handler_types
 
             return list(self.plugin_path.glob("**/*.py"))
@@ -186,10 +207,16 @@ def _retrieve_plugin_src(self) -> List[Path]:
         if not check_file_is_py(file_path, self.verbose):
             raise ValueError("Wrong file format.")
 
-        contains_handler, handler_types = check_file_contains_handler(file_path)
+        contains_handler, handler_types, has_on_event = check_file_contains_handler(file_path)
         if not contains_handler:
             raise ValueError("PluginHandler class is not present in your plugin file.")
 
+        if has_on_event and not self.event_matcher:
+            raise ValueError("Event matcher is required for plugins with on_event method.")
+
+        if handler_types and self.event_matcher:
+            raise ValueError("Cannot have both handler types and event matcher.")
+
         self.handler_types = handler_types
 
         return [file_path]
@@ -276,7 +303,11 @@ def _upload_script(self, is_updating_plugin: bool) -> None:
 
     def _create_plugin_runner(self) -> Any:
         """Create plugin's runner."""
-        variables = {"pluginName": self.plugin_name, "handlerTypes": self.handler_types}
+        variables = {
+            "pluginName": self.plugin_name,
+            "handlerTypes": self.handler_types,
+            "eventMatcher": self.event_matcher,
+        }
 
         result = self.kili.graphql_client.execute(GQL_CREATE_PLUGIN_RUNNER, variables)
         return self.kili.format_result("data", result)
@@ -345,7 +376,11 @@ def create_plugin(self):
 
     def _update_plugin_runner(self) -> Any:
         """Update plugin's runner."""
-        variables = {"pluginName": self.plugin_name, "handlerTypes": self.handler_types}
+        variables = {
+            "pluginName": self.plugin_name,
+            "handlerTypes": self.handler_types,
+            "eventMatcher": self.event_matcher,
+        }
 
         result = self.kili.graphql_client.execute(GQL_UPDATE_PLUGIN_RUNNER, variables)
         return self.kili.format_result("data", result)
diff --git a/tests/unit/services/plugins/test_plugins/handlers_correctly_implemented_events.py b/tests/unit/services/plugins/test_plugins/handlers_correctly_implemented_events.py
@@ -0,0 +1,8 @@
+from typing import Dict
+
+from kili.plugins import PluginCore
+
+
+class PluginHandler(PluginCore):
+    def on_event(self, payload: Dict) -> None:
+        super().on_event(payload=payload)
diff --git a/tests/unit/services/plugins/test_plugins/handlers_correctly_implemented_events_handlers.py b/tests/unit/services/plugins/test_plugins/handlers_correctly_implemented_events_handlers.py
@@ -0,0 +1,14 @@
+from typing import Dict
+
+from kili.plugins import PluginCore
+
+
+class PluginHandler(PluginCore):
+    def on_event(self, payload: Dict) -> None:
+        super().on_event(payload=payload)
+
+    def on_submit(self, label: Dict, asset_id: str) -> None:
+        super().on_submit(label=label, asset_id=asset_id)
+
+    def on_review(self, label: Dict, asset_id: str) -> None:
+        super().on_review(label=label, asset_id=asset_id)
diff --git a/tests/unit/services/plugins/test_unit_plugins.py b/tests/unit/services/plugins/test_unit_plugins.py
