plugin.rst 2.73 KB
Newer Older
1
2
3
Plugin API documentation
========================

4
5
6
7
8
9
10
11
12
13
14
15
16
17
External plugins
----------------

It is possible to create external plugins easily using `setuptools'
entry_point
<https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_
feature. You can register your plugin against the ``poezio_plugins`` entry
group with the following snippet in your project ``setup.py``:

.. code-block:: python

    setup(
        ..
        packages=['yourmodule'],
Maxime Buquet's avatar
Maxime Buquet committed
18
        entry_points={'poezio_plugins': 'yourplugin = yourmodule'},
19
20
21
22
23
        ..
    )

The plugin will then be available as ``yourplugin`` at runtime.

24
25
26
BasePlugin
----------

mathieui's avatar
mathieui committed
27
.. module:: poezio.plugin
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

.. autoclass:: BasePlugin

    .. method:: init(self)

        Method called at the creation of the plugin.

        Do not override __init__ and use this instead.

    .. method:: cleanup(self)

        Method called before the destruction of the plugin.

        Use it to erase or save things before the plugin is disabled.

    .. attribute:: core

        The Poezio :py:class:`~Core` object. Use it carefully.

    .. attribute:: api

        The :py:class:`~PluginAPI` instance for this plugin.

51
52
53
54
55
56
57
58
59
60
    .. attribute:: dependencies

        Dependencies on other plugins, as a set of strings. A reference
        to each dependency will be added in ``refs``.

    .. attribute:: 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.
61
62
63
64
65
66
67
68

Each plugin inheriting :py:class:`~BasePlugin` has an ``api`` member variable, which refers
to a :py:class:`~PluginAPI` object.

The :py:class:`~PluginAPI` object is an a interface through which the :py:class:`~BasePlugin`
(and inheritors) *should* go to interact with poezio. If it is not sufficient, then the ``core``
member can be used.

69
70
71
PluginAPI
---------

72
73
74
75
76
.. autoclass:: PluginAPI
    :members:
    :undoc-members:


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
Example plugins
---------------

**Example 1:** Add a simple command that sends "Hello World!" into the conversation

.. code-block:: python

    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”

.. code-block:: python

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