Adding new CogSetting to make guild config easier to implement

cogs/basecog.py

@@ -277,9 +277,39 @@ class BotMessage:
 
 		return s
 
+class CogSetting:
+	def __init__(self,
+			name: str,
+			brief: str = None,
+			description: str = None,
+			usage: str = None,
+			min_value = None,
+			max_value = None,
+			enum_values: set = None):
+		self.name = name
+		self.brief = brief
+		self.description = description or ''  # XXX: Can't be None
+		self.usage = usage
+		self.min_value = min_value
+		self.max_value = max_value
+		self.enum_values = enum_values
+		if self.enum_values or self.min_value is not None or self.max_value is not None:
+			self.description += '\n'
+		if self.enum_values:
+			allowed_values = '`' + ('`, `'.join(enum_values)) + '`'
+			self.description += f'\nAllowed values: {allowed_values}'
+		if self.min_value is not None:
+			self.description += f'\nMin value: {self.min_value}'
+		if self.max_value is not None:
+			self.description += f'\nMax value: {self.max_value}'
+		if self.usage is None:
+			self.usage = f'<{self.name}>'
+
 class BaseCog(commands.Cog):
 	def __init__(self, bot):
 		self.bot = bot
+		self.are_settings_setup = False
+		self.settings = []
 
 	# Config
 
@@ -295,6 +325,147 @@ class BaseCog(commands.Cog):
 			return None
 		return cog.get(key)
 
