Plugin API documentation

BasePlugin

class poezio.plugin.BasePlugin(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')