diff options
Diffstat (limited to 'doc/source/dev')
| -rw-r--r-- | doc/source/dev/contributing.rst | 10 | ||||
| -rw-r--r-- | doc/source/dev/e2ee.rst | 52 | ||||
| -rw-r--r-- | doc/source/dev/events.rst | 2 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/dev/overview.rst | 6 | ||||
| -rw-r--r-- | doc/source/dev/plugin.rst | 31 | ||||
| -rw-r--r-- | doc/source/dev/slix.rst | 4 | ||||
| -rw-r--r-- | doc/source/dev/xep.rst | 2 |
8 files changed, 95 insertions, 13 deletions
diff --git a/doc/source/dev/contributing.rst b/doc/source/dev/contributing.rst index ca7de049..4c2d8161 100644 --- a/doc/source/dev/contributing.rst +++ b/doc/source/dev/contributing.rst @@ -5,7 +5,7 @@ Conventions ----------- We don’t have a strict set of conventions, but you should respect PEP8 mostly -(e.g. 4 spaces, class names in CamelCase and methods lowercased with +(e.g. 4 spaces, class names in CamelCase and methods lowercase with underscores) except if it means less-readable code (80 chars is often a hassle, and if you look inside poezio you’ll see lots of long lines, mostly because of strings). @@ -18,7 +18,7 @@ for the application as a whole. Commit guidelines ----------------- -Commits **should** have a meaninful title (first line), and *may* have a detailed +Commits **should** have a meaningful title (first line), and *may* have a detailed description below. There are of course exceptions (for example, a single-line commit that takes care of a typo right behind a big commit does not need to say ``fix a typo ("azre" → "are") in toto.py line 45454``, since the metainfos @@ -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/events.rst b/doc/source/dev/events.rst index a2e6ad9d..6dd2e65e 100644 --- a/doc/source/dev/events.rst +++ b/doc/source/dev/events.rst @@ -121,7 +121,7 @@ The following events are poezio-only events, for Slixmpp events, check out changing_nick - **presence:** :py:class:`~~slixmpp.Presence` to be sent - Triggered when the user changes his/her nickname on a MUC. The + Triggered when the user changes their nickname on a MUC. The presence can thus be modified before being sent. send_normal_presence 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/overview.rst b/doc/source/dev/overview.rst index fcf5ff22..96d4435b 100644 --- a/doc/source/dev/overview.rst +++ b/doc/source/dev/overview.rst @@ -40,7 +40,7 @@ method (inherited empty from the Tab class), call a scrolling method from the appropriate **window**. All tabs types inherit from the class **Tab**, and the tabs featuring -chat functionnality will inherit from **ChatTab** (which inherits from **Tab**). +chat functionality will inherit from **ChatTab** (which inherits from **Tab**). Examples of **tabs**: MUCTab, XMLTab, RosterTab, MUCListTab, etc… @@ -80,9 +80,9 @@ or /command "arg1 with spaces" arg2 -However, when creating a command, you wil deal with _one_ str, no matter what. +However, when creating a command, you will deal with _one_ str, no matter what. There are utilities to deal with it (common.shell_split), but it is not always -necessary. Commands are registered in the **commands** dictionnary of a tab +necessary. Commands are registered in the **commands** dictionary of a tab structured as key (command name) -> tuple(command function, help string, completion). Completions are a bit tricky, but it’s easy once you get used to it: 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 diff --git a/doc/source/dev/xep.rst b/doc/source/dev/xep.rst index 339553ff..7feca4cf 100644 --- a/doc/source/dev/xep.rst +++ b/doc/source/dev/xep.rst @@ -91,7 +91,7 @@ Table of all XEPs implemented in poezio. +----------+-------------------------+---------------------+ |0270 |Compliance Suites 2010 |Advanced Client | +----------+-------------------------+---------------------+ -|0280 |Messsage Carbons |100% | +|0280 |Message Carbons |100% | +----------+-------------------------+---------------------+ |0296 |Best Practices for |0% | | |Resource Locking | | |