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)[source]¶

Class that all plugins derive from.

init(self)[source]¶

Method called at the creation of the plugin.

Do not override __init__ and use this instead.

cleanup(self)[source]¶

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()[source]

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Schedule a timed event.

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

all_tabs(_)[source]¶

Return a list of all opened tabs

Returns list: The list of tabs.

create_delayed_event(_, *args, **kwargs)[source]¶

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)[source]¶

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(_)[source]¶

Get the current Tab.

Returns: The current tab.

del_command(module, *args, **kwargs)[source]¶

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)[source]¶

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)[source]¶

Remove a global binding.

Parameters: key (str) -- The binding to remove.

del_slix_event_handler(module, event_name, handler)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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(_)[source]¶

Get the current user global status.

Returns Status: The current status.

information(_, *args, **kwargs)[source]¶

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)[source]¶

Unschedule a timed event.

Parameters: event (timed_events.TimedEvent) -- The event to unschedule.

run_command(_, *args, **kwargs)[source]¶

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)[source]¶

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