bss
/
dr.botzo
1
0
Fork 0
Code Issues 1 Pull Requests Releases 2 Wiki Activity

ircbot: add load/unload plugin documentation

This commit is contained in:
Brian S. Stephan 2016-01-17 09:43:48 -06:00
parent 676f479d52
commit 10071f9094
1 changed files with 51 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
dr_botzo/ircbot/bot.py
View File

@ -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)