From e8e4b0bb4c9b98f64934cebcc3e4faff63b1f562 Mon Sep 17 00:00:00 2001 From: mathieui Date: Wed, 9 Nov 2011 18:38:56 +0100 Subject: Plugin docstrings --- src/events.py | 5 ++--- src/plugin.py | 27 ++++++++++++++++++++++++--- 2 files changed, 26 insertions(+), 6 deletions(-) (limited to 'src') diff --git a/src/events.py b/src/events.py index 22d60ddf..cd45448f 100644 --- a/src/events.py +++ b/src/events.py @@ -20,7 +20,6 @@ class EventHandler(object): """ def __init__(self): self.events = { - # when you are highlighted in a muc tab 'highlight': [], 'muc_say': [], 'conversation_say': [], @@ -35,7 +34,7 @@ class EventHandler(object): Add a callback to a given event. Note that if that event name doesn’t exist, it just returns False. If it was successfully added, it returns True - position: 0 means insert a the beginning, -1 means end + position: 0 means insert at the beginning, -1 means end """ if name not in self.events: return False @@ -49,7 +48,7 @@ class EventHandler(object): def trigger(self, name, *args, **kwargs): """ - Call all the callbacks associated to the given event name + Call all the callbacks associated to the given event name. """ callbacks = self.events[name] for callback in callbacks: diff --git a/src/plugin.py b/src/plugin.py index c87ba2f1..40f96871 100644 --- a/src/plugin.py +++ b/src/plugin.py @@ -50,9 +50,7 @@ class SafetyMetaclass(type): class BasePlugin(object, metaclass=SafetyMetaclass): """ - Class that all plugins derive from. Any methods beginning with command_ - are interpreted as a command and beginning with on_ are interpreted as - event handlers + Class that all plugins derive from. """ def __init__(self, plugin_manager, core, plugins_conf_dir): @@ -65,22 +63,45 @@ class BasePlugin(object, metaclass=SafetyMetaclass): self.init() def init(self): + """ + Method called at the creation of the plugin. + Do not overwrite __init__ and use this instead. + """ pass def cleanup(self): + """ + Called when the plugin is unloaded. + Overwrite this if you want to erase or save things before the plugin is disabled. + """ pass def unload(self): self.cleanup() def add_command(self, name, handler, help, completion=None): + """ + Add a global command. + You cannot overwrite the existing commands. + """ return self.plugin_manager.add_command(self.__module__, name, handler, help, completion) def del_command(self, name): + """ + Remove a global command. + This only works if the command was added by the plugin + """ return self.plugin_manager.del_command(self.__module__, name) def add_event_handler(self, event_name, handler, position=0): + """ + Add an event handler to the event event_name. + An optional position in the event handler list can be provided. + """ return self.plugin_manager.add_event_handler(self.__module__, event_name, handler, position) def del_event_handler(self, event_name, handler): + """ + Remove 'handler' from the event list for 'event_name'. + """ return self.plugin_manager.del_event_handler(self.__module__, event_name, handler) -- cgit v1.2.3