# Plugin API documentation

## BasePlugin

class `poezio.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 `poezio.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 OTR, which must be the last function called on the text. Defaults to 0.

    A complete list of those events can be found at https://doc.poez.io/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`

  `get_status`(_)

    Get the current user global status.

    Returns Status: | The current status.

  `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')