+	def add_setting(self, setting: CogSetting) -> None:
+		"""
+		Called by a subclass in __init__ to register a mod-configurable
+		guild setting. A "get" and "set" command will be generated. If the cog
+		has a command group it will be detected automatically and the commands
+		added to that. Otherwise the commands will be added at the top level.
+		"""
+		self.settings.append(setting)
+
+	@classmethod
+	def get_guild_setting(cls,
+			guild: Guild,
+			setting: CogSetting,
+			use_cog_default_if_not_set: bool = True):
+		"""
+		Returns the configured value for a setting for the given guild. If no
+		setting is configured the default for the cog will be returned,
+		unless the optional `use_cog_default_if_not_set` is `False`, then
+		`None` will be returned.
+		"""
+		key = f'{cls.__name__}.{setting.name}'
+		value = Storage.get_config_value(guild, key)
+		if value is None and use_cog_default_if_not_set:
+			value = cls.get_cog_default(setting.name)
+		return value
+
+	@classmethod
+	def set_guild_setting(cls,
+			guild: Guild,
+			setting: CogSetting,
+			new_value) -> None:
+		"""
+		Manually sets a setting for the given guild. BaseCog creates "get" and
+		"set" commands for guild administrators to configure values themselves,
+		but this method can be used for hidden settings from code.
+		"""
+		key = f'{cls.__name__}.{setting.name}'
+		Storage.set_config_value(guild, key, new_value)
+
+	@commands.Cog.listener()
+	async def on_ready(self):
+		if self.are_settings_setup:
+			return
+		group: commands.core.Group = None
+		for member_name in dir(self):
+			member = getattr(self, member_name)
+			if isinstance(member, commands.core.Group):
+				group = member
+				break
+		lookup = {}
+		for setting in self.settings:
+			# Manually constructing equivalent of:
+			# 	@commands.command(
+			# 		brief='Posts a test warning in the configured warning channel.'
+			# 	)
+			# 	@commands.has_permissions(ban_members=True)
+			# 	@commands.guild_only()
+			# 	async def get/setvar(self, context, ...):
+			async def _set_setting(self, context, new_value):
+				s = lookup[context.command.name]
+				await self.__set_setting(context, new_value, s)
+			async def _get_setting(self, context):
+				s = lookup[context.command.name]
+				await self.__get_setting(context, s)
+
+			set_command = commands.Command(
+				_set_setting,
+				name=f'set{setting.name}',
+				brief=f'Sets {setting.brief}',
+				description=setting.description,
+				usage=setting.usage,
+				checks=[
+					commands.has_permissions(ban_members=True),
+					commands.guild_only(),
+				])
+			# XXX: Passing `cog` in init gets ignored and set to `None`.
+			set_command.cog = self
+			get_command = commands.Command(
+				_get_setting,
+				name=f'get{setting.name}',
+				brief=f'Shows {setting.brief}',
+				description=setting.description,
+				checks=[
+					commands.has_permissions(ban_members=True),
+					commands.guild_only(),
+				])
+			get_command.cog = self
+
+			if group:
+				group.add_command(get_command)
+				group.add_command(set_command)
+			else:
+				self.bot.add_command(get_command)
+				self.bot.add_command(set_command)
+
+			lookup[set_command.name] = setting
+			lookup[get_command.name] = setting
+		self.are_settings_setup = True
+
+	async def __set_setting(self, context, new_value, setting) -> None:
+		setting_name = setting.name
+		if context.command.parent:
+			setting_name = f'{context.command.parent.name}.{setting_name}'
+		if setting.min_value is not None and new_value < setting.min_value:
+			await context.message.reply(
+				f'{CONFIG["failure_emoji"]} `{setting_name}` must be >= {setting.min_value}',
+				mention_author=False)
+			return
+		if setting.max_value is not None and new_value > setting.max_value:
+			await context.message.reply(
+				f'{CONFIG["failure_emoji"]} `{setting_name}` must be <= {setting.max_value}',
+				mention_author=False)
+			return
+		if setting.enum_values is not None and new_value not in setting.enum_values:
+			allowed_values = '`' + ('`, `'.join(setting.enum_values)) + '`'
+			await context.message.reply(
+				f'{CONFIG["failure_emoji"]} `{setting_name}` must be one of {allowed_values}',
+				mention_author=False)
+			return
+		key = f'{self.__class__.__name__}.{setting.name}'
+		Storage.set_config_value(context.guild, key, new_value)
+		await context.message.reply(
+			f'{CONFIG["success_emoji"]} `{setting_name}` is now set to `{new_value}`',
+			mention_author=False)
+
+	async def __get_setting(self, context, setting) -> None:
+		setting_name = setting.name
+		if context.command.parent:
+			setting_name = f'{context.command.parent.name}.{setting_name}'
+		key = f'{self.__class__.__name__}.{setting.name}'
+		value = Storage.get_config_value(context.guild, key)
+		if value is None:
+			value = self.get_cog_default(setting.name)
+			await context.message.reply(
+				f'{CONFIG["info_emoji"]} `{setting_name}` is using default of `{value}`',
+				mention_author=False)
+		else:
+			await context.message.reply(
+				f'{CONFIG["info_emoji"]} `{setting_name}` is set to `{value}`',
+				mention_author=False)
+
 	# Bot message handling
 
 	@classmethod
@@ -442,7 +613,3 @@ class BaseCog(commands.Cog):
 	def log(cls, guild: Guild, message) -> None:
 		now = datetime.now()
 		print(f'[{now.strftime("%Y-%m-%dT%H:%M:%S")}|{cls.__name__}|{guild.name}] {message}')
-
-	@classmethod
-	def deprecated_guild_trace(cls, guild: Guild, message: str) -> None:
-		print(f'[guild {guild.id}|{guild.name}] {message}')

cogs/urlspamcog.py

@@ -3,7 +3,7 @@ from discord.ext import commands
 import re
 from datetime import timedelta
 
-from cogs.basecog import BaseCog, BotMessage, BotMessageReaction
+from cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
 from config import CONFIG
 from storage import Storage
 
@@ -15,19 +15,35 @@ class URLSpamContext:
 		self.is_banned = False
 
 class URLSpamCog(BaseCog):
