Convert MetaPluginInterface from Protocol to base class with default implementations

Author: elonen

organizer/basic_folders/organizer/metaplugin/loader.py

@@ -191,7 +191,14 @@ def call_extend_actions_hooks(self, actions: dict) -> dict:
                 continue
 
             try:
-                actions = plugin.extend_actions(actions)
+                result = plugin.extend_actions(actions)
+                if result is not None:
+                    actions = result
+                else:
+                    self.log.warning(
+                        f"Metaplugin {plugin.PLUGIN_NAME}.extend_actions() returned None - "
+                        "plugins must return the modified actions dict"
+                    )
             except Exception as e:
                 self.log.error(
                     f"Metaplugin {plugin.PLUGIN_NAME} failed in extend_actions: {e}",
@@ -258,9 +265,16 @@ async def call_augment_folder_listing_hooks(
                 continue
 
             try:
-                listing_items = await plugin.augment_folder_listing(
+                result = await plugin.augment_folder_listing(
                     listing_items, folder_context, session
                 )
+                if result is not None:
+                    listing_items = result
+                else:
+                    self.log.warning(
+                        f"Metaplugin {plugin.PLUGIN_NAME}.augment_folder_listing() returned None - "
+                        "plugins must return the modified listing_items list"
+                    )
             except Exception as e:
                 self.log.error(
                     f"Metaplugin {plugin.PLUGIN_NAME} failed in augment_folder_listing: {e}",
@@ -291,9 +305,16 @@ async def call_augment_listing_data_hooks(
                 continue
 
             try:
-                listing_data = await plugin.augment_listing_data(
+                result = await plugin.augment_listing_data(
                     listing_data, folder_context, session
                 )
+                if result is not None:
+                    listing_data = result
+                else:
+                    self.log.warning(
+                        f"Metaplugin {plugin.PLUGIN_NAME}.augment_listing_data() returned None - "
+                        "plugins must return the modified listing_data dict"
+                    )
             except Exception as e:
                 self.log.error(
                     f"Metaplugin {plugin.PLUGIN_NAME} failed in augment_listing_data: {e}",

organizer/basic_folders/organizer/metaplugin/types.py

@@ -14,7 +14,7 @@
 
 from dataclasses import dataclass
 from logging import Logger, LoggerAdapter
-from typing import Any, Optional, Protocol, TYPE_CHECKING
+from typing import Any, Optional, TYPE_CHECKING
 from sqlalchemy import orm
 
 from organizer.database.models import DbFolder
@@ -67,12 +67,16 @@ class OrganizerContext:
     """Helper for constructing UI pages"""
 
 
-class MetaPluginInterface(Protocol):
+class MetaPluginInterface:
     """
-    Protocol defining the metaplugin interface.
+    Base class for metaplugins.
 
-    Metaplugins should implement a `Plugin` class with these attributes and methods.
-    All methods are optional - metaplugins only need to implement the hooks they use.
+    Metaplugins should inherit from this class and override the hooks they need.
+    All methods have sensible defaults, so you only need to implement what you use.
+
+    Required attributes:
+        PLUGIN_NAME: str - Unique metaplugin identifier (e.g., "my_metaplugin")
+        PLUGIN_VERSION: str - Metaplugin version string (e.g., "1.0.0")
     """
 
     PLUGIN_NAME: str
@@ -96,7 +100,7 @@ async def on_init(self, context: OrganizerContext):
                 self.log = context.log
                 self.log.info(f"{self.PLUGIN_NAME} initialized")
         """
-        ...
+        pass
 
     async def on_shutdown(self) -> None:
         """
@@ -108,7 +112,7 @@ async def on_shutdown(self) -> None:
             async def on_shutdown(self):
                 self.log.info(f"{self.PLUGIN_NAME} shutting down")
         """
-        ...
+        pass
 
     def extend_actions(self, actions: dict[str, clap.ActionDef]) -> dict[str, clap.ActionDef]:
         """
@@ -138,7 +142,7 @@ def extend_actions(self, actions):
 
                 return actions
         """
-        ...
+        return actions
 
     async def handle_custom_command(
         self, cmd: str, args: dict[str, Any], session: org.UserSessionData, organizer: "OrganizerInbound"
@@ -173,7 +177,7 @@ async def handle_custom_command(self, cmd, args, session, organizer):
 
                 return True
         """
-        ...
+        return False
 
     async def augment_folder_listing(
         self, listing_items: list[clap.PageItemFolderListingItem], folder_context: "FolderContext", session: org.UserSessionData
@@ -206,7 +210,7 @@ async def augment_folder_listing(self, listing_items, folder_context, session):
 
                 return listing_items
         """
-        ...
+        return listing_items
 
     async def augment_listing_data(
         self, listing_data: dict[str, str], folder_context: "FolderContext", session: org.UserSessionData
@@ -231,7 +235,7 @@ async def augment_listing_data(self, listing_data, folder_context, session):
                 listing_data["folder_id"] = str(folder_context.folder.id)
                 return listing_data
         """
-        ...
+        return listing_data
 
     async def check_action_authorization(
         self,
@@ -270,4 +274,4 @@ async def check_action_authorization(self, action, folder, media_file, session):
                 # Use default checks for everything else
                 return None
         """
-        ...
+        return None