sid/plugin.py

   1 # -*- coding: utf-8 -*-
   2
   3 # Copyright (C) 2010, 2011 Anaël Verrier <elghinn@free.fr>
   4 # Copyright (C) 2014, 2020 kaliko <kaliko@azylum.org>
   5
   6 # This program is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, version 3 only.
   9
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 from .sid import botcmd
  19
  20
  21 class Plugin:
  22     """
  23     Simple Plugin object to derive from:
  24
  25        * Exposes the bot object and its logger
  26        * Provides send helpers
  27
  28     :param sid.sid.MUCBot bot: bot the plugin is load from
  29     """
  30
  31     def __init__(self, bot):
  32         self.bot = bot
  33         self.log = bot.log.getChild(self.__class__.__name__)
  34         #: :py:obj:`list` : List of tuples (event, handler)
  35         self.handlers = []
  36
  37     def add_handlers(self):
  38         """Add handlers declared in self.hanlders"""
  39         for event, handler in self.handlers:
  40             self.log.debug(f'Add {event} > {self.__class__.__name__}().{handler.__name__}')
  41             self.bot.add_event_handler(event, handler)
  42
  43     def rm_handlers(self):
  44         """Remove handlers declared in self.hanlders"""
  45         for event, handler in self.handlers:
  46             self.log.debug(f'Remove {event} > {self.__class__.__name__}().{handler.__name__}')
  47             self.bot.del_event_handler(event, handler)
  48
  49     def send(self, dest, msg, mtype='chat'):
  50         """Send msg to dest
  51
  52         :param str dest: Message recipient
  53         :param dict,str msg: Message to send (use dict for xhtml-im)
  54
  55         .. note::
  56           if **msg** is a :py:obj:`dict` to provide xhmlt-im massages::
  57
  58               msg = {
  59                   mbody: 'text',
  60                   mhtml: '<b>text</b>,  # optional'
  61               }
  62         """
  63         if isinstance(msg, str):
  64             msg = {'mbody': msg}
  65         msg.setdefault('mhtml', None)
  66         self.bot.send_message(mto=dest,
  67                               mtype=mtype,
  68                               **msg)
  69
  70     def reply(self, rcv, msg):
  71         """Smart reply to message received.
  72
  73         Replies ``msg`` in private or on the muc depending on ``rcv``
  74
  75         :param rcv: The received message (slixmpp object)
  76         :param dict,str msg: The message to reply, refer to :py:obj:`sid.plugin.Plugin.send` for ``msg`` format
  77         """
  78         to = rcv['from']
  79         if rcv['type'] == 'groupchat':
  80             to = rcv['mucroom']
  81         self.send(to, msg, mtype=rcv['type'])
  82
  83     def shutdown(self):
  84         """Empty method to override. Called on bot shutdown"""
  85         pass