From 10071f90940f904735ed8f5f9da3bba569a7709c Mon Sep 17 00:00:00 2001 From: "Brian S. Stephan" Date: Sun, 17 Jan 2016 09:43:48 -0600 Subject: [PATCH] ircbot: add load/unload plugin documentation --- dr_botzo/ircbot/bot.py | 55 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/dr_botzo/ircbot/bot.py b/dr_botzo/ircbot/bot.py index 42bc64d..d5f0e26 100644 --- a/dr_botzo/ircbot/bot.py +++ b/dr_botzo/ircbot/bot.py @@ -576,7 +576,18 @@ class IRCBot(irc.client.SimpleIRCClient): pass def handle_load(self, connection, event, match): - """Handle IRC requests to load a plugin.""" + """Handle IRC requests to load a plugin. + + This loads a plugin, as requested, and the interpreter takes care of + loading dependencies. + + :param connection: connection for this load request + :type connection: LenientServerConnection + :param event: associated irc event object + :type event: Event + :param match: the matched regex (via add_global_regex_handler) + :type match: Match + """ has_perm = ircbotlib.has_permission(event.source, 'ircbot.manage_loaded_plugins') log.debug("has permission to load?: %s", str(has_perm)) @@ -588,7 +599,18 @@ class IRCBot(irc.client.SimpleIRCClient): def _load_plugin(self, connection, event, plugin_path, feedback=True): """Load an IRC plugin. - The general assumption here is that a plugin's init loads its hooks and handlers. + A plugin's init must initialize its hooks and handlers as references to this bot, this + is handed off but otherwise nothing is done with that here, this just loads it from a + Python sense. + + :param connection: connection for this load request + :type connection: LenientServerConnection + :param event: associated irc event object + :type event: Event + :param plugin_path: path (likely a relative one) of the plugin to attempt to load + :type plugin_path: str + :param feedback: whether or not to send messages to IRC regarding the load attempt + :type feedback: bool """ log.debug("trying to load plugin %s", plugin_path) @@ -641,7 +663,21 @@ class IRCBot(irc.client.SimpleIRCClient): log.debug(" %s", module_name) def handle_unload(self, connection, event, match): - """Handle IRC requests to unload a plugin.""" + """Handle IRC requests to unload a plugin. + + Unloading includes disconnecting the IRC plugin hooks, so this is the + way to "remove" a plugin from the IRC bot. Note that this only + removes the module for the specified plugin, not its dependencies, so + if you're trying to unload in order to refresh modules, this won't + do what you want. + + :param connection: connection for this unload request + :type connection: LenientServerConnection + :param event: associated irc event object + :type event: Event + :param match: the matched regex (via add_global_regex_handler) + :type match: Match + """ has_perm = ircbotlib.has_permission(event.source, 'ircbot.manage_loaded_plugins') log.debug("has permission to unload?: %s", str(has_perm)) @@ -651,7 +687,18 @@ class IRCBot(irc.client.SimpleIRCClient): self._unload_plugin(connection, event, plugin_path) def _unload_plugin(self, connection, event, plugin_path): - """Attempt to unload and del a module if it's loaded.""" + """Attempt to unload and del a module if it's loaded. + + This stops the plugin, which should (if it's coded properly) disconnect its + event handlers and kill threads and whatnot. + + :param connection: connection for this unload request + :type connection: LenientServerConnection + :param event: associated irc event object + :type event: Event + :param plugin_path: path (likely a relative one) of the plugin to attempt to unload + :type plugin_path: str + """ log.debug("trying to unload plugin %s", plugin_path)