# Plugin API documentation

## BasePlugin

class `plugin.``BasePlugin`(plugin_api, core, plugins_conf_dir)

  Class that all plugins derive from.

  `init`(self)

    Method called at the creation of the plugin.

    Do not override __init__ and use this instead.

  `cleanup`(self)

    Method called before the destruction of the plugin.

    Use it to erase or save things before the plugin is disabled.

  `core`

    The Poezio `Core` object. Use it carefully.

  `api`

    The `PluginAPI` instance for this plugin.

  `init`()

    Method called at the creation of the plugin.

    Do not overwrite __init__ and use this instead.

Each plugin inheriting `BasePlugin` has an `api` member variable, which refers to a `PluginAPI` object.

The `PluginAPI` object is an a interface through which the `BasePlugin` (and inheritors) should go to interact with poezio. If it is not sufficient, then the `core` member can be used.

## PluginAPI

class `plugin.``PluginAPI`(core, plugin_manager)

  The public API exposed to the plugins. Its goal is to limit the use of the raw Core object as much as possible.

  `add_command`(module, *args, **kwargs)

    Add a global command.

    Parameters:

    - name (str) – The name of the command (/name)
    - handler (function) – The function called when the command is run.
    - help (str) – The complete help for that command.
    - short (str) – A short description of the command.
    - completion (function) – The completion function for that command (optional)
    - usage (str) –

      A string showing the required and optional args of the command. Optional args should be surrounded by [] and mandatory args should be surrounded by <>.

      Example string: “<server> [port]”

    Raises Exception:
    | If the command already exists.

  `add_event_handler`(module, *args, **kwargs)

    Add an event handler for a poezio event.

    Parameters:

    - event_name (str) – The event name.
    - handler (function) – The handler function.
    - position (int) – The position of that handler in the handler list. This is useful for plugins like GPG or OTR, which must be the last function called on the text. Defaults to 0.

    A complete list of those events can be found at http://poezio.eu/doc/en/dev/events.html

  `add_key`(module, *args, **kwargs)

    Associate a global binding to a handler.

    Parameters:

    - key (str) – The curses representation of the binding.
    - handler (function) – The function called when the binding is pressed.

    Raises Exception:
    | If the binding is already present.

  `add_slix_event_handler`(module, event_name, handler)

    Add an event handler for a slixmpp event.

    Parameters:

    - event_name (str) – The event name.
    - handler (function) – The handler function.

    A list of the slixmpp events can be found here http://sleekxmpp.com/event_index.html

  `add_tab_command`(module, *args, **kwargs)

    Add a command to only one type of tab.

    Parameters:

    - tab_type (tabs.Tab) – The type of Tab to target.
    - name (str) – The name of the command (/name)
    - handler (function) – The function called when the command is run.
    - help (str) – The complete help for that command.
    - short (str) – A short description of the command.
    - completion (function) – The completion function for that command (optional)
    - usage (str) –

      A string showing the required and optional args of the command. Optional args should be surrounded by [] and mandatory args should be surrounded by <>.

      Example string: “<server> [port]”

    Raises Exception:
    | If the command already exists.

  `add_tab_key`(module, *args, **kwargs)

    Associate a binding to a handler, but only for a certain tab type.

    Parameters:

    - tab_type (Tab) – The type of tab to target.
    - key (str) – The binding to add.
    - handler (function) – The function called when the binding is pressed

  `add_timed_event`(_, *args, **kwargs)

    Schedule a timed event.

    Parameters: | event (timed_events.TimedEvent) – The timed event to schedule.

  `all_tabs`(_)

    Return a list of all opened tabs

    Returns list: | The list of tabs.

  `create_delayed_event`(_, *args, **kwargs)

    Create a delayed event, but do not schedule it; `add_timed_event()` must be used for that.

    A delayed event is a timed event with a delay from the time this function is called (instead of a datetime).

    Parameters:

    - delay (int) – The number of seconds to schedule the execution
    - callback (function) – The handler that will be executed
    - *args – Optional arguments passed to the handler.

    Returns: | The created event.
    Return type: | `timed_events.DelayedEvent`

  `create_timed_event`(_, *args, **kwargs)

    Create a timed event, but do not schedule it; `add_timed_event()` must be used for that.

    Parameters:

    - date (datetime.datetime) – The time at which the handler must be executed
    - callback (function) – The handler that will be executed
    - *args – Optional arguments passed to the handler.

    Returns: | The created event.
    Return type: | `timed_events.TimedEvent`

  `current_tab`(_)

    Get the current Tab.

    Returns: | The current tab.

  `del_command`(module, *args, **kwargs)

    Remove a global command.

    Parameters: | name (str) – The name of the command to remove. That command _must_ have been added by the same plugin

  `del_event_handler`(module, *args, **kwargs)

    Remove a handler for a poezio event.

    Parameters:

    - event_name (str) – The name of the targeted event.
    - handler (function) – The function to remove from the handlers.

  `del_key`(module, *args, **kwargs)

    Remove a global binding.

    Parameters: | key (str) – The binding to remove.

  `del_slix_event_handler`(module, event_name, handler)

    Remove a handler for a slixmpp event

    Parameters:

    - event_name (str) – The name of the targeted event.
    - handler (function) – The function to remove from the handlers.

  `del_tab_command`(module, *args, **kwargs)

    Remove a tab-specific command.

    Parameters:

    - tab_type (tabs.Tab) – The type of tab to target.
    - name (str) – The name of the command to remove. That command _must_ have been added by the same plugin

  `del_tab_key`(module, *args, **kwargs)

    Remove a binding added with add_tab_key

    Parameters:

    - tab_type (tabs.Tab) – The type of tab to target.
    - key (str) – The binding to remove.

  `get_conversation_messages`(_, *args, **kwargs)

    Get all the Messages of the current Tab.

    Returns: | The list of `text_buffer.Message` objects.
    Returns: | None if the Tab does not inherit from ChatTab.
    Return type: | `list`

  `information`(_, *args, **kwargs)

    Display a new message in the information buffer.

    Parameters:

    - msg (str) – The message to display.
    - typ (str) – The message type (e.g. Info, Error…)

  `remove_timed_event`(_, *args, **kwargs)

    Unschedule a timed event.

    Parameters: | event (timed_events.TimedEvent) – The event to unschedule.

  `run_command`(_, *args, **kwargs)

    Run a command from the current tab. (a command starts with a /, if not, it’s a message)

    Parameters: | line (str) – The command to run.

  `send_message`(_, *args, **kwargs)

    Send a message to the current tab.

    Parameters: | msg (str) – The message to send.

## Example plugins

Example 1: Add a simple command that sends “Hello World!” into the conversation

    class Plugin(BasePlugin):
        def init(self):
            self.add_command('hello', self.command_hello, "Send 'Hello World!'")

        def command_hello(self, arg):
            self.core.send_message('Hello World!')

Example 2: Adds an event handler that sends “tg” to a groupchat when a message is received from someone named “Partauche”

    class Plugin(BasePlugin):
        def init(self):
            self.add_event_handler('muc_msg', self.on_groupchat_message)

        def on_groupchat_message(self, message, tab):
            if message['mucnick'] == "Partauche":
                tab.command_say('tg')