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.
-
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
A complete list of those events can be found at https://doc.poez.io/dev/events.html
-
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.
-
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
-
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
-
remove_timed_event
(_, *args, **kwargs)[source]¶ Unschedule a timed event.
- Parameters
event (timed_events.TimedEvent) -- The event to unschedule.
-
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')