Merge pull request #1982 from Exirel/bot-has-privilege

plugin: new `require_bot_privilege` decorator

Author: dgw

docs/source/plugin/anatomy.rst

@@ -80,6 +80,18 @@ better to limit who can trigger them. There are decorators for that:
   trigger the rule
 * :func:`sopel.plugin.require_owner`: only the bot's owner can trigger the rule
 
+Sometimes it's not the channel privilege level of the user who triggers a
+command that matters, but the **bot's** privilege level. For that, there are
+two options:
+
+* :func:`sopel.plugin.require_bot_privilege`: this decorator is similar to
+  the ``require_privilege`` decorator, but it checks the bot's privilege level
+  instead of the user's; works only for channel messages, not private messages;
+  and you probably want to use it with the ``require_chanmsg`` decorator.
+* :meth:`bot.has_channel_privilege() <sopel.bot.Sopel.has_channel_privilege>`
+  is a method that can be used to check the bot's privilege level in a channel,
+  which can be used in any callable.
+
 .. __: https://ircv3.net/specs/extensions/account-tag-3.2
 
 Rate limiting

sopel/bot.py

@@ -200,6 +200,29 @@ def hostmask(self):
 
         return self.users.get(self.nick).hostmask
 
+    def has_channel_privilege(self, channel, privilege):
+        """Tell if the bot has a ``privilege`` level or above in a ``channel``.
+
+        :param str channel: a channel the bot is in
+        :param int privilege: privilege level to check
+        :raise ValueError: when the channel is unknown
+
+        This method checks the bot's privilege level in a channel, i.e. if it
+        has this level or higher privileges::
+
+            >>> bot.channels['#chan'].privileges[bot.nick] = plugin.OP
+            >>> bot.has_channel_privilege('#chan', plugin.VOICE)
+            True
+
+        The ``channel`` argument can be either a :class:`str` or a
+        :class:`sopel.tools.Identifier`, as long as Sopel joined said channel.
+        If the channel is unknown, a :exc:`ValueError` will be raised.
+        """
+        if channel not in self.channels:
+            raise ValueError('Unknown channel %s' % channel)
+
+        return self.channels[channel].has_privilege(self.nick, privilege)
+
     # signal handlers
 
     def set_signal_handlers(self):

sopel/modules/adminchannel.py

@@ -28,16 +28,14 @@ def default_mask(trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.OP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('op')
 def op(bot, trigger):
     """
     Command to op users in a room. If no nick is given,
     Sopel will op the nick who sent the command
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.OP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     nick = trigger.group(2)
     channel = trigger.sender
     if not nick:
@@ -46,16 +44,14 @@ def op(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.OP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('deop')
 def deop(bot, trigger):
     """
     Command to deop users in a room. If no nick is given,
     Sopel will deop the nick who sent the command
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.OP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     nick = trigger.group(2)
     channel = trigger.sender
     if not nick:
@@ -64,16 +60,14 @@ def deop(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.HALFOP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('voice')
 def voice(bot, trigger):
     """
     Command to voice users in a room. If no nick is given,
     Sopel will voice the nick who sent the command
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     nick = trigger.group(2)
     channel = trigger.sender
     if not nick:
@@ -82,16 +76,14 @@ def voice(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.HALFOP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('devoice')
 def devoice(bot, trigger):
     """
     Command to devoice users in a room. If no nick is given,
     Sopel will devoice the nick who sent the command
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     nick = trigger.group(2)
     channel = trigger.sender
     if not nick:
@@ -100,14 +92,12 @@ def devoice(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.HALFOP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('kick')
 @plugin.priority('high')
 def kick(bot, trigger):
     """Kick a user from the channel."""
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     text = trigger.group().split()
     argc = len(text)
     if argc < 2:
@@ -153,17 +143,15 @@ def configureHostMask(mask):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.HALFOP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('ban')
 @plugin.priority('high')
 def ban(bot, trigger):
     """Ban a user from the channel
 
     The bot must be a channel operator for this command to work.
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     text = trigger.group().split()
     argc = len(text)
     if argc < 2:
@@ -183,16 +171,14 @@ def ban(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.HALFOP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('unban')
 def unban(bot, trigger):
     """Unban a user from the channel
 
     The bot must be a channel operator for this command to work.
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     text = trigger.group().split()
     argc = len(text)
     if argc < 2:
@@ -212,16 +198,14 @@ def unban(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.OP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('quiet')
 def quiet(bot, trigger):
     """Quiet a user
 
     The bot must be a channel operator for this command to work.
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.OP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     text = trigger.group().split()
     argc = len(text)
     if argc < 2:
@@ -241,16 +225,14 @@ def quiet(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.OP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('unquiet')
 def unquiet(bot, trigger):
     """Unquiet a user
 
     The bot must be a channel operator for this command to work.
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.OP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     text = trigger.group().split()
     argc = len(text)
     if argc < 2:
@@ -270,7 +252,8 @@ def unquiet(bot, trigger):
 
 
 @plugin.require_chanmsg
-@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
+@plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV, reply=True)
+@plugin.require_bot_privilege(plugin.OP, ERROR_MESSAGE_NOT_OP, reply=True)
 @plugin.command('kickban', 'kb')
 @plugin.example('.kickban [#chan] user1 user!*@* get out of here')
 @plugin.priority('high')
@@ -279,9 +262,6 @@ def kickban(bot, trigger):
 
     The bot must be a channel operator for this command to work.
     """
-    if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
-        bot.reply(ERROR_MESSAGE_NOT_OP)
-        return
     text = trigger.group().split()
     argc = len(text)
     if argc < 4:

sopel/plugin.py

@@ -35,6 +35,7 @@
     'rate',
     'require_account',
     'require_admin',
+    'require_bot_privilege',
     'require_chanmsg',
     'require_owner',
     'require_privilege',
@@ -68,6 +69,13 @@
 """Privilege level for the +h channel permission
 
 .. versionadded:: 4.1
+
+.. important::
+
+    Not all IRC networks support this privilege mode. If you are writing a
+    plugin for public distribution, ensure your code behaves sensibly if only
+    ``+v`` (voice) and ``+o`` (op) modes exist.
+
 """
 
 OP = 4
@@ -80,12 +88,26 @@
 """Privilege level for the +a channel permission
 
 .. versionadded:: 4.1
+
+.. important::
+
+    Not all IRC networks support this privilege mode. If you are writing a
+    plugin for public distribution, ensure your code behaves sensibly if only
+    ``+v`` (voice) and ``+o`` (op) modes exist.
+
 """
 
 OWNER = 16
 """Privilege level for the +q channel permission
 
 .. versionadded:: 4.1
+
+.. important::
+
+    Not all IRC networks support this privilege mode. If you are writing a
+    plugin for public distribution, ensure your code behaves sensibly if only
+    ``+v`` (voice) and ``+o`` (op) modes exist.
+
 """
 
 OPER = 32
@@ -95,6 +117,13 @@
 store any user's OPER status.
 
 .. versionadded:: 7.0.0
+
+.. important::
+
+    Not all IRC networks support this privilege mode. If you are writing a
+    plugin for public distribution, ensure your code behaves sensibly if only
+    ``+v`` (voice) and ``+o`` (op) modes exist.
+
 """
 
 
@@ -927,6 +956,45 @@ def guarded(bot, trigger, *args, **kwargs):
     return actual_decorator
 
 
+def require_bot_privilege(level, message=None, reply=False):
+    """Decorate a function to require a minimum channel privilege for the bot.
+
+    :param int level: minimum channel privilege the bot needs for this function
+    :param str message: optional message said if the bot's channel privilege
+                        level is insufficient
+    :param bool reply: use :meth:`~.bot.Sopel.reply` instead of
+                       :meth:`~.bot.Sopel.say` when ``True``; defaults to
+                       ``False``
+
+    ``level`` can be one of the privilege level constants defined in this
+    module. If the bot does not have the privilege, the bot will say
+    ``message`` if given. By default, it uses :meth:`bot.say()
+    <.bot.Sopel.say>`, but when ``reply`` is true, then it uses
+    :meth:`bot.reply() <.bot.Sopel.reply>` instead.
+
+    Privilege requirements are ignored in private messages.
+
+    .. versionadded:: 7.1
+    """
+    def actual_decorator(function):
+        @functools.wraps(function)
+        def guarded(bot, trigger, *args, **kwargs):
+            # If this is a privmsg, ignore privilege requirements
+            if trigger.is_privmsg:
+                return function(bot, trigger, *args, **kwargs)
+
+            if not bot.has_channel_privilege(trigger.sender, level):
+                if message and not callable(message):
+                    if reply:
+                        bot.reply(message)
+                    else:
+                        bot.say(message)
+            else:
+                return function(bot, trigger, *args, **kwargs)
+        return guarded
+    return actual_decorator
+
+
 def url(*url_rules):
     """Decorate a function to handle URLs.