From d676c2ee7b6207ff0b2a7b384052ab07c08bf43a Mon Sep 17 00:00:00 2001 From: mathieui Date: Sat, 13 Apr 2013 22:33:06 +0200 Subject: Move the plugins documentation (use automodule directive & docstrings) --- plugins/alias.py | 38 ++++++++++++++- plugins/amsg.py | 22 ++++++++- plugins/day_change.py | 12 +++++ plugins/display_corrections.py | 31 +++++++++++- plugins/double.py | 12 +++++ plugins/exec.py | 44 ++++++++++++++++- plugins/figlet.py | 20 ++++++++ plugins/gpg/__init__.py | 104 +++++++++++++++++++++++++++++++++++++++++ plugins/iq_show.py | 13 ++++++ plugins/link.py | 78 ++++++++++++++++++++++++++++++- plugins/mpd_client.py | 51 +++++++++++++++++++- plugins/otr.py | 95 +++++++++++++++++++++++++++++++++++++ plugins/pacokick.py | 22 +++++++++ plugins/ping.py | 32 +++++++++++++ plugins/quote.py | 30 ++++++++++++ plugins/rainbow.py | 23 +++++++++ plugins/reminder.py | 57 ++++++++++++++++++++++ plugins/replace.py | 64 +++++++++++++++++++++++-- plugins/revstr.py | 14 ++++++ plugins/screen_detach.py | 12 +++++ plugins/shuffle.py | 14 ++++++ plugins/simple_notify.py | 66 ++++++++++++++++++++++++++ plugins/status.py | 35 ++++++++++++++ plugins/time_marker.py | 29 +++++++++++- plugins/uptime.py | 22 +++++++++ 25 files changed, 927 insertions(+), 13 deletions(-) (limited to 'plugins') diff --git a/plugins/alias.py b/plugins/alias.py index a3843f35..80efe5bc 100644 --- a/plugins/alias.py +++ b/plugins/alias.py @@ -1,7 +1,41 @@ """ -Alias plugin. +Installation +------------ +You only have to load the plugin: + +``/load alias`` + +Usage +----- + +This plugin defines two new global commands: :term:`/alias` and :term:`/unalias`. + +.. glossary:: + + /alias + **Usage:** ``/alias [args]`` + + This command will create a new command, named ``name`` (and callable with + ``/name``), that runs ``/command``, with ``[args]`` as fixed args for the command. + When you run the alias, you can also pass parameters to it, that will be fed + to the original command. + + Example: :: + + /alias toto say "koin " + + Will bind ``/say koin `` to ``/toto``, so this alias will work in any + Chat tab. If someone calls it with :: + + /toto koin + + Poezio will then execute ``/say koin koin``. + + /unalias + **Usage:** ``/unalias `` + + This command removes a defined alias. -Allows the creation and the removal of personal aliases. """ from plugin import BasePlugin diff --git a/plugins/amsg.py b/plugins/amsg.py index 57a37255..c330373f 100644 --- a/plugins/amsg.py +++ b/plugins/amsg.py @@ -1,5 +1,25 @@ -# A simple broadcast plugin +""" +This plugin broadcasts a message to all your joined rooms. +.. note:: With great power comes great responsability. + Use with moderation. + +Installation +------------ +You only have to load the plugin.:: + + /load amsg + +Command +------- + +.. glossary:: + + /amsg + **Usage:** ``/amsg `` + + +""" from plugin import BasePlugin from tabs import MucTab diff --git a/plugins/day_change.py b/plugins/day_change.py index 179bfd98..d9cd3197 100644 --- a/plugins/day_change.py +++ b/plugins/day_change.py @@ -1,3 +1,15 @@ +""" +This plugin adds a message at 00:00 in each of your chat tabs saying that the +date has changed. + +Installation +------------ +You only have to load the plugin.:: + + /load day_change + +""" + from gettext import gettext as _ from plugin import BasePlugin import datetime diff --git a/plugins/display_corrections.py b/plugins/display_corrections.py index cad5a327..c7617b3e 100644 --- a/plugins/display_corrections.py +++ b/plugins/display_corrections.py @@ -1,6 +1,33 @@ -# A plugin that adds the /display_corrections command, to view the previous -# versions of a corrected message. +""" +Lists old versions of a corrected message. +Installation +------------ +:: + + /load display_corrections + +Usage +----- + +.. glossary:: + + /display_corrections + **Usage:** ``/display_corrections [number]`` + + This command lists the old versions of a message. + + Without argument, it will list the last corrected message if there + is any. If you give an integer as an argument, ``/display_corrections`` + will go back gradually in the buffer to find the message matching + that number (starting from 1, for the last corrected message). + + If you are scrolling in the buffer, Poezio will list the corrected messages + starting from the first you can see. (although there are some problems with + multiline messages). + + +""" from plugin import BasePlugin from common import shell_split import tabs diff --git a/plugins/double.py b/plugins/double.py index 597ab242..02c7ddcd 100644 --- a/plugins/double.py +++ b/plugins/double.py @@ -1,3 +1,15 @@ +""" +Double the first word of any message you send in a :ref:`muctab`, making you appear retarded. + +Installation +------------ + +You only have to load the plugin: + +.. code-block:: none + + /load double +""" from plugin import BasePlugin class Plugin(BasePlugin): diff --git a/plugins/exec.py b/plugins/exec.py index 4dbe9590..10681713 100644 --- a/plugins/exec.py +++ b/plugins/exec.py @@ -1,4 +1,46 @@ -# A plugin that can execute a command and send the result in the conversation +""" +This plugin lets you execute a system command through poezio. + +Installation +------------ + +You only have to load the plugin. :: + + /load exec + +Usage +----- + +.. warning:: Running commands that start a daemon or an interface is not a good + idea. + +.. glossary:: + + /exec + **Usage:** ``/exec [-o|-O] `` + + Execute a system command. + + :: + + /exec command + + Will give you the result in the information buffer. + + :: + + /exec -o command + + Will send the result of the command into the current tab, if possible. + + :: + + /exec -O command + + Will send the result of the command and the command summary into the current + tab, if possible. + +""" from plugin import BasePlugin import os diff --git a/plugins/figlet.py b/plugins/figlet.py index eaf8dab3..9006f793 100644 --- a/plugins/figlet.py +++ b/plugins/figlet.py @@ -1,3 +1,23 @@ +""" +This plugin uses figlet to transform every message into a big ascii-art +message. + +Installation +------------ +You only have to load the plugin (and have :file:`figlet` installed, of course). +:: + + /load figlet + + +Usage +----- + +Say something in a Chat tab. + +.. note:: Can create fun things when used with :ref:`The rainbow plugin `. + +""" from plugin import BasePlugin import subprocess diff --git a/plugins/gpg/__init__.py b/plugins/gpg/__init__.py index 9fa8ee13..c6945e18 100644 --- a/plugins/gpg/__init__.py +++ b/plugins/gpg/__init__.py @@ -1,3 +1,107 @@ +""" +This plugin implements the `XEP-0027`_ “Current Jabber OpenPGP Usage”. + +This is a plugin used to encrypt one-to-one conversation using the PGP +encryption method. You can use it if you want really good privacy. Without this +encryption, your messages are encrypted **at least** from your client (poezio) to +your server. The message is decrypted by your server and you cannot control the +encryption method of your messages from your server to your contact’s server +(unless you are your own server’s administrator), nor from your contact’s +server to your contact’s client. + +This plugin does end-to-end encryption. This means that **only** your contact can +decrypt your messages, and it is fully encrypted during **all** its travel +through the internet. + +Note that if you are having an encrypted conversation with a contact, you can +**not** send XHTML-IM messages to him. They will be removed and be replaced by +plain text messages. + +Installation and configuration +------------------------------ + +You should autoload this plugin, as it will send your signed presence directly +on login, making it easier for your contact’s clients to know that you are +supporting GPG encryption. To do that, use the :term:`plugins_autoload` configuration +option. + +You need to create a plugin configuration file. Create a file named :file:`gpg.cfg` +into your plugins configuration directory (:file:`~/.config/poezio/plugins` by +default), and fill it like this: + +.. code-block:: ini + + [gpg] + keyid = 091F9C78 + passphrase = your OPTIONAL passphrase + + [keys] + example@jabber.org = E3CFCDE2 + juliet@xmpp.org = EF27ABCD + +The ``gpg`` section is about your key. You need to specify the keyid, for the +key you want to use. You can as well provide a passphrase. If you don’t, you +should use a gpg agent or something like that that will ask your passphrase +whenever you need it. + +The ``keys`` section contains your contact’s id keys. For each contact you want +to have encrypted conversations with, add her/his JID associated with the keyid +of his/her key. + +And that’s it, now you need to talk directly to the **full** jid of your +contacts. Poezio doesn’t let you encrypt messages whom recipients is a bare +JID. + +Additionnal information on GnuPG +-------------------------------- + +Create a key +~~~~~~~~~~~~ + +To create a personal key, use + +.. code-block:: bash + + gpg --gen-key + +and follow the instructions. + +Keyid +~~~~~ +The keyid (required in the gpg.cfg configuration file) is a 8 character-long +key. You can get the ones you created or imported by using the command + +.. code-block:: bash + + gpg --list-keys + +You will get something like + +.. code-block:: none + + pub 4096R/01234567 2011-11-11 + uid Your Name Here (comment) + sub 4096R/AAFFBBCC 2011-11-11 + + pub 2048R/12345678 2011-11-12 [expire: 2011-11-22] + uid A contact’s name (comment) + sub 2048R/FFBBAACC 2011-11-12 [expire: 2011-11-22] + +In this example, the keyids are ``01234567`` and ``12345678``. + +Share your key +~~~~~~~~~~~~~~ +Use: + +.. code-block:: bash + + gpg --send-keys --keyserver pgp.mit.edu + +to upload you public key on a public server. + +.. _XEP-0027: http://xmpp.org/extensions/xep-0027.html + +""" from gpg import gnupg from sleekxmpp.xmlstream.stanzabase import JID diff --git a/plugins/iq_show.py b/plugins/iq_show.py index 06d06d8e..69bd2722 100644 --- a/plugins/iq_show.py +++ b/plugins/iq_show.py @@ -1,3 +1,16 @@ +""" +Show the exchanged IQs (useful for debugging). + +Installation +------------ + +Load the plugin: + +.. code-block:: none + + /load iq_show + +""" from plugin import BasePlugin from sleekxmpp.xmlstream.matcher import StanzaPath from sleekxmpp.xmlstream.handler import Callback diff --git a/plugins/link.py b/plugins/link.py index 9e8b6f97..a51a8bef 100644 --- a/plugins/link.py +++ b/plugins/link.py @@ -1,6 +1,80 @@ -# A plugin that adds the /link command, letting you open links that are pasted -# in the conversation, without having to click them. +""" +Opens links in a browser. +Installation +------------ + +First use case: local use +~~~~~~~~~~~~~~~~~~~~~~~~~ +If you use poezio on your workstation, this is for you. +You only have to load the plugin: :: + + /load link + +Second use case: remote use +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you use poezio through SSH, this is for you. + +.. note:: Small explanation: Poezio will create a `Unix FIFO`_ and send the commands in, + and you will have to run a dæmon locally with ssh, to get those commands. + +First, set the :term:`exec_remote` option in the config file to ``true``. Then select +the directory you want to put the fifo in (default is the current +directory, :file:`./`), the :file:`poezio.fifo` file will be created there. + +After that, load the plugin: :: + + /load link + +And open a link with :term:`/link` (as described below), this will create the FIFO. + +You need to grab poezio’s sources on your client computer, or at least the `daemon.py`_ +file. + +Finally, on your client computer, run the ssh command: + +.. code-block:: bash + + ssh toto@example.org "cat ~/poezio/poezio.fifo" | python3 daemon.py + +Usage +----- + +.. glossary:: + + /link + **Usage:** ``/link [num]`` + + This plugin adds a :term:`/link` command that will open the links in ``firefox``. If + you want to use another browser, you can use the :term:`/set` command to change the + :term:`browser` option. + + + :term:`/link` without argument will open the last received link, if any is found. + If an integer argument is given, /link will go back gradually in the buffer + to open the previous link, and so on. + + + If you are scrolling in the buffer, poezio will open the links starting from + the first you can see. (although there are some problems with multiline + messages). + +Options +------- + +:term:`exec_remote` + + To execute the command on your client + +.. glossary:: + + browser + Set the default browser started by the plugin + +.. _Unix FIFO: https://en.wikipedia.org/wiki/Named_pipe +.. _daemon.py: http://gitweb.louiz.org/?p=poezio;a=blob_plain;f=src/daemon.py;hb=HEAD + +""" import re from plugin import BasePlugin diff --git a/plugins/mpd_client.py b/plugins/mpd_client.py index 09a2e5d2..5991422c 100644 --- a/plugins/mpd_client.py +++ b/plugins/mpd_client.py @@ -1,4 +1,53 @@ -# a plugin adding a command to manipulate an MPD instance +""" +This plugin is here to send what you are listening to in a chat tab. + + + +Installation +------------ + +You need `python-mpd`_, in its python3 version. + +Then you can load the plugin. + +.. code-block:: none + + /load mpd_client + + +Configuration +------------- + +You have to put the following into :file:`mpd_client.cfg`, as explained in +the :ref:`plugin-configuration` section. + +.. note:: If you do not put anything, the plugin will try to connect to + :file:`localhost:6600` with no password. + +.. code-block:: ini + + [mpd_client] + host = the_mpd_host + port = 6600 + password = password if necessary + + +Usage +----- + +.. glossary:: + + /mpd + **Usage:** ``/mpd [full]`` + + The bare command will show the current song, artist, and album + + ``/mpd full`` will show the current song, artist, and album, + plus a nice progress bar in color. + +.. _python-mpd: https://github.com/Mic92/python-mpd2 + +""" from plugin import BasePlugin from common import shell_split diff --git a/plugins/otr.py b/plugins/otr.py index 4e900b84..9014a4c6 100644 --- a/plugins/otr.py +++ b/plugins/otr.py @@ -1,3 +1,98 @@ +""" + +.. warning:: THE OTR LIB IS IN AN EXPERIMENTAL STATE AND SHOULD NOT BE + CONSIDERED AS ENTIRELY RELIABLE + +This plugin implements `Off The Record messaging`_. + +This is a plugin used to encrypt one-to-one conversation using the OTR +encryption method. You can use it if you want good privacy, deniability, +authentication, and strong secrecy. Without this +encryption, your messages are encrypted **at least** from your client (poezio) to +your server. The message is decrypted by your server and you cannot control the +encryption method of your messages from your server to your contact’s server +(unless you are your own server’s administrator), nor from your contact’s +server to your contact’s client. + +This plugin does end-to-end encryption. This means that **only** your contact can +decrypt your messages, and it is fully encrypted during **all** its travel +through the internet. + +Note that if you are having an encrypted conversation with a contact, you can +**not** send XHTML-IM messages to him. They will be removed and be replaced by +plain text messages. + +Installation and configuration +------------------------------ + +To use the OTR plugin, you must first install libopenotr. + +If you use Archlinux, there is a `libopenotr-git`_ package on the AUR. + +If not, then you will have to install it by hand. + +First, clone the repo and go inside the created directory: + +.. code-block:: bash + + git clone https://github.com/teisenbe/libopenotr.git + cd libopenotr + +Then run autogen.sh and configure + +.. code-block:: bash + + sh autogen.sh + ./configure --enable-gaping-security-hole + +(as of now, you *should* have been warned enough that the library is not finished) + +Then compile & install the lib: + +.. code-block:: bash + + make + sudo make install + +Finally, install the python module: + +.. code-block:: bash + + python3 setup.py build + sudo python3 setup.py install + +Usage +----- + +To use OTR, make sure the plugin is loaded (if not, then do ``/load otr``). + +Once you are in a private conversation, you have to do a: + + +.. code-block:: none + + /otr start + +The status of the OTR encryption should appear in the bar between the chat and +the input as ``OTR: encrypted``. + + +Once you’re done, end the OTR session with + +.. code-block:: none + + /otr end + +Known problems +-------------- + +Empty messages send when changing status. + +.. _Off The Record messaging: http://wiki.xmpp.org/web/OTR +.. _libopenotr-git: https://aur.archlinux.org/packages.php?ID=57957 + +""" + import pyotr from sleekxmpp.xmlstream.stanzabase import JID diff --git a/plugins/pacokick.py b/plugins/pacokick.py index 358df013..bd285db8 100644 --- a/plugins/pacokick.py +++ b/plugins/pacokick.py @@ -1,3 +1,25 @@ +""" +This plugin adds a :term:`/pacokick` command, which is a random kick. + +Installation +------------ +You only have to load the plugin. + +.. code-block:: none + + /load pacokick + +Usage +----- + +.. glossary:: + + /pacokick + + Run the command in a room where you are a moderator to + kick someone randomly. +""" + from random import choice from tabs import MucTab diff --git a/plugins/ping.py b/plugins/ping.py index faf3e97d..c4f56c81 100644 --- a/plugins/ping.py +++ b/plugins/ping.py @@ -1,3 +1,35 @@ +""" +This plugin allows you to ping an entity. + +Installation +------------ +You only have to load the plugin. + +.. code-block:: none + + /load ping + +Command +------- + +.. glossary:: + + /ping + **Usage (globally):** ``/ping `` + + **Usage (in a MUC tab):** ``/ping `` + + **Usage (in a conversation tab):** ``/ping [jid]`` + + Globally, you can do ``/ping jid@example.com`` to get a ping. + + In a MUC, you can either do it to a JID or a nick (``/ping nick`` or ``/ping + jid@example.com``). + + In a private or a direct conversation, you can do ``/ping`` to ping + the current interlocutor. +""" + from plugin import BasePlugin from roster import roster from common import safeJID diff --git a/plugins/quote.py b/plugins/quote.py index 9b1fd9ad..829f251e 100644 --- a/plugins/quote.py +++ b/plugins/quote.py @@ -1,3 +1,33 @@ +""" +This plugin allows you to quote messages easily. + +Installation +------------ +You only have to load the plugin. + +.. code-block:: none + + /load quote + +Usage +------- + +.. glossary:: + + /quote + **Usage:** ``/quote `` + + Timestamp is in ``HH:MM:SS`` format, and can be completed with [tab]. + + Example: + + .. code-block:: none + + /quote 21:12:23 + + If there is a message at 21:12:23, it will be put in the input. If there + isn’t, you will get a warning. +""" from plugin import BasePlugin from xhtml import clean_text import common diff --git a/plugins/rainbow.py b/plugins/rainbow.py index 4a188b33..0937eeb7 100644 --- a/plugins/rainbow.py +++ b/plugins/rainbow.py @@ -1,3 +1,26 @@ +""" +This plugin colors each character of a message with a random color. + +Installation +------------ + +You only have to load the plugin. + +.. code-block:: none + + /load rainbow + +Usage +----- + +.. glossary:: + + /rainbow + + Say something in a Chat tab. + +.. note:: Can create fun things when used with :ref:`The figlet plugin `. +""" from plugin import BasePlugin import xhtml import random diff --git a/plugins/reminder.py b/plugins/reminder.py index 16a3f710..eb2f9801 100644 --- a/plugins/reminder.py +++ b/plugins/reminder.py @@ -1,3 +1,60 @@ +""" +Installation +------------ +You only have to load the plugin: + +.. code-block:: none + + /load reminder + +Usage +----- + +This plugin defines three new global commands: :term:`/remind`, +:term:`/done`, and :term:`/tasks`. + +.. glossary:: + + /remind + **Usage:** ``/remind