sphinx: document plugins

[sid.git] / sid / echo.py

diff --git a/sid/echo.py b/sid/echo.py
index 94836d0b4c4766cb0ebc33015676ddcb66c7f188..5bb90c06768e7e5daaf9e99b6721ef8d3a352784 100644 (file)
--- a/sid/echo.py
+++ b/sid/echo.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 # Copyright (C) 2007-2012 Thomas Perl <thp.io/about>
-# Copyright (C) 2014 kaliko <kaliko@azylum.org>
+# Copyright (C) 2014, 2020 kaliko <kaliko@azylum.org>
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -17,7 +17,10 @@
 
 from .plugin import Plugin, botcmd
 
+
 class Echo(Plugin):
+    """Drops a message to be sent when someone gets online.
+    """
 
     def __init__(self, bot):
         Plugin.__init__(self, bot)
@@ -28,9 +31,11 @@ class Echo(Plugin):
         # any presences you send yourself. To limit event handling
         # to a single room, use the events muc::room@server::presence,
         # muc::room@server::got_online, or muc::room@server::got_offline.
-        bot.add_event_handler("muc::%s::presence" %    self.bot.room, self.log_presence)
+        bot.add_event_handler("muc::%s::presence" %
+                              self.bot.room, self.log_presence)
 
     def log_presence(self, pres):
+        """Handler method registering MUC participants presence"""
         self.log.debug('%s: %s', pres['muc']['nick'], pres['type'])
         nick = pres['muc']['nick']
         self.presence.update({nick: (pres['muc']['role'], pres['type'])})
@@ -40,13 +45,15 @@ class Echo(Plugin):
                 self.send(self.bot.room,
                           self.inbox.get(nick).pop(),
                           mtype='groupchat')
-            self.inbox.pop(nick)
+                self.inbox.pop(nick)
 
     @botcmd
     def tell(self, message, args):
-        """drop a message to be sent when someone gets online.
-        !tell queue        : messages in queue
-        !tell <nick> <msg> : append <msg> to <nick> in queue"""
+        """
+        **commands**:
+
+        * ``!tell queue``        : messages in queue
+        * ``!tell <nick> <msg>`` : append <msg> to <nick> in queue"""
         if not len(args):
             msg = 'Missing arguments:\n{}'.format(self.tell.__doc__)
             self.reply(message, msg)
@@ -54,13 +61,13 @@ class Echo(Plugin):
         if len(args) == 1:
             if args[0] == 'queue':
                 msg = '\n'.join(['{0}:\n\t{1}'.format(k, '\n'.join(v))
-                                for k, v in self.inbox.items()])
+                                 for k, v in self.inbox.items()])
                 self.reply(message, msg)
                 return
             if args[0] == 'purge':
                 sender = message['from'].resource
                 if self.presence[sender][0] == 'moderator':
-                    self.online = set()
+                    self.inbox = dict()
                 return
         if len(args) < 2:
             msg = 'Please provide a message:\n{}'.format(self.tell.__doc__)
@@ -69,6 +76,7 @@ class Echo(Plugin):
         self._handle_msg(message)
 
     def _handle_msg(self, message):
+        """Format and drop message in the inbox"""
         sender = message['from'].resource
         recipient = message['body'].split()[1]
         tell_msg = ' '.join(message['body'].split()[2:])
@@ -78,9 +86,9 @@ class Echo(Plugin):
                 self.presence[recipient][1] == 'available'):
             return
         if recipient in self.inbox.keys():
-           self.inbox[recipient].append(letter)
+            self.inbox[recipient].append(letter)
         else:
-           self.inbox[recipient] = [letter]
+            self.inbox[recipient] = [letter]
 
 
 # VIM MODLINE