-	CONFIG_KEY_EARLY_URL_TIMEOUT = "urlspam_early_url_timeout"
-	CONFIG_KEY_EARLY_URL_ACTION = "urlspam_early_url_action"
+	SETTING_ACTION = CogSetting('action',
+			brief='action to take on spam',
+			description='The action to take on detected URL spam.',
+			enum_values=set(['nothing', 'modwarn', 'delete', 'kick', 'ban']))
+	SETTING_JOIN_AGE = CogSetting('joinage',
+			brief='seconds since member joined',
+			description='The minimum seconds since the user joined the ' + \
+				'server before they can post URLs. URLs posted by users ' + \
+				'who joined too recently will be flagged. Keep in mind ' + \
+				'many servers have a minimum 10 minute cooldown before ' + \
+				'new members can say anything. Setting to 0 effectively ' + \
+				'disables URL spam detection.',
+			usage='<seconds:int>',
+			min_value=0)
 
 	def __init__(self, bot):
 		super().__init__(bot)
+		self.add_setting(URLSpamCog.SETTING_ACTION)
+		self.add_setting(URLSpamCog.SETTING_JOIN_AGE)
 
-	def __early_url_timeout(self, guild: Guild) -> int:
-		return Storage.get_config_value(guild, self.CONFIG_KEY_EARLY_URL_TIMEOUT) or \
-			self.get_cog_default('early_url_timeout')
-
-	def __early_url_action(self, guild: Guild) -> str:
-		return Storage.get_config_value(guild, self.CONFIG_KEY_EARLY_URL_ACTION) or \
-			self.get_cog_default('early_url_action')
+	@commands.group(
+		brief='Manages URL spam detection',
+	)
+	@commands.has_permissions(ban_members=True)
+	@commands.guild_only()
+	async def urlspam(self, context: commands.Context):
+		'Command group'
+		if context.invoked_subcommand is None:
+			await context.send_help()
 
 	@commands.Cog.listener()
 	async def on_message(self, message: Message):
@@ -38,69 +54,54 @@ class URLSpamCog(BaseCog):
 				message.content is None:
 			return
 
-		action = self.__early_url_action(message.guild)
+		action = self.get_guild_setting(message.guild, self.SETTING_ACTION)
+		min_join_age = timedelta(seconds=self.get_guild_setting(message.guild, self.SETTING_JOIN_AGE))
 		if action == 'nothing':
 			return
 		if not self.__contains_url(message.content):
 			return
 		join_age = message.created_at - message.author.joined_at
 		join_age_str = self.__format_timedelta(join_age)
-		if join_age.total_seconds() < self.__early_url_timeout(message.guild):
+		if join_age < min_join_age:
+			context = URLSpamContext(message)
+			needs_attention = False
 			if action == 'modwarn':
-				bm = BotMessage(
-					message.guild,
-					f'User {message.author.mention} posted a URL ' + \
-					f'{join_age_str} after joining.',
-					type = BotMessage.TYPE_MOD_WARNING,
-					context = URLSpamContext(message))
-				bm.quote = message.content
-				await bm.add_reaction(BotMessageReaction(CONFIG['trash_emoji'], True, 'Delete message'))
-				await bm.add_reaction(BotMessageReaction(CONFIG['kick_emoji'], True, 'Kick user'))
-				await bm.add_reaction(BotMessageReaction(CONFIG['ban_emoji'], True, 'Ban user'))
-				await self.post_message(bm)
+				needs_attention = True
 				self.log(message.guild, f'New user {message.author.name} ' + \
 					f'({message.author.id}) posted URL. Mods alerted.')
 			elif action == 'delete':
 				await message.delete()
-				bm = BotMessage(
-					message.guild,
-					f'User {message.author.mention} posted a URL ' + \
-					f'{join_age_str} after joining. Message deleted.',
-					type = BotMessage.TYPE_INFO,
-					context = URLSpamContext(message))
-				bm.quote = message.content
-				await bm.add_reaction(BotMessageReaction(CONFIG['kick_emoji'], True, 'Kick user'))
-				await bm.add_reaction(BotMessageReaction(CONFIG['ban_emoji'], True, 'Ban user'))
-				await self.post_message(bm)
+				context.is_deleted = True
 				self.log(message.guild, f'New user {message.author.name} ' + \
 					f'({message.author.id}) posted URL. Message deleted.')
 			elif action == 'kick':
+				await message.delete()
+				context.is_deleted = True
 				await message.author.kick(reason='User posted a link ' + \
 					f'{join_age_str} after joining')
-				bm = BotMessage(
-					message.guild,
-					f'User {message.author.mention} posted a URL ' + \
-					f'{join_age_str} after joining. Kicked by bot.',
-					type = BotMessage.TYPE_INFO,
-					context = URLSpamContext(message))
-				bm.quote = message.content
-				await bm.add_reaction(BotMessageReaction(CONFIG['ban_emoji'], True, 'Ban user'))
-				await self.post_message(bm)
+				context.is_kicked = True
 				self.log(message.guild, f'New user {message.author.name} ' + \
 					f'({message.author.id}) posted URL. User kicked.')
 			elif action == 'ban':
 				await message.author.ban(reason='User posted a link ' + \
 					f'{join_age_str} after joining', delete_message_days=1)
-				bm = BotMessage(
-					message.guild,
-					f'User {message.author.mention} posted a URL ' + \
-					f'{join_age_str} after joining. Banned by bot.',
-					type = BotMessage.TYPE_INFO,
-					context = URLSpamContext(message))
-				bm.quote = message.content
-				await self.post_message(bm)
+				context.is_deleted = True
+				context.is_kicked = True
+				context.is_banned = True
 				self.log(message.guild, f'New user {message.author.name} ' + \
 					f'({message.author.id}) posted URL. User banned.')
+			bm = BotMessage(
+					message.guild,
+					f'User {message.author.mention} posted a URL ' + \
+					f'{join_age_str} after joining.',
+					type = BotMessage.TYPE_MOD_WARNING if needs_attention else BotMessage.TYPE_INFO,
+					context = context)
+			bm.quote = message.content
+			await bm.set_reactions(BotMessageReaction.standard_set(
+				did_delete=context.is_deleted,
+				did_kick=context.is_kicked,
+				did_ban=context.is_banned))
+			await self.post_message(bm)
 
 	async def on_mod_react(self,
 			bot_message: BotMessage,
@@ -137,11 +138,13 @@ class URLSpamCog(BaseCog):
 			did_kick=context.is_kicked,
 			did_ban=context.is_banned))
 
-	def __contains_url(self, text: str) -> bool:
+	@classmethod
+	def __contains_url(cls, text: str) -> bool:
 		p = re.compile(r'http(?:s)?://[^\s]+')
 		return p.search(text) is not None
 
-	def __format_timedelta(self, timespan: timedelta) -> str:
+	@classmethod
+	def __format_timedelta(cls, timespan: timedelta) -> str:
 		parts = []
 		d = timespan.days
 		h = timespan.seconds // 3600

config.py.sample

@@ -1,6 +1,6 @@
 # Copy this file to config.py and fill in necessary values
 CONFIG = {
-	'__config_version': 1,
+	'__config_version': 2,
 	'client_token': 'token',
 	'command_prefix': '$rb_',
 	'kick_emoji': '👢',
@@ -24,8 +24,8 @@ CONFIG = {
 			'min_message_length': 0,
 		},
 		'URLSpamCog': {
-			'early_url_timeout': 900,  # Should be > 10m due to Discord-imposed waiting period
-			'early_url_action': 'modwarn', # "nothing" | "modwarn" | "delete" | "kick" | "ban"
+			'joinage': 900,  # Should be > 600 due to Discord-imposed waiting period
+			'action': 'nothing',  # "nothing" | "modwarn" | "delete" | "kick" | "ban"
 		},
 	},
 }

rocketbot.py

@@ -16,7 +16,7 @@ from cogs.joinraidcog import JoinRaidCog
 from cogs.patterncog import PatternCog
 from cogs.urlspamcog import URLSpamCog
 
-CURRENT_CONFIG_VERSION = 1
+CURRENT_CONFIG_VERSION = 2
 if (CONFIG.get('__config_version') or 0) < CURRENT_CONFIG_VERSION:
     raise RuntimeError('config.py format may be outdated. Review ' +
         'config.py.sample, update the "__config_version" field to ' +