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.

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