sid/plugin.py

   1 # -*- coding: utf-8 -*-
   2 # SPDX-FileCopyrightText: 2010, 2011 Anaël Verrier <elghinn@free.fr>
   3 # SPDX-FileCopyrightText: 2014, 2020, 2023 kaliko <kaliko@azylum.org>
   4
   5
   6 from slixmpp.exceptions import XMPPError
   7
   8 from .sid import botcmd
   9
  10
  11 class Plugin:
  12     """
  13     Simple Plugin object to derive from:
  14
  15        * Exposes the bot object and its logger
  16        * Provides send helpers
  17
  18     :param sid.sid.MUCBot bot: bot the plugin is load from
  19     """
  20
  21     def __init__(self, bot):
  22         self.bot = bot
  23         self.log = bot.log.getChild(self.__class__.__name__)
  24         #: :py:obj:`list` : List of tuples (event, handler)
  25         self.handlers = []
  26
  27     def add_handlers(self):
  28         """Add handlers declared in self.hanlders"""
  29         for event, handler in self.handlers:
  30             self.log.debug(f'Add {event} > {self.__class__.__name__}().{handler.__name__}')
  31             self.bot.add_event_handler(event, handler)
  32
  33     def rm_handlers(self):
  34         """Remove handlers declared in self.hanlders"""
  35         for event, handler in self.handlers:
  36             self.log.debug(f'Remove {event} > {self.__class__.__name__}().{handler.__name__}')
  37             self.bot.del_event_handler(event, handler)
  38
  39     def send(self, dest, msg, mtype='chat'):
  40         """Send msg to dest
  41
  42         :param str dest: Message recipient
  43         :param dict,str msg: Message to send (use dict for xhtml-im)
  44
  45         .. note::
  46           if **msg** is a :py:obj:`dict` to provide xhmlt-im massages::
  47
  48               msg = {
  49                   mbody: 'text',
  50                   mhtml: '<b>text</b>,  # optional'
  51               }
  52         """
  53         if isinstance(msg, str):
  54             msg = {'mbody': msg}
  55         msg.setdefault('mhtml', None)
  56         self.bot.send_message(mto=dest,
  57                               mtype=mtype,
  58                               **msg)
  59
  60     def reply(self, rcv, msg):
  61         """Smart reply to message received.
  62
  63         Replies ``msg`` in private or on the muc depending on ``rcv``
  64
  65         :param rcv: The received message (slixmpp object)
  66         :param dict,str msg: The message to reply, refer to :py:obj:`sid.plugin.Plugin.send` for ``msg`` format
  67         """
  68         to = rcv['from']
  69         if rcv['type'] == 'groupchat':
  70             to = rcv['mucroom']
  71         self.send(to, msg, mtype=rcv['type'])
  72
  73     async def ban(self, jid, reason):
  74         """Coroutine to ban a jid from the room
  75
  76         :param str jid: JID to ban
  77         :param str reason: Reason
  78         """
  79         room = self.bot.room
  80         try:
  81             await self.bot['xep_0045'].set_affiliation(room,
  82                     jid=jid, affiliation='outcast', reason=reason)
  83         except XMPPError as error:
  84             self.log.error(error)
  85
  86     def shutdown(self):
  87         """Empty method to override. Called on bot shutdown"""
  88         pass