Added a reload plugin method. /JL

README.md

@@ -1,5 +1,5 @@
 # XtendR
-![Latest Version](https://gitpot.lerk.ing/badges/badge/static?label=Latest+version&message=0.5.0&color=blue)
+![Latest Version](https://gitpot.lerk.ing/badges/badge/static?label=Latest+version&message=0.5.3&color=blue)
 
 A very basic Python 3.12 friendly plugin system based on the K.I.S.S principle.
 

plugins/example_plugin/example_plugin.py

@@ -37,3 +37,6 @@ class ExamplePlugin(XtendRBase):
     def pre_load(self, callback):
         time.sleep(5) # Indicate long running pre-load.
         callback()
+
+    def unload(self):
+        print("ExamplePlugin has unloaded!")  # release signal handlers, timers, widgets, etc. here

setup.py

@@ -6,7 +6,7 @@ if __name__ == "__main__":
 
     setup(
         name="XtendR",
-        version="0.5.0",
+        version="0.5.3",
         packages=find_packages(),
         install_requires=[],
         author="Jan Lerking",

xtendr/xtendrbase.py

@@ -2,19 +2,43 @@ from abc import ABC, abstractmethod
 
 class XtendRBase(ABC):
     """Abstract base class for all plugins.
-    
+
+    Lifecycle: pre_load() -> run() -> stop() -> unload(). XtendRSystem calls
+    unload() exactly once, right before it drops its own references to the
+    plugin instance and removes its module from sys.modules. This is the
+    plugin's only chance to release anything it holds that XtendRSystem
+    doesn't know about and can't clean up on its own, for example:
+
+    - GObject/GTK signal handler ids from .connect() (disconnect them, or
+      the GObject side keeps a reference to the bound method, which keeps
+      the plugin instance -- and everything it references -- alive).
+    - Widgets the plugin inserted into the app's widget tree (remove them
+      from their parent; a parented widget is kept alive by GTK regardless
+      of what Python does with its own references).
+    - GLib.timeout_add / idle_add source ids (GLib.source_remove them).
+    - Any threads it started that aren't daemon threads, or open files/
+      sockets/subprocesses.
+
+    unload() has a default no-op implementation so existing plugins that
+    don't hold any such resources keep working unchanged; override it only
+    when there's something to release.
+
     Example:
     >>> class TestPlugin(XtendRBase):
     ...     def run(self):
     ...         print("Running TestPlugin")
     ...     def stop(self):
     ...         print("Stopping TestPlugin")
+    ...     def unload(self):
+    ...         print("Unloading TestPlugin")
     
     >>> plugin = TestPlugin()
     >>> plugin.run()
     Running TestPlugin
     >>> plugin.stop()
     Stopping TestPlugin
+    >>> plugin.unload()
+    Unloading TestPlugin
     """
     @abstractmethod
     def run(self, *args, **kwargs):
@@ -27,4 +51,9 @@ class XtendRBase(ABC):
     @abstractmethod
     def pre_load(self, *args):
         pass
-        
+
+    def unload(self):
+        """Release any resources the plugin holds. Called once by
+        XtendRSystem.detach(), after stop(). Optional to override;
+        default is a no-op."""
+        pass

xtendr/xtendrsystem.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from xtendr.xtendrbase import XtendRBase
 from xtendr import signing as xsign
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 
 logger = logging.getLogger("xtendr")
 
@@ -37,7 +37,7 @@ class XtendRSystem:
     Example:
     >>> system = XtendRSystem()
     >>> system.version()
-    XtendR v0.5.0
+    XtendR v0.5.1
     >>> system.attach("example_plugin", lambda: None)
     >>> system.run("example_plugin")
     ExamplePlugin is running!
@@ -45,34 +45,43 @@ class XtendRSystem:
     ExamplePlugin has stopped!
     >>> system.detach("example_plugin")
     Detached plugin 'example_plugin'.
+
+    A system can be marked `protected=True` for plugins that must stay
+    attached for the lifetime of the process (e.g. an application's
+    built-ins). Protected systems still attach/run/stop normally; only
+    detach() is restricted, and only for ordinary callers -- detach(...,
+    force=True) and detach_all(..., force=True) remain available for the
+    host application's own shutdown path. There is deliberately no way to
+    force a single detach() without also opting in via the same keyword a
+    UI action would have to expose, so "not detachable by the user" is a
+    property of the call site, not of hidden state.
     """
 
-    def __init__(self, pluginpath="plugins", public_key_path=None, whitelist_path=None, whitelist_passphrase=None):
+    def __init__(self, pluginpath="plugins", public_key_path=None, whitelist_path=None,
+                 whitelist_passphrase=None, protected=False):
         self.pluginspath = pluginpath
         self.plugins = {}
+        self.protected = protected
         self._lock = threading.RLock()
 
         # -- signature verification setup ---------------------------------
+        # Paths are kept (not just the loaded key/whitelist objects) so
+        # reload() can re-read them from disk later -- e.g. after an admin
+        # re-signs a plugin or adds a whitelist entry for it -- without
+        # restarting the whole process.
+        #
         # If either the public key or the whitelist can't be loaded, we
         # fail closed: self._public_key / self._whitelist stay None, and
         # every plugin will come back as SIG_UNSIGNED (disabled) rather
         # than silently skipping verification. This is deliberate -- an
         # admin who wants unsigned plugins to run should not be able to
         # get there by accident (e.g. a missing/misspelled key path).
+        self._public_key_path = public_key_path
+        self._whitelist_path = whitelist_path
+        self._whitelist_passphrase = whitelist_passphrase
         self._public_key = None
         self._whitelist = None
-
-        if public_key_path is not None:
-            try:
-                self._public_key = xsign.load_public_key(Path(public_key_path))
-            except (OSError, ValueError) as e:
-                logger.error("Could not load XtendR public key from '%s': %s", public_key_path, e)
-
-        if whitelist_path is not None:
-            try:
-                self._whitelist = xsign.Whitelist.load(Path(whitelist_path), whitelist_passphrase)
-            except (OSError, ValueError) as e:
-                logger.error("Could not load XtendR plugin whitelist from '%s': %s", whitelist_path, e)
+        self._reload_verification_material()
 
         if self._public_key is None or self._whitelist is None:
             logger.warning(
@@ -81,6 +90,30 @@ class XtendRSystem:
                 pluginpath,
             )
 
+    def _reload_verification_material(self) -> None:
+        """(Re-)read the public key and whitelist from disk into
+        self._public_key / self._whitelist. Called once from __init__,
+        and again from reload() so a freshly-signed plugin or updated
+        whitelist can be picked up without restarting the process.
+
+        Fails closed on error, same as __init__ did: a key/whitelist
+        that can't be (re)loaded leaves that half of verification as
+        None rather than keeping around whatever was previously loaded.
+        """
+        self._public_key = None
+        if self._public_key_path is not None:
+            try:
+                self._public_key = xsign.load_public_key(Path(self._public_key_path))
+            except (OSError, ValueError) as e:
+                logger.error("Could not load XtendR public key from '%s': %s", self._public_key_path, e)
+
+        self._whitelist = None
+        if self._whitelist_path is not None:
+            try:
+                self._whitelist = xsign.Whitelist.load(Path(self._whitelist_path), self._whitelist_passphrase)
+            except (OSError, ValueError) as e:
+                logger.error("Could not load XtendR plugin whitelist from '%s': %s", self._whitelist_path, e)
+
     def version(self) -> str:
         return "XtendR v" + __version__
 
@@ -208,6 +241,7 @@ class XtendRSystem:
                     "module_key": None,
                     "disabled": True,
                     "signature": sig,
+                    "pre_load_thread": None,
                 }
                 return
 
@@ -244,6 +278,7 @@ class XtendRSystem:
                 "module_key": qualified_name,
                 "disabled": False,
                 "signature": sig,
+                "pre_load_thread": None,
             }
             logger.info("Attached plugin '%s'.", name)
             logger.info("Running pre-load on '%s'.", name)
@@ -255,45 +290,162 @@ class XtendRSystem:
                     logger.error("Plugin '%s' raised during pre_load.", name, exc_info=True)
 
             thread = threading.Thread(target=_pre_load_worker, daemon=True)
+            self.plugins[name]["pre_load_thread"] = thread
             thread.start()
 
+    def reload(self, name: str, callback=None) -> bool:
+        """Re-attempt attaching a plugin that's currently disabled due to
+        failed signature verification (SIG_UNSIGNED / SIG_INVALID) -- e.g.
+        after re-signing it or adding/fixing its whitelist entry.
+
+        This is specifically a recovery path for that one state, not a
+        general-purpose re-attach: a plugin that isn't currently attached,
+        or is attached but not disabled, is left alone and this returns
+        False without side effects.
+
+        The public key and whitelist are re-read from disk before
+        re-verifying -- __init__ only loads them once, so without this a
+        freshly-updated whitelist would never actually take effect and
+        reload() would just repeat the same failed check.
+
+        Returns True if the plugin ends up attached and enabled, False if
+        it's still disabled (or wasn't reloadable to begin with).
+        """
+        with self._lock:
+            entry = self.plugins.get(name)
+            if entry is None:
+                logger.error("Plugin '%s' is not attached; nothing to reload.", name)
+                return False
+            if not entry.get("disabled"):
+                logger.info("Plugin '%s' is not disabled; reload() is a no-op.", name)
+                return False
+            # Drop the disabled placeholder so attach() below doesn't just
+            # see 'already attached' and bail out immediately.
+            self.plugins.pop(name, None)
+
+        self._reload_verification_material()
+        self.attach(name, callback)
+
+        with self._lock:
+            entry = self.plugins.get(name)
+            return entry is not None and not entry.get("disabled")
+
     def run(self, name: str, *args, **kwargs):
         """Run the plugin's 'run' method if available."""
         with self._lock:
             entry = self.plugins.get(name)
-        if entry is None:
-            logger.error("Plugin '%s' not found or has no 'run' method.", name)
-            return
-        if entry.get("disabled"):
-            logger.error("Plugin '%s' is disabled (failed signature verification) and cannot run.", name)
-            return
-        entry["running"] = True
+            if entry is None:
+                logger.error("Plugin '%s' not found or has no 'run' method.", name)
+                return
+            if entry.get("disabled"):
+                logger.error("Plugin '%s' is disabled (failed signature verification) and cannot run.", name)
+                return
+            entry["running"] = True
+            instance = entry["instance"]
         try:
-            return entry["instance"].run(*args, **kwargs)
+            return instance.run(*args, **kwargs)
         except Exception:  # noqa: BLE001
             logger.error("Plugin '%s' raised during run.", name, exc_info=True)
-            entry["running"] = False
+            with self._lock:
+                entry["running"] = False
 
     def stop(self, name: str) -> None:
         """Stop the plugin if it's running."""
         with self._lock:
             entry = self.plugins.get(name)
-        if entry is None or not entry["running"]:
-            logger.info("Plugin '%s' is not running.", name)
-            return
-        entry["running"] = False
+            if entry is None or not entry["running"]:
+                logger.info("Plugin '%s' is not running.", name)
+                return
+            entry["running"] = False
+            instance = entry["instance"]
         try:
-            entry["instance"].stop()
+            instance.stop()
         except Exception:  # noqa: BLE001
             logger.error("Plugin '%s' raised during stop.", name, exc_info=True)
 
-    def detach(self, name: str) -> None:
-        """Unload a plugin."""
+    def detach(self, name: str, *, timeout: float = 5.0, force: bool = False) -> None:
+        """Unload a plugin: stop it if running, let it release its own
+        resources via unload(), then drop every reference XtendRSystem
+        holds to it (dict entry, sys.modules entry) so nothing outside the
+        plugin's own cleanup keeps it alive.
+
+        Protected systems (see __init__) refuse this unless force=True is
+        passed explicitly -- the caller has to opt in on purpose, so a
+        generic "detach" UI action wired up against this system can't
+        accidentally (or maliciously) unload a built-in.
+        """
+        if self.protected and not force:
+            logger.error(
+                "Refusing to detach '%s': this plugin system is protected "
+                "and cannot be detached from without force=True.", name,
+            )
+            return
+
         with self._lock:
             entry = self.plugins.pop(name, None)
             if entry is None:
                 logger.info("Plugin '%s' is not attached.", name)
                 return
-            if entry.get("module_key"):
-                sys.modules.pop(entry["module_key"], None)
-            logger.info("Detached plugin '%s'.", name)
+            was_running = entry["running"]
+            entry["running"] = False
+            instance = entry["instance"]
+            thread = entry.get("pre_load_thread")
+
+        # pre_load() may still be running in its own thread (e.g. detach
+        # called right after attach). Give it a bounded chance to finish
+        # before we call stop()/unload(), so a plugin doesn't get stopped
+        # out from under itself mid pre_load. If it doesn't finish in
+        # time we proceed anyway -- it's a daemon thread and holds its
+        # own reference to the instance, so this is a correctness/race
+        # concern rather than a leak.
+        if thread is not None and thread.is_alive():
+            thread.join(timeout)
+            if thread.is_alive():
+                logger.warning(
+                    "Plugin '%s' pre_load() did not finish within %.1fs; "
+                    "detaching anyway.", name, timeout,
+                )
+
+        if instance is not None:
+            if was_running:
+                try:
+                    instance.stop()
+                except Exception:  # noqa: BLE001
+                    logger.error("Plugin '%s' raised during stop.", name, exc_info=True)
+            try:
+                instance.unload()
+            except Exception:  # noqa: BLE001
+                logger.error("Plugin '%s' raised during unload.", name, exc_info=True)
+
+        if entry.get("module_key"):
+            sys.modules.pop(entry["module_key"], None)
+
+        # Drop our own strong references explicitly rather than letting
+        # them idle until this frame unwinds -- entry/instance are the
+        # last references XtendRSystem holds, so this makes the plugin
+        # object (and anything it exclusively owns) collectible the
+        # moment its unload() has actually let go of its own resources.
+        entry["instance"] = None
+        entry["pre_load_thread"] = None
+
+        logger.info("Detached plugin '%s'.", name)
+
+    def detach_all(self, *, force: bool = False) -> None:
+        """Detach every currently-attached plugin. Convenience for clean
+        shutdown; equivalent to calling detach() on every plugin name.
+
+        For a protected system this is a no-op unless force=True (see
+        detach()) -- shutdown code that genuinely needs to tear a
+        protected system down (e.g. the host application closing) passes
+        force=True explicitly; nothing else can.
+        """
+        if self.protected and not force:
+            logger.error(
+                "Refusing detach_all(): this plugin system is protected "
+                "and cannot be detached from without force=True."
+            )
+            return
+        with self._lock:
+            names = list(self.plugins.keys())
+        for name in names:
+            self.detach(name, force=force)