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