g1mp/plugins/services/administration.py

# -*- coding: utf-8 -*-
"""
IRC Bot Plugins: Voice, Kick, and Ban Management

This module provides three IRC bot plugins:
1. `VoicePlugin`: Handles granting and revoking voice (+v) privileges.
2. `KickPlugin`: Handles kicking users from the channel.
3. `BanPlugin`: Handles banning and unbanning users.

All commands require **admin** permissions.

Features:
- Voice a single user or all users in a channel.
- Devoice a single user or all users.
- Kick users with optional reasons.
- Ban and unban users.

Author: Zodiac (Modified for verbose logging by bot.log)
"""

import asyncio
import irc3
from irc3.plugins.command import command


@irc3.plugin
class VoicePlugin:
    """A plugin to manage voice (+v) privileges in an IRC channel."""

    def __init__(self, bot):
        """
        Initialize the VoicePlugin.

        Args:
            bot (irc3.IrcBot): The IRC bot instance.
        """
        self.bot = bot

    @command(permission='admin')
    async def voice(self, mask, target, args):
        """
        Grant voice to a specific user or all users in the channel.

        Usage:
            %%voice [<nick>]
        """
        nick = args.get('<nick>')
        if nick:
            self.bot.log.info("Request to grant voice to %s in %s", nick, target)
            await self.give_voice(target, nick)
        else:
            self.bot.log.info("Request to grant voice to all users in %s", target)
            await self.give_voice_all(target)

    @command(permission='admin')
    async def devoice(self, mask, target, args):
        """
        Remove voice from a specific user or all users in the channel.

        Usage:
            %%devoice [<nick>]
        """
        nick = args.get('<nick>')
        if nick:
            self.bot.log.info("Request to remove voice from %s in %s", nick, target)
            await self.remove_voice(target, nick)
        else:
            self.bot.log.info("Request to remove voice from all users in %s", target)
            await self.remove_voice_all(target)

    async def give_voice(self, target, nick):
        """
        Grant voice to a specific user.

        Args:
            target (str): The IRC channel.
            nick (str): The nickname of the user.
        """
        self.bot.log.info("Granting voice to user %s in channel %s", nick, target)
        self.bot.send(f'MODE {target} +v {nick}')

    async def remove_voice(self, target, nick):
        """
        Remove voice from a specific user.

        Args:
            target (str): The IRC channel.
            nick (str): The nickname of the user.
        """
        self.bot.log.info("Removing voice from user %s in channel %s", nick, target)
        self.bot.send(f'MODE {target} -v {nick}')

    async def give_voice_all(self, target):
        """
        Grant voice to all users in the channel who do not have it.

        Args:
            target (str): The IRC channel.
        """
        self.bot.log.info("Granting voice to all non-voiced users in channel %s", target)
        names = await self.bot.async_cmds.names(target)
        for user in names['names']:
            if not user.startswith(("+", "@")):  # Ignore voiced/opped users
                self.bot.log.info("Granting voice to user %s", user)
                self.bot.send(f'MODE {target} +v {user}')
                await asyncio.sleep(0.07)  # Prevent server flooding

    async def remove_voice_all(self, target):
        """
        Remove voice from all users in the channel.

        Args:
            target (str): The IRC channel.
        """
        self.bot.log.info("Removing voice from all voiced users in channel %s", target)
        names = await self.bot.async_cmds.names(target)
        for user in names['names']:
            if user.startswith("+"):  # Only devoice voiced users
                actual_user = user.lstrip("+")
                self.bot.log.info("Removing voice from user %s", actual_user)
                self.bot.send(f'MODE {target} -v {actual_user}')
                await asyncio.sleep(0.07)  # Prevent server flooding


@irc3.plugin
class KickPlugin:
    """A plugin to kick users from an IRC channel."""

    def __init__(self, bot):
        """
        Initialize the KickPlugin.

        Args:
            bot (irc3.IrcBot): The IRC bot instance.
        """
        self.bot = bot

    @command(permission='admin')
    async def kick(self, mask, target, args):
        """
        Kick a specific user from the channel with an optional reason.

        Usage:
            %%kick <nick> [<reason>]
        """
        nick = args.get('<nick>')
        reason = args.get('<reason>') or 'Kicked by admin'
        if nick:
            self.bot.log.info("Request to kick user %s from channel %s for reason: %s", nick, target, reason)
            await self.kick_user(target, nick, reason)

    async def kick_user(self, target, nick, reason):
        """
        Kick a user from the channel using ChanServ.

        Args:
            target (str): The IRC channel.
            nick (str): The nickname of the user.
            reason (str): The reason for kicking the user.
        """
        self.bot.log.info("Kicking user %s from channel %s", nick, target)
        self.bot.send(f'PRIVMSG ChanServ :KICK {target} {nick} {reason}')


@irc3.plugin
class BanPlugin:
    """A plugin to ban and unban users in an IRC channel."""

    def __init__(self, bot):
        """
        Initialize the BanPlugin.

        Args:
            bot (irc3.IrcBot): The IRC bot instance.
        """
        self.bot = bot

    @command(permission='admin')
    async def ban(self, mask, target, args):
        """
        Ban a specific user from the channel.

        Usage:
            %%ban <nick>
        """
        nick = args.get('<nick>')
        if nick:
            self.bot.log.info("Request to ban user %s from channel %s", nick, target)
            await self.ban_user(target, nick)

    @command(permission='admin')
    async def unban(self, mask, target, args):
        """
        Unban a specific user from the channel.

        Usage:
            %%unban <nick>
        """
        nick = args.get('<nick>')
        if nick:
            self.bot.log.info("Request to unban user %s from channel %s", nick, target)
            await self.unban_user(target, nick)

    async def ban_user(self, target, nick):
        """
        Ban a specific user from the channel.

        Args:
            target (str): The IRC channel.
            nick (str): The nickname of the user.
        """
        self.bot.log.info("Banning user %s in channel %s", nick, target)
        self.bot.send(f'MODE {target} +b {nick}')

    async def unban_user(self, target, nick):
        """
        Unban a specific user from the channel.

        Args:
            target (str): The IRC channel.
            nick (str): The nickname of the user.
        """
        self.bot.log.info("Unbanning user %s in channel %s", nick, target)
        self.bot.send(f'MODE {target} -b {nick}')