# Plugin API documentation

## External plugins

It is possible to create external plugins easily using setuptools’ entry_point feature. You can register your plugin against the `poezio_plugins` entry group with the following snippet in your project `setup.py`:

    setup(
        ..
        packages=['yourmodule'],
        entry_points={'poezio_plugins': 'yourplugin = yourmodule'},
        ..
    )

The plugin will then be available as `yourplugin` at runtime.

## BasePlugin

class poezio.plugin.BasePlugin(name, 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.

  dependencies

    Dependencies on other plugins, as a set of strings. A reference to each dependency will be added in `refs`.

  refs

    This attribute is not to be edited by the user. It will be populated when the plugin is initialized with references on each plugin specified in the `dependencies` attribute.

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