diff options
Diffstat (limited to 'doc/source/dev')
-rw-r--r-- | doc/source/dev/contributing.rst | 6 | ||||
-rw-r--r-- | doc/source/dev/e2ee.rst | 52 | ||||
-rw-r--r-- | doc/source/dev/index.rst | 1 | ||||
-rw-r--r-- | doc/source/dev/plugin.rst | 31 | ||||
-rw-r--r-- | doc/source/dev/slix.rst | 4 |
5 files changed, 88 insertions, 6 deletions
diff --git a/doc/source/dev/contributing.rst b/doc/source/dev/contributing.rst index 8d386c87..4c2d8161 100644 --- a/doc/source/dev/contributing.rst +++ b/doc/source/dev/contributing.rst @@ -38,8 +38,8 @@ useless merges (and polluting the commit history) when none is needed. .. code-block:: bash git fetch origin - git rebase origin/master - git push origin master + git rebase origin/main + git push origin main If your commit is related to an issue on our tracker_ (or fixes such an issue), you can use ``Fix #BUGID`` or ``References #BUGID`` to help with the @@ -64,4 +64,4 @@ account and submit it again. If you have already submitted some code and plan to do more, you can ask us direct commit access on the main repo. -.. _tracker: https://dev.louiz.org/project/poezio/bugs +.. _tracker: https://lab.louiz.org/poezio/poezio/-/issues diff --git a/doc/source/dev/e2ee.rst b/doc/source/dev/e2ee.rst new file mode 100644 index 00000000..23304512 --- /dev/null +++ b/doc/source/dev/e2ee.rst @@ -0,0 +1,52 @@ +End-to-end Encryption API documentation +======================================= + +E2EEPlugin +---------- + +.. module:: poezio.plugin_e2ee + + +.. autoclass:: E2EEPlugin + :members: decrypt, encrypt, encryption_name, encryption_short_name, eme_ns, replace_body_with_eme, stanza_encryption, tag_whitelist + + +Please refer to :py:class:`~BasePlugin` for more information on how to +write plugins. + +Example plugins +--------------- + +**Example 1:** Base64 plugin + +.. code-block:: python + + from base64 import b64decode, b64encode + from poezio.plugin_e2ee import E2EEPlugin + from slixmpp import Message + + + class Plugin(E2EEPlugin): + """Base64 Plugin""" + + encryption_name = 'base64' + encryption_short_name = 'b64' + eme_ns = 'urn:xmpps:base64:0' + + # This encryption mechanism is using <body/> as a container + replace_body_with_eme = False + + def decrypt(self, message: Message, _tab) -> None: + """ + Decrypt base64 + """ + body = message['body'] + message['body'] = b64decode(body.encode()).decode() + + def encrypt(self, message: Message, _tab) -> None: + """ + Encrypt to base64 + """ + # TODO: Stop using <body/> for this. Put the encoded payload in another element. + body = message['body'] + message['body'] = b64encode(body.encode()).decode() diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index 21ea6253..630abfad 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -14,6 +14,7 @@ About plugins :maxdepth: 2 plugin + e2ee events slix xep diff --git a/doc/source/dev/plugin.rst b/doc/source/dev/plugin.rst index 7a63ed8f..4614c761 100644 --- a/doc/source/dev/plugin.rst +++ b/doc/source/dev/plugin.rst @@ -1,13 +1,32 @@ Plugin API documentation ======================== +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'], + entry_points={'poezio_plugins': 'yourplugin = yourmodule'}, + .. + ) + +The plugin will then be available as ``yourplugin`` at runtime. + BasePlugin ---------- .. module:: poezio.plugin .. autoclass:: BasePlugin - :members: init, cleanup, api, core .. method:: init(self) @@ -29,6 +48,16 @@ BasePlugin The :py:class:`~PluginAPI` instance for this plugin. + .. 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. Each plugin inheriting :py:class:`~BasePlugin` has an ``api`` member variable, which refers to a :py:class:`~PluginAPI` object. diff --git a/doc/source/dev/slix.rst b/doc/source/dev/slix.rst index 3c06e349..50f9dd07 100644 --- a/doc/source/dev/slix.rst +++ b/doc/source/dev/slix.rst @@ -1,5 +1,5 @@ -SleekXMPP classes -================= +Slixmpp classes +=============== .. module:: slixmpp |