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