Llllllots of cleanup after switching to VSCode

.pylintrc

@@ -0,0 +1,6 @@
+[MESSAGES CONTROL]
+disable=bad-indentation, invalid-name
+
+[FORMAT]
+
+indent-string=' '

cogs/basecog.py

@@ -1,12 +1,11 @@
+from datetime import datetime, timedelta
 from discord import Guild, Member, Message, PartialEmoji, RawReactionActionEvent, TextChannel
+from discord.abc import GuildChannel
 from discord.ext import commands
-from datetime import datetime, timedelta
 
-from abc import ABC, abstractmethod
 from config import CONFIG
 from rscollections import AgeBoundDict
 from storage import ConfigKey, Storage
-import json
 
 class BotMessageReaction:
 	"""
@@ -136,18 +135,23 @@ class BotMessage:
 		return self.__message is not None
 
 	def message_id(self):
+		'Returns the Message id or None if not sent.'
 		return self.__message.id if self.__message else None
 
-	def message_sent_at(self):
+	def message_sent_at(self) -> datetime:
+		'Returns when the message was sent or None if not sent.'
 		return self.__message.created_at if self.__message else None
 
+	def has_reactions(self) -> bool:
+		return len(self.__reactions) > 0
+
 	async def set_text(self, new_text: str) -> None:
 		"""
 		Replaces the text of this message. If the message has been sent, it will
 		be updated.
 		"""
 		self.text = new_text
-		await self.__update_if_sent()
+		await self.update_if_sent()
 
 	async def set_reactions(self, reactions: list) -> None:
 		"""
@@ -158,7 +162,7 @@ class BotMessage:
 			# No change
 			return
 		self.__reactions = reactions.copy() if reactions is not None else []
-		await self.__update_if_sent()
+		await self.update_if_sent()
 
 	async def add_reaction(self, reaction: BotMessageReaction) -> None:
 		"""
@@ -175,8 +179,7 @@ class BotMessage:
 		will be updated.
 		"""
 		found = False
-		for i in range(len(self.__reactions)):
-			existing = self.__reactions[i]
+		for i, existing in enumerate(self.__reactions):
 			if existing.emoji == reaction.emoji:
 				if reaction == self.__reactions[i]:
 					# No change
@@ -186,34 +189,47 @@ class BotMessage:
 				break
 		if not found:
 			self.__reactions.append(reaction)
-		await self.__update_if_sent()
+		await self.update_if_sent()
 
 	async def remove_reaction(self, reaction_or_emoji) -> None:
 		"""
 		Removes a reaction. Can pass either a BotMessageReaction or just the
 		emoji string. If the message has been sent, it will be updated.
 		"""
-		for i in range(len(self.__reactions)):
-			existing = self.__reactions[i]
+		for i, existing in enumerate(self.__reactions):
 			if (isinstance(reaction_or_emoji, str) and existing.emoji == reaction_or_emoji) or \
-				(isinstance(reaction_or_emoji, BotMessageReaction) and existing.emoji == reaction_or_emoji.emoji):
+				(isinstance(reaction_or_emoji, BotMessageReaction) and \
+					existing.emoji == reaction_or_emoji.emoji):
 				self.__reactions.pop(i)
-				await self.__update_if_sent()
+				await self.update_if_sent()
 				return
 
 	def reaction_for_emoji(self, emoji) -> BotMessageReaction:
+		"""
+		Finds the BotMessageReaction for the given emoji or None if not found.
+		Accepts either a PartialEmoji or str.
+		"""
 		for reaction in self.__reactions:
 			if isinstance(emoji, PartialEmoji) and reaction.emoji == emoji.name:
 				return reaction
-			elif isinstance(emoji, str) and reaction.emoji == emoji:
+			if isinstance(emoji, str) and reaction.emoji == emoji:
 				return reaction
 		return None
 
-	async def __update_if_sent(self) -> None:
+	async def update_if_sent(self) -> None:
+		"""
+		Updates the text and/or reactions on a message if it was sent to
+		the guild, otherwise does nothing. Does not need to be called by
+		BaseCog subclasses.
+		"""
 		if self.__message:
-			await self._update()
+			await self.update()
 
-	async def _update(self) -> None:
+	async def update(self) -> None:
+		"""
+		Sends or updates an already sent message based on BotMessage state.
+		Does not need to be called by BaseCog subclasses.
+		"""
 		content: str = self.__formatted_message()
 		if self.__message:
 			if content != self.__posted_text:
@@ -278,6 +294,12 @@ class BotMessage:
 		return s
 
 class CogSetting:
+	"""
+	Describes a configuration setting for a guild that can be edited by the
+	mods of those guilds. BaseCog can generate "get" and "set" commands
+	automatically, reducing the boilerplate of generating commands manually.
+	Offers simple validation rules.
+	"""
 	def __init__(self,
 			name: str,
 			datatype,
@@ -287,6 +309,23 @@ class CogSetting:
 			min_value = None,
 			max_value = None,
 			enum_values: set = None):
+		"""
+		Params:
+		- name         Setting identifier. Must follow variable naming
+		               conventions.
+		- datatype     Datatype of the setting. E.g. int, float, str
+		- brief        Description of the setting, starting with lower case.
+		               Will be inserted into phrases like "Sets <brief>" and
+					   "Gets <brief".
+		- description  Long-form description. Min, max, and enum values will be
+		               appended to the end, so does not need to include these.
+		- usage        Description of the value argument in a set command, e.g.
+		               "<maxcount:int>"
+		- min_value    Smallest allowable value. Must be of the same datatype as
+		               the value. None for no minimum.
+		- max_value    Largest allowable value. None for no maximum.
+		- enum_values  Set of allowed values. None if unconstrained.
+		"""
 		self.name = name
 		self.datatype = datatype
 		self.brief = brief
@@ -308,6 +347,10 @@ class CogSetting:
 			self.usage = f'<{self.name}>'
 
 class BaseCog(commands.Cog):
+	"""
+	Superclass for all Rocketbot cogs. Provides lots of conveniences for
+	common tasks.
+	"""
 	def __init__(self, bot):
 		self.bot = bot
 		self.are_settings_setup = False
@@ -319,7 +362,8 @@ class BaseCog(commands.Cog):
 	def get_cog_default(cls, key: str):
 		"""
 		Convenience method for getting a cog configuration default from
-		`CONFIG['cogs'][<cogname>][<key>]`.
+		`CONFIG['cogs'][<cogname>][<key>]`. These values are used for
+		CogSettings when no guild-specific value is configured yet.
 		"""
 		cogs: dict = CONFIG['cog_defaults']
 		cog = cogs.get(cls.__name__)
@@ -337,6 +381,8 @@ class BaseCog(commands.Cog):
 		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.
+
+		Changes to settings can be detected by overriding `on_setting_updated`.
 		"""
 		self.settings.append(setting)
 
@@ -365,13 +411,22 @@ class BaseCog(commands.Cog):
 		"""
 		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.
+		but this method can be used for hidden settings from code. A ValueError
+		will be raised if the new value does not pass validation specified in
+		the CogSetting.
 		"""
+		if setting.min_value is not None and new_value < setting.min_value:
+			raise ValueError(f'{setting.name} must be at least {setting.min_value}')
+		if setting.max_value is not None and new_value > setting.max_value:
+			raise ValueError(f'{setting.name} must be no more than {setting.max_value}')
+		if setting.enum_values and new_value not in setting.enum_values:
+			raise ValueError(f'{setting.name} must be one of {setting.enum_values}')
 		key = f'{cls.__name__}.{setting.name}'
 		Storage.set_config_value(guild, key, new_value)
 
 	@commands.Cog.listener()
 	async def on_ready(self):
+		'Event listener'
 		self.__set_up_setting_commands()
 
 	def __set_up_setting_commands(self):
@@ -406,9 +461,7 @@ class BaseCog(commands.Cog):
 		under the bot if `None`.
 		"""
 		# Manually constructing equivalent of:
-		# 	@commands.command(
-		# 		brief='Posts a test warning in the configured warning channel.'
-		# 	)
+		# 	@commands.command()
 		# 	@commands.has_permissions(ban_members=True)
 		# 	@commands.guild_only()
 		# 	async def getvar(self, context):
@@ -573,7 +626,6 @@ class BaseCog(commands.Cog):
 		"""
 		Subclass override point for being notified when a CogSetting is edited.
 		"""
-		pass
 
 	# Bot message handling
 
@@ -588,13 +640,17 @@ class BaseCog(commands.Cog):
 		return bm
 
 	async def post_message(self, message: BotMessage) -> bool:
+		"""
+		Posts a BotMessage to a guild. Returns whether it was successful. If
+		the caller wants to listen to reactions they should be added before
+		calling this method. Listen to reactions by overriding `on_mod_react`.
+		"""
 		message.source_cog = self
-		await message._update()
-		guild_messages = self.__bot_messages(message.guild)
-		if message.is_sent():
+		await message.update()
+		if message.has_reactions() and message.is_sent():
+			guild_messages = self.__bot_messages(message.guild)
 			guild_messages[message.message_id()] = message
-			return True
-		return False
+		return message.is_sent()
 
 	@commands.Cog.listener()
 	async def on_raw_reaction_add(self, payload: RawReactionActionEvent):
@@ -645,80 +701,13 @@ class BaseCog(commands.Cog):
 		Subclass override point for receiving mod reactions to bot messages sent
 		via `post_message()`.
 		"""
-		pass
 
 	# Helpers
 
 	@classmethod
-	async def validate_param(cls, context: commands.Context, param_name: str, value,
-		allowed_types: tuple = None,
-		min_value = None,
-		max_value = None) -> bool:
-		"""
-		Convenience method for validating a command parameter is of the expected
-		type and in the expected range. Bad values will cause a reply to be sent
-		to the original message and a False will be returned. If all checks
-		succeed, True will be returned.
-		"""
-		# TODO: Rework this to use BotMessage
-		if allowed_types is not None and not isinstance(value, allowed_types):
-			if len(allowed_types) == 1:
-				await context.message.reply(f'⚠️ `{param_name}` must be of type ' +
-					f'{allowed_types[0]}.', mention_author=False)
-			else:
-				await context.message.reply(f'⚠️ `{param_name}` must be of types ' +
-					f'{allowed_types}.', mention_author=False)
-			return False
-		if min_value is not None and value < min_value:
-			await context.message.reply(f'⚠️ `{param_name}` must be >= {min_value}.',
-				mention_author=False)
-			return False
-		if max_value is not None and value > max_value:
-			await context.message.reply(f'⚠️ `{param_name}` must be <= {max_value}.',
-				mention_author=False)
-		return True
-
-	@classmethod
-	async def warn(cls, guild: Guild, message: str) -> Message:
-		"""
-		DEPRECATED. Use post_message.
-
-		Sends a warning message to the configured warning channel for the
-		given guild. If no warning channel is configured no action is taken.
-		Returns the Message if successful or None if not.
-		"""
-		channel_id = Storage.get_config_value(guild, ConfigKey.WARNING_CHANNEL_ID)
-		if channel_id is None:
-			cls.log(guild, '\u0007No warning channel set! No warning issued.')
-			return None
-		channel: TextChannel = guild.get_channel(channel_id)
-		if channel is None:
-			cls.log(guild, '\u0007Configured warning channel does not exist!')
-			return None
-		mention: str = Storage.get_config_value(guild, ConfigKey.WARNING_MENTION)
-		text: str = message
-		if mention is not None:
-			text = f'{mention} {text}'
-		msg: Message = await channel.send(text)
-		return msg
-
-	@classmethod
-	async def update_warn(cls, warn_message: Message, new_text: str) -> None:
+	def log(cls, guild: Guild, message) -> None:
 		"""
-		DEPRECATED. Use post_message.
-
-		Updates the text of a previously posted `warn`. Includes configured
-		mentions if necessary.
+		Writes a message to the console. Intended for significant events only.
 		"""
-		text: str = new_text
-		mention: str = Storage.get_config_value(
-			warn_message.guild,
-			ConfigKey.WARNING_MENTION)
-		if mention is not None:
-			text = f'{mention} {text}'
-		await warn_message.edit(content=text)
-
-	@classmethod
-	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}')

cogs/configcog.py

@@ -5,33 +5,30 @@ from config import CONFIG
 from storage import ConfigKey, Storage
 from cogs.basecog import BaseCog
 
-class ConfigCog(BaseCog):
+class ConfigCog(BaseCog, name='Configuration'):
 	"""
 	Cog for handling general bot configuration.
 	"""
-	def __init__(self, bot):
-		super().__init__(bot)
-
 	@commands.group(
 		brief='Manages general bot configuration'
 	)
 	@commands.has_permissions(ban_members=True)
 	@commands.guild_only()
 	async def config(self, context: commands.Context):
-		'Command group'
+		'General guild configuration command group'
 		if context.invoked_subcommand is None:
 			await context.send_help()
 
 	@config.command(
-		name='setwarningchannel',
-		brief='Sets where to post mod warnings',
+		brief='Sets the mod warning channel',
 		description='Run this command in the channel where bot messages ' +
 			'intended for server moderators should be sent. Other bot ' +
 			'messages may still be posted in the channel a command was ' +
 			'invoked in. If no output channel is set, mod-related messages ' +
 			'will not be posted!',
 	)
-	async def config_setwarningchannel(self, context: commands.Context) -> None:
+	async def setwarningchannel(self, context: commands.Context) -> None:
+		'Command handler'
 		guild: Guild = context.guild
 		channel: TextChannel = context.channel
 		Storage.set_config_value(guild, ConfigKey.WARNING_CHANNEL_ID,
@@ -41,10 +38,12 @@ class ConfigCog(BaseCog):
 			mention_author=False)
 
 	@config.command(
-		name='getwarningchannel',
-		brief='Shows the channel where mod warnings are posted',
+		brief='Shows the mod warning channel',
+		description='Shows the configured channel (if any) where mod ' + \
+			'warnings will be posted.',
 	)
-	async def config_getwarningchannel(self, context: commands.Context) -> None:
+	async def getwarningchannel(self, context: commands.Context) -> None:
+		'Command handler'
 		guild: Guild = context.guild
 		channel_id = Storage.get_config_value(guild, ConfigKey.WARNING_CHANNEL_ID)
 		if channel_id is None:
@@ -58,7 +57,6 @@ class ConfigCog(BaseCog):
 				mention_author=False)
 
 	@config.command(
-		name='setwarningmention',
 		brief='Sets a user/role to mention in warning messages',
 		usage='<@user|@role>',
 		description='Configures an role or other prefix to include at the ' +
@@ -66,9 +64,10 @@ class ConfigCog(BaseCog):
 			'attention of certain users, be sure to specify a properly ' +
 			'formed @ tag, not just the name of the user/role.'
 	)
-	async def config_setwarningmention(self,
+	async def setwarningmention(self,
 			context: commands.Context,
 			mention: str = None) -> None:
+		'Command handler'
 		guild: Guild = context.guild
 		Storage.set_config_value(guild, ConfigKey.WARNING_MENTION, mention)
 		if mention is None:
@@ -81,12 +80,12 @@ class ConfigCog(BaseCog):
 				mention_author=False)
 
 	@config.command(
-		name='getwarningmention',
 		brief='Shows the user/role to mention in warning messages',
 		description='Shows the text, if any, that will be prefixed on any ' +
 			'warning messages.'
 	)
-	async def config_getwarningmention(self, context: commands.Context) -> None:
+	async def getwarningmention(self, context: commands.Context) -> None:
+		'Command handler'
 		guild: Guild = context.guild
 		mention: str = Storage.get_config_value(guild, ConfigKey.WARNING_MENTION)
 		if mention is None:

cogs/crosspostcog.py

@@ -1,5 +1,5 @@
 from datetime import datetime, timedelta
-from discord import Guild, Member, Message
+from discord import Member, Message
 from discord.ext import commands
 
 from cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
@@ -8,6 +8,9 @@ from rscollections import AgeBoundList, SizeBoundDict
 from storage import Storage
 
 class SpamContext:
+	"""
+	Data about a set of duplicate messages from a user.
+	"""
 	def __init__(self, member, message_hash):
 		self.member = member
 		self.message_hash = message_hash
@@ -20,7 +23,7 @@ class SpamContext:
 		self.deleted_messages = set()  # of Message
 		self.unique_channels = set()  # of TextChannel
 
-class CrossPostCog(BaseCog):
+class CrossPostCog(BaseCog, name='Crosspost Detection'):
 	"""
 	Detects a user posting the same text in multiple channels in a short period
 	of time: a common pattern for spammers. Repeated posts in the same channel
@@ -120,7 +123,6 @@ class CrossPostCog(BaseCog):
 				continue
 			key = f'{message.author.id}|{message_hash}'
 			context = spam_lookup.get(key)
-			is_new = context is None
 			if context is None:
 				context = SpamContext(message.author, message_hash)
 				spam_lookup[key] = context
@@ -139,7 +141,6 @@ class CrossPostCog(BaseCog):
 		channel_count = len(context.unique_channels)
 		if channel_count >= ban_count:
 			if not context.is_banned:
-				count = len(context.spam_messages)
 				await context.member.ban(
 					reason='Rocketbot: Posted same message in ' + \
 						f'{channel_count} channels. Banned by ' + \
@@ -227,6 +228,7 @@ class CrossPostCog(BaseCog):
 
 	@commands.Cog.listener()
 	async def on_message(self, message: Message):
+		'Event handler'
 		if message.author is None or \
 				message.author.bot or \
 				message.channel is None or \

cogs/generalcog.py

@@ -1,14 +1,18 @@
+import re
 from datetime import datetime, timedelta
-from discord import Member, Message
+from discord import Message
 from discord.ext import commands
-import re
 
 from cogs.basecog import BaseCog, BotMessage
 from config import CONFIG
 from rbutils import parse_timedelta, describe_timedelta
 from storage import ConfigKey, Storage
 
-class GeneralCog(BaseCog):
+class GeneralCog(BaseCog, name='General'):
+	"""
+	Cog for handling high-level bot functionality and commands. Should be the
+	first cog added to the bot.
+	"""
 	def __init__(self, bot: commands.Bot):
 		super().__init__(bot)
 		self.is_connected = False
@@ -16,20 +20,26 @@ class GeneralCog(BaseCog):
 
 	@commands.Cog.listener()
 	async def on_connect(self):
+		'Event handler'
 		print('on_connect')
 		self.is_connected = True
 
 	@commands.Cog.listener()
 	async def on_ready(self):
+		'Event handler'
 		print('on_ready')
 		self.is_ready = True
 
 	@commands.command(
-		brief='Posts a test warning in the configured warning channel.'
+		brief='Posts a test warning',
+		description='Tests whether a warning channel is configured for this ' + \
+			'guild by posting a test warning. If a mod mention is ' + \
+			'configured, that user/role will be tagged in the test warning.',
 	)
 	@commands.has_permissions(ban_members=True)
 	@commands.guild_only()
 	async def testwarn(self, context):
+		'Command handler'
 		if Storage.get_config_value(context.guild, ConfigKey.WARNING_CHANNEL_ID) is None:
 			await context.message.reply(
 				f'{CONFIG["warning_emoji"]} No warning channel set!',
@@ -43,30 +53,39 @@ class GeneralCog(BaseCog):
 
 	@commands.command(
 		brief='Simple test reply',
+		description='Replies to the command message. Useful to ensure the ' + \
+			'bot is working properly.',
 	)
 	async def hello(self, context):
+		'Command handler'
 		await context.message.reply(
 			f'Hey, {context.author.name}!',
 		 	mention_author=False)
 
 	@commands.command(
-		brief='Shuts down the bot (admin only)',
+		brief='Shuts down the bot',
+		description='Causes the bot script to terminate. Only usable by a ' + \
+			'user with server admin permissions.',
 	)
 	@commands.has_permissions(administrator=True)
 	@commands.guild_only()
-	async def shutdown(self, context):
+	async def shutdown(self, context: commands.Context):
+		'Command handler'
+		await context.message.add_reaction('👋')
 		await self.bot.close()
 
 	@commands.command(
 		brief='Mass deletes messages',
-		description='Deletes recent messages by the given user. The age is ' +
-			'a duration, such as "30s", "5m", "1h30m". Messages far back in ' +
-			'the scrollback might not be deleted by this command.',
-		usage='<user> <age>'
+		description='Deletes recent messages by the given user. The user ' +
+			'can be either an @ mention or a numeric user ID. The age is ' +
+			'a duration, such as "30s", "5m", "1h30m". Only the most ' +
+			'recent 100 messages in each channel are searched.',
+		usage='<user:id|mention> <age:timespan>'
 	)
 	@commands.has_permissions(manage_messages=True)
 	@commands.guild_only()
 	async def deletemessages(self, context, user: str, age: str) -> None:
+		'Command handler'
 		member_id = self.__parse_member_id(user)
 		if member_id is None:
 			await context.message.reply(

cogs/joinraidcog.py

@@ -1,7 +1,7 @@
+import weakref
 from datetime import datetime, timedelta
 from discord import Guild, Member
 from discord.ext import commands
-import weakref
 
 from cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
 from config import CONFIG
@@ -9,6 +9,9 @@ from rscollections import AgeBoundList
 from storage import Storage
 
 class JoinRaidContext:
+	"""
+	Data about a join raid.
+	"""
 	def __init__(self, join_members: list):
 		self.join_members = list(join_members)
 		self.kicked_members = set()
@@ -16,9 +19,10 @@ class JoinRaidContext:
 		self.warning_message_ref = None
 
 	def last_join_time(self) -> datetime:
+		'Returns when the most recent member join was, in UTC'
 		return self.join_members[-1].joined_at
 
-class JoinRaidCog(BaseCog):
+class JoinRaidCog(BaseCog, name='Join Raids'):
 	"""
 	Cog for monitoring member joins and detecting potential bot raids.
 	"""
@@ -40,7 +44,7 @@ class JoinRaidCog(BaseCog):
 			min_value=1.0,
 			max_value=900.0)
 
-	STATE_KEY_RECENT_JOINS = "JoinRaidCog.recent_joins"	
+	STATE_KEY_RECENT_JOINS = "JoinRaidCog.recent_joins"
 	STATE_KEY_LAST_RAID = "JoinRaidCog.last_raid"
 
 	def __init__(self, bot):
@@ -55,7 +59,7 @@ class JoinRaidCog(BaseCog):
 	@commands.has_permissions(ban_members=True)
 	@commands.guild_only()
 	async def joinraid(self, context: commands.Context):
-		'Command group'
+		'Join raid detection command group'
 		if context.invoked_subcommand is None:
 			await context.send_help()
 
@@ -64,7 +68,7 @@ class JoinRaidCog(BaseCog):
 			reaction: BotMessageReaction,
 			reacted_by: Member) -> None:
 		guild: Guild = bot_message.guild
-		raid: JoinRaidRecord = bot_message.context
+		raid: JoinRaidContext = bot_message.context
 		if reaction.emoji == CONFIG['kick_emoji']:
 			to_kick = set(raid.join_members) - raid.kicked_members
 			for member in to_kick:

cogs/patterncog.py

@@ -1,8 +1,7 @@
+import re
 from abc import ABC, abstractmethod
 from discord import Guild, Member, Message
 from discord.ext import commands
-from datetime import timedelta
-import re
 
 from cogs.basecog import BaseCog, BotMessage, BotMessageReaction
 from config import CONFIG
@@ -10,42 +9,58 @@ from rbutils import parse_timedelta
 from storage import Storage
 
 class PatternAction:
-	def __init__(self, type: str, args: list):
-		self.type = type
+	"""
+	Describes one action to take on a matched message or its author.
+	"""
+	def __init__(self, action: str, args: list):
+		self.action = action
 		self.arguments = list(args)
 
 	def __str__(self) -> str:
 		arg_str = ', '.join(self.arguments)
-		return f'{self.type}({arg_str})'
+		return f'{self.action}({arg_str})'
 
 class PatternExpression(ABC):
+	"""
+	Abstract message matching expression.
+	"""
 	def __init__(self):
 		pass
 
 	@abstractmethod
 	def matches(self, message: Message) -> bool:
+		"""
+		Whether a message matches this expression.
+		"""
 		return False
 
 class PatternSimpleExpression(PatternExpression):
+	"""
+	Message matching expression with a simple "<field> <operator> <value>"
+	structure.
+	"""
 	def __init__(self, field: str, operator: str, value):
+		super().__init__()
 		self.field = field
 		self.operator = operator
 		self.value = value
 
-	def matches(self, message: Message) -> bool:
-		field_value = None
+	def __field_value(self, message: Message):
 		if self.field == 'content':
-			field_value = message.content
-		elif self.field == 'author':
-			field_value = str(message.author.id)
-		elif self.field == 'author.id':
-			field_value = str(message.author.id)
-		elif self.field == 'author.joinage':
-			field_value = message.created_at - message.author.joined_at
-		elif self.field == 'author.name':
-			field_value = message.author.name
+			return message.content
+		if self.field == 'author':
+			return str(message.author.id)
+		if self.field == 'author.id':
+			return str(message.author.id)
+		if self.field == 'author.joinage':
+			return message.created_at - message.author.joined_at
+		if self.field == 'author.name':
+			return message.author.name
 		else:
 			raise ValueError(f'Bad field name {self.field}')
+
+	def matches(self, message: Message) -> bool:
+		field_value = self.__field_value(message)
 		if self.operator == '==':
 			if isinstance(field_value, str) and isinstance(self.value, str):
 				return field_value.lower() == self.value.lower()
@@ -78,35 +93,42 @@ class PatternSimpleExpression(PatternExpression):
 		return f'({self.field} {self.operator} {self.value})'
 
 class PatternCompoundExpression(PatternExpression):
+	"""
+	Message matching expression that combines several child expressions with
+	a boolean operator.
+	"""
 	def __init__(self, operator: str, operands: list):
+		super().__init__()
 		self.operator = operator
 		self.operands = list(operands)
 
 	def matches(self, message: Message) -> bool:
 		if self.operator == '!':
 			return not self.operands[0].matches(message)
-		elif self.operator == 'and':
+		if self.operator == 'and':
 			for op in self.operands:
 				if not op.matches(message):
 					return False
 			return True
-		elif self.operator == 'or':
+		if self.operator == 'or':
 			for op in self.operands:
 				if op.matches(message):
 					return True
 			return False
-		else:
-			raise RuntimeError(f'Bad operator "{self.operator}"')
+		raise RuntimeError(f'Bad operator "{self.operator}"')
 
 	def __str__(self) -> str:
 		if self.operator == '!':
 			return f'(!( {self.operands[0]} ))'
-		else:
-			strs = map(str, self.operands)
-			joined = f' {self.operator} '.join(strs)
-			return f'( {joined} )'
+		strs = map(str, self.operands)
+		joined = f' {self.operator} '.join(strs)
+		return f'( {joined} )'
 
 class PatternStatement:
+	"""
+	A full message match statement. If a message matches the given expression,
+	the given actions should be performed.
+	"""
 	def __init__(self, name: str, actions: list, expression: PatternExpression, original: str):
 		self.name = name
 		self.actions = list(actions)  # PatternAction[]
@@ -114,6 +136,10 @@ class PatternStatement:
 		self.original = original
 
 class PatternContext:
+	"""
+	Data about a message that has matched a configured statement and what
+	actions have been carried out.
+	"""
 	def __init__(self, message: Message, statement: PatternStatement):
 		self.message = message
 		self.statement = statement
@@ -121,20 +147,11 @@ class PatternContext:
 		self.is_kicked = False
 		self.is_banned = False
 
-class PatternCog(BaseCog):
-	def __init__(self, bot):
-		super().__init__(bot)
-
-	# def __patterns(self, guild: Guild) -> list:
-	# 	patterns = Storage.get_state_value(guild, 'pattern_patterns')
-	# 	if patterns is None:
-	# 		patterns_encoded = Storage.get_config_value(guild, 'pattern_patterns')
-	# 		if patterns_encoded:
-	# 			patterns = []
-	# 			for pe in patterns_encoded:
-	# 				patterns.append(Pattern.decode(pe))
-	# 			Storage.set_state_value(guild, 'pattern_patterns', patterns)
-	# 	return patterns
+class PatternCog(BaseCog, name='Pattern Matching'):
+	"""
+	Highly flexible cog for performing various actions on messages that match
+	various critera. Patterns can be defined by mods for each guild.
+	"""
 
 	def __get_patterns(self, guild: Guild) -> dict:
 		patterns = Storage.get_state_value(guild, 'PatternCog.patterns')
@@ -148,12 +165,13 @@ class PatternCog(BaseCog):
 					try:
 						ps = PatternCompiler.parse_statement(name, statement)
 						patterns[name] = ps
-					except RuntimeError as e:
-						self.log(guild, f'Error parsing saved statement "{name}". Skipping: {statement}')
+					except Exception as e:
+						self.log(guild, f'Error parsing saved statement "{name}". Skipping: {statement}. Error: {e}')
 			Storage.set_state_value(guild, 'PatternCog.patterns', patterns)
 		return patterns
 
-	def __save_patterns(self, guild: Guild, patterns: dict) -> None:
+	@classmethod
+	def __save_patterns(cls, guild: Guild, patterns: dict) -> None:
 		to_save = []
 		for name, statement in patterns.items():
 			to_save.append({
@@ -164,6 +182,7 @@ class PatternCog(BaseCog):
 
 	@commands.Cog.listener()
 	async def on_message(self, message: Message) -> None:
+		'Event listener'
 		if message.author is None or \
 				message.author.bot or \
 				message.channel is None or \
@@ -176,7 +195,7 @@ class PatternCog(BaseCog):
 			return
 
 		patterns = self.__get_patterns(message.guild)
-		for name, statement in patterns.items():
+		for _, statement in patterns.items():
 			if statement.expression.matches(message):
 				await self.__trigger_actions(message, statement)
 				break
@@ -188,7 +207,7 @@ class PatternCog(BaseCog):
 		action_descriptions = []
 		self.log(message.guild, f'Message from {message.author.name} matched pattern "{statement.name}"')
 		for action in statement.actions:
-			if action.type == 'ban':
+			if action.action == 'ban':
 				await message.author.ban(
 					reason=f'Rocketbot: Message matched custom pattern named "{statement.name}"',
 					delete_message_days=0)
@@ -196,21 +215,21 @@ class PatternCog(BaseCog):
 				context.is_kicked = True
 				action_descriptions.append('Author banned')
 				self.log(message.guild, f'{message.author.name} banned')
-			elif action.type == 'delete':
+			elif action.action == 'delete':
 				await message.delete()
 				context.is_deleted = True
 				action_descriptions.append('Message deleted')
 				self.log(message.guild, f'{message.author.name}\'s message deleted')
-			elif action.type == 'kick':
+			elif action.action == 'kick':
 				await message.author.kick(
 					reason=f'Rocketbot: Message matched custom pattern named "{statement.name}"')
 				context.is_kicked = True
 				action_descriptions.append('Author kicked')
 				self.log(message.guild, f'{message.author.name} kicked')
-			elif action.type == 'modwarn':
+			elif action.action == 'modwarn':
 				should_alert_mods = True
 				action_descriptions.append('Mods alerted')
-			elif action.type == 'reply':
+			elif action.action == 'reply':
 				await message.reply(
 					f'{action.arguments[0]}',
 					mention_author=False)
@@ -240,13 +259,13 @@ class PatternCog(BaseCog):
 			context.is_deleted = True
 		elif reaction.emoji == CONFIG['kick_emoji']:
 			await context.message.author.kick(
-				reason=f'Rocketbot: Message matched custom pattern named ' + \
-					'"{statement.name}". Kicked by {reacted_by.name}.')
+				reason='Rocketbot: Message matched custom pattern named ' + \
+					f'"{context.statement.name}". Kicked by {reacted_by.name}.')
 			context.is_kicked = True
 		elif reaction.emoji == CONFIG['ban_emoji']:
 			await context.message.author.ban(
-				reason=f'Rocketbot: Message matched custom pattern named ' + \
-					'"{statement.name}". Banned by {reacted_by.name}.',
+				reason='Rocketbot: Message matched custom pattern named ' + \
+					f'"{context.statement.name}". Banned by {reacted_by.name}.',
 					delete_message_days=1)
 			context.is_banned = True
 		await bot_message.set_reactions(BotMessageReaction.standard_set(
@@ -260,7 +279,7 @@ class PatternCog(BaseCog):
 	@commands.has_permissions(ban_members=True)
 	@commands.guild_only()
 	async def pattern(self, context: commands.Context):
-		'Message pattern matching'
+		'Message pattern matching command group'
 		if context.invoked_subcommand is None:
 			await context.send_help()
 
@@ -273,6 +292,7 @@ class PatternCog(BaseCog):
 		ignore_extra=True
 	)
 	async def add(self, context: commands.Context, name: str):
+		'Command handler'
 		pattern_str = PatternCompiler.expression_str_from_context(context, name)
 		try:
 			statement = PatternCompiler.parse_statement(name, pattern_str)
@@ -292,6 +312,7 @@ class PatternCog(BaseCog):
 		usage='<pattern_name>'
 	)
 	async def remove(self, context: commands.Context, name: str):
+		'Command handler'
 		patterns = self.__get_patterns(context.guild)
 		if patterns.get(name) is not None:
 			del patterns[name]
@@ -308,6 +329,7 @@ class PatternCog(BaseCog):
 		brief='Lists all patterns'
 	)
 	async def list(self, context: commands.Context) -> None:
+		'Command handler'
 		patterns = self.__get_patterns(context.guild)
 		if len(patterns) == 0:
 			await context.message.reply('No patterns defined.', mention_author=False)
@@ -318,6 +340,9 @@ class PatternCog(BaseCog):
 		await context.message.reply(msg, mention_author=False)
 
 class PatternCompiler:
+	"""
+	Parses a user-provided message filter statement into a PatternStatement.
+	"""
 	TYPE_ID = 'id'
 	TYPE_MEMBER = 'Member'
 	TYPE_TEXT = 'text'
@@ -364,6 +389,9 @@ class PatternCompiler:
 
 	@classmethod
 	def expression_str_from_context(cls, context: commands.Context, name: str) -> str:
+		"""
+		Extracts the statement string from an "add" command context.
+		"""
 		pattern_str = context.message.content
 		command_chain = [ name ]
 		cmd = context.command
@@ -380,6 +408,9 @@ class PatternCompiler:
 
 	@classmethod
 	def parse_statement(cls, name: str, statement: str) -> PatternStatement:
+		"""
+		Parses a user-provided message filter statement into a PatternStatement.
+		"""
 		tokens = cls.tokenize(statement)
 		token_index = 0
 		actions, token_index = cls.read_actions(tokens, token_index)
@@ -388,6 +419,9 @@ class PatternCompiler:
 
 	@classmethod
 	def tokenize(cls, statement: str) -> list:
+		"""
+		Converts a message filter statement into a list of tokens.
+		"""
 		tokens = []
 		in_quote = False
 		in_escape = False
@@ -476,6 +510,11 @@ class PatternCompiler:
 
 	@classmethod
 	def read_actions(cls, tokens: list, token_index: int) -> tuple:
+		"""
+		Reads the actions from a list of statement tokens. Returns a tuple
+		containing a list of PatternActions and the token index this method
+		left off at (the token after the "if").
+		"""
 		actions = []
 		current_action_tokens = []
 		while token_index < len(tokens):
@@ -501,43 +540,47 @@ class PatternCompiler:
 
 	@classmethod
 	def __validate_action(cls, action: PatternAction) -> None:
-		args = cls.ACTION_TO_ARGS.get(action.type)
+		args = cls.ACTION_TO_ARGS.get(action.action)
 		if args is None:
-			raise RuntimeError(f'Unknown action "{action.type}"')
+			raise RuntimeError(f'Unknown action "{action.action}"')
 		if len(action.arguments) != len(args):
-			arg_list = ', '.join(args)
 			if len(args) == 0:
-				raise RuntimeError(f'Action "{action.type}" expects no arguments, got {len(action.arguments)}.')
+				raise RuntimeError(f'Action "{action.action}" expects no arguments, ' + \
+					f'got {len(action.arguments)}.')
 			else:
-				raise RuntimeError(f'Action "{action.type}" expects {len(args)} arguments, got {len(action.arguments)}.')
-		for i in range(len(args)):
-			datatype = args[i]
+				raise RuntimeError(f'Action "{action.action}" expects {len(args)} ' + \
+					f'arguments, got {len(action.arguments)}.')
+		for i, datatype in enumerate(args):
 			action.arguments[i] = cls.parse_value(action.arguments[i], datatype)
 
 	@classmethod
-	def read_expression(cls, tokens: list, token_index: int, depth: int = 0, one_subexpression: bool = False) -> tuple:
-		# field op value
-		# (field op value)
-		# !(field op value)
-		# field op value and field op value
-		# (field op value and field op value) or field op value
-		indent = '\t' * depth
+	def read_expression(cls,
+			tokens: list,
+			token_index: int,
+			depth: int = 0,
+			one_subexpression: bool = False) -> tuple:
+		"""
+		Reads an expression from a list of statement tokens. Returns a tuple
+		containing the PatternExpression and the token index it left off at.
+		If one_subexpression is True then it will return after reading a
+		single expression instead of joining multiples (for readong the
+		subject of a NOT expression).
+		"""
 		subexpressions = []
 		last_compound_operator = None
 		while token_index < len(tokens):
 			if one_subexpression:
 				if len(subexpressions) == 1:
 					return (subexpressions[0], token_index)
-				elif len(subexpressions) > 1:
+				if len(subexpressions) > 1:
 					raise RuntimeError('Too many subexpressions')
 			compound_operator = None
 			if tokens[token_index] == ')':
 				if len(subexpressions) == 0:
 					raise RuntimeError('No subexpressions')
-				elif len(subexpressions) == 1:
+				if len(subexpressions) == 1:
 					return (subexpressions[0], token_index)
-				else:
-					return (PatternCompoundExpression(last_compound_operator, subexpressions), token_index)
+				return (PatternCompoundExpression(last_compound_operator, subexpressions), token_index)
 			if tokens[token_index] in set(["and", "or"]):
 				compound_operator = tokens[token_index]
 				if last_compound_operator and compound_operator != last_compound_operator:
@@ -547,7 +590,8 @@ class PatternCompiler:
 					last_compound_operator = compound_operator
 				token_index += 1
 			if tokens[token_index] == '!':
-				(exp, next_index) = cls.read_expression(tokens, token_index + 1, depth + 1, one_subexpression=True)
+				(exp, next_index) = cls.read_expression(tokens, token_index + 1, \
+						depth + 1, one_subexpression=True)
 				subexpressions.append(PatternCompoundExpression('!', [exp]))
 				token_index = next_index
 			elif tokens[token_index] == '(':
@@ -569,8 +613,13 @@ class PatternCompiler:
 
 	@classmethod
 	def read_simple_expression(cls, tokens: list, token_index: int, depth: int = 0) -> tuple:
-		indent = '\t' * depth
-
+		"""
+		Reads a simple expression consisting of a field name, operator, and
+		comparison value. Returns a tuple of the PatternSimpleExpression and
+		the token index it left off at.
+		"""
+		if depth > 8:
+			raise RuntimeError('Expression nests too deeply')
 		if token_index >= len(tokens):
 			raise RuntimeError('Expected field name, found EOL')
 		field = tokens[token_index]
@@ -609,20 +658,23 @@ class PatternCompiler:
 		return (exp, token_index)
 
 	@classmethod
-	def parse_value(cls, value: str, type: str):
-		if type == cls.TYPE_ID:
+	def parse_value(cls, value: str, datatype: str):
+		"""
+		Converts a value token to its Python value.
+		"""
+		if datatype == cls.TYPE_ID:
 			p = re.compile('^[0-9]+$')
 			if p.match(value) is None:
 				raise ValueError(f'Illegal id value "{value}"')
 			# Store it as a str so it can be larger than an int
 			return value
-		if type == cls.TYPE_MEMBER:
+		if datatype == cls.TYPE_MEMBER:
 			p = re.compile('^<@!?([0-9]+)>$')
 			m = p.match(value)
 			if m is None:
-				raise ValueError(f'Illegal member value. Must be an @ mention.')
+				raise ValueError('Illegal member value. Must be an @ mention.')
 			return m.group(1)
-		if type == cls.TYPE_TEXT:
+		if datatype == cls.TYPE_TEXT:
 			# Must be quoted.
 			if len(value) < 2 or \
 					value[0:1] not in cls.STRING_QUOTE_CHARS or \
@@ -630,10 +682,10 @@ class PatternCompiler:
 					value[0:1] != value[-1:]:
 				raise ValueError(f'Not a quoted string value: {value}')
 			return value[1:-1]
-		if type == cls.TYPE_INT:
+		if datatype == cls.TYPE_INT:
 			return int(value)
-		if type == cls.TYPE_FLOAT:
+		if datatype == cls.TYPE_FLOAT:
 			return float(value)
-		if type == cls.TYPE_TIMESPAN:
+		if datatype == cls.TYPE_TIMESPAN:
 			return parse_timedelta(value)
 		raise ValueError(f'Unhandled datatype {datatype}')

cogs/urlspamcog.py

@@ -1,20 +1,23 @@
-from discord import Guild, Member, Message
-from discord.ext import commands
 import re
 from datetime import timedelta
+from discord import Member, Message
+from discord.ext import commands
 
 from cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
 from config import CONFIG
-from storage import Storage
+from rbutils import describe_timedelta
 
 class URLSpamContext:
+	"""
+	Data about a suspected spam message containing a URL.
+	"""
 	def __init__(self, spam_message: Message):
 		self.spam_message = spam_message
 		self.is_deleted = False
 		self.is_kicked = False
 		self.is_banned = False
 
-class URLSpamCog(BaseCog):
+class URLSpamCog(BaseCog, name='URL Spam'):
 	"""
 	Detects users posting URLs who just joined recently: a common spam pattern.
 	Can be configured to take immediate action or just warn the mods.
@@ -50,12 +53,13 @@ class URLSpamCog(BaseCog):
 	@commands.has_permissions(ban_members=True)
 	@commands.guild_only()
 	async def urlspam(self, context: commands.Context):
-		'Command group'
+		'URL spam command group'
 		if context.invoked_subcommand is None:
 			await context.send_help()
 
 	@commands.Cog.listener()
 	async def on_message(self, message: Message):
+		'Event listener'
 		if message.author is None or \
 				message.author.bot or \
 				message.guild is None or \
@@ -73,7 +77,7 @@ class URLSpamCog(BaseCog):
 		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)
+		join_age_str = describe_timedelta(join_age)
 		if join_age < min_join_age:
 			context = URLSpamContext(message)
 			needs_attention = False
@@ -165,22 +169,3 @@ class URLSpamCog(BaseCog):
 	def __contains_url(cls, text: str) -> bool:
 		p = re.compile(r'http(?:s)?://[^\s]+')
 		return p.search(text) is not None
-
-	@classmethod
-	def __format_timedelta(cls, timespan: timedelta) -> str:
-		parts = []
-		d = timespan.days
-		h = timespan.seconds // 3600
-		m = (timespan.seconds // 60) % 60
-		s = timespan.seconds % 60
-		if d > 0:
-			parts.append(f'{d} days')
-		if d > 0 or h > 0:
-			parts.append(f'{h} hours')
-		if d > 0 or h > 0 or m > 0:
-			parts.append(f'{m} minutes')
-		parts.append(f'{s} seconds')
-		# Limit the precision to the two most significant elements
-		while len(parts) > 2:
-			parts.pop(-1)
-		return ' '.join(parts)

rbutils.py

@@ -1,5 +1,5 @@
-from datetime import timedelta
 import re
+from datetime import timedelta
 
 def parse_timedelta(s: str) -> timedelta:
 	"""
@@ -32,28 +32,22 @@ def parse_timedelta(s: str) -> timedelta:
 	return timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds)
 
 def describe_timedelta(td: timedelta, max_components: int = 2) -> str:
-	values = [
-		td.days,
-		td.seconds // 3600,
-		(td.seconds // 60) % 60,
-		td.seconds % 60,
-	]
-	units = [
-		'day' if values[0] == 1 else 'days',
-		'hour' if values[1] == 1 else 'hours',
-		'minute' if values[2] == 1 else 'minutes',
-		'second' if values[3] == 1 else 'seconds',
-	]
-	while len(values) > 1 and values[0] == 0:
-		values.pop(0)
-		units.pop(0)
-	if len(values) > max_components:
-		values = values[0:max_components]
-		units = units[0:max_components]
-	while len(values) > 1 and values[-1] == 0:
-		values.pop(-1)
-		units.pop(-1)
-	tokens = []
-	for i in range(len(values)):
-		tokens.append(f'{values[i]} {units[i]}')
-	return ' '.join(tokens)
+	"""
+	Formats a human-readable description of a time span. E.g. "3 days 2 hours".
+	"""
+	d = td.days
+	h = td.seconds // 3600
+	m = (td.seconds // 60) % 60
+	s = td.seconds % 60
+	components = []
+	if d != 0:
+		components.append('1 day' if d == 1 else f'{d} days')
+	if h != 0:
+		components.append('1 hour' if h == 1 else f'{h} hours')
+	if m != 0:
+		components.append('1 minute' if m == 1 else f'{m} minutes')
+	if s != 0 or len(components) == 0:
+		components.append('1 second' if s == 1 else f'{s} seconds')
+	if len(components) > max_components:
+		components = components[0:max_components]
+	return ' '.join(components)

rocketbot.py

@@ -18,21 +18,24 @@ from cogs.urlspamcog import URLSpamCog
 
 CURRENT_CONFIG_VERSION = 3
 if (CONFIG.get('__config_version') or 0) < CURRENT_CONFIG_VERSION:
-    # If you're getting this error, it means something changed in config.py's
-    # format. Consult config.py.sample and compare it to your own config.py.
-    # Rename/move any values as needed. When satisfied, update "__config_version"
-    # to the value in config.py.sample.
-    raise RuntimeError('config.py format may be outdated. Review ' +
-        'config.py.sample, update the "__config_version" field to ' +
-        f'{CURRENT_CONFIG_VERSION}, and try again.')
+	# If you're getting this error, it means something changed in config.py's
+	# format. Consult config.py.sample and compare it to your own config.py.
+	# Rename/move any values as needed. When satisfied, update "__config_version"
+	# to the value in config.py.sample.
+	raise RuntimeError('config.py format may be outdated. Review ' +
+		'config.py.sample, update the "__config_version" field to ' +
+		f'{CURRENT_CONFIG_VERSION}, and try again.')
 
 class Rocketbot(commands.Bot):
+	"""
+	Bot subclass
+	"""
 	def __init__(self, command_prefix, **kwargs):
 		super().__init__(command_prefix, **kwargs)
 
 intents = Intents.default()
-intents.messages = True
-intents.members = True # To get join/leave events
+intents.messages = True  # pylint: disable=assigning-non-slot
+intents.members = True  # pylint: disable=assigning-non-slot
 bot = Rocketbot(command_prefix=CONFIG['command_prefix'], intents=intents)
 
 # Core

rscollections.py

@@ -1,9 +1,9 @@
-from abc import ABC, abstractmethod
-
 """
 Subclasses of list, set, and dict with special behaviors.
 """
 
+from abc import ABC, abstractmethod
+
 # Abstract collections
 
 class AbstractMutableList(list, ABC):
@@ -247,7 +247,10 @@ class SizeBoundList(AbstractMutableList):
 	however elements will only be discarded following the next mutating
 	operation. Call `self.purge_old_elements()` to force resizing.
 	"""
-	def __init__(self, max_element_count: int, element_age, *args, **kwargs):
+	def __init__(self,
+			max_element_count: int,
+			element_age,
+			*args, **kwargs):
 		super().__init__(*args, **kwargs)
 		self.element_age = element_age
 		self.max_element_count = max_element_count
@@ -272,8 +275,7 @@ class SizeBoundList(AbstractMutableList):
 		while len(self) > self.max_element_count:
 			oldest_age = None
 			oldest_index = -1
-			for i in range(len(self)):
-				elem = self[i]
+			for i, elem in enumerate(self):
 				age = self.element_age(i, elem)
 				if oldest_age is None or age < oldest_age:
 					oldest_age = age
@@ -281,8 +283,8 @@ class SizeBoundList(AbstractMutableList):
 			self.pop(oldest_index)
 		self.is_culling = False
 
-	def copy():
-		return SizeBoundList(max_element_count, element_age, super())
+	def copy(self):
+		return SizeBoundList(self.max_element_count, self.element_age, super())
 
 class SizeBoundSet(AbstractMutableSet):
 	"""
@@ -303,7 +305,10 @@ class SizeBoundSet(AbstractMutableSet):
 	however elements will only be discarded following the next mutating
 	operation. Call `self.purge_old_elements()` to force resizing.
 	"""
-	def __init__(self, max_element_count: int, element_age, *args, **kwargs):
+	def __init__(self,
+			max_element_count: int,
+			element_age,
+			*args, **kwargs):
 		super().__init__(*args, **kwargs)
 		self.element_age = element_age
 		self.max_element_count = max_element_count
@@ -335,8 +340,8 @@ class SizeBoundSet(AbstractMutableSet):
 			self.remove(oldest_elem)
 		self.is_culling = False
 
-	def copy():
-		return SizeBoundSet(max_element_count, element_age, super())
+	def copy(self):
+		return SizeBoundSet(self.max_element_count, self.element_age, super())
 
 class SizeBoundDict(AbstractMutableDict):
 	"""
@@ -357,7 +362,10 @@ class SizeBoundDict(AbstractMutableDict):
 	however elements will only be discarded following the next mutating
 	operation. Call `self.purge_old_elements()` to force resizing.
 	"""
-	def __init__(self, max_element_count = 10, element_age = (lambda key, value: float(key)), *args, **kwargs):
+	def __init__(self,
+			max_element_count: int,
+			element_age,
+			*args, **kwargs):
 		super().__init__(*args, **kwargs)
 		self.element_age = element_age
 		self.max_element_count = max_element_count
@@ -389,8 +397,8 @@ class SizeBoundDict(AbstractMutableDict):
 			del self[oldest_key]
 		self.is_culling = False
 
-	def copy():
-		return SizeBoundDict(max_element_count, element_age, super())
+	def copy(self):
+		return SizeBoundDict(self.max_element_count, self.element_age, super())
 
 # Collections with limited age of elements
 
@@ -436,8 +444,7 @@ class AgeBoundList(AbstractMutableList):
 		min_age = None
 		max_age = None
 		ages = {}
-		for i in range(len(self)):
-			elem = self[i]
+		for i, elem in enumerate(self):
 			age = self.element_age(i, elem)
 			ages[i] = age
 			if min_age is None or age < min_age:
@@ -453,6 +460,9 @@ class AgeBoundList(AbstractMutableList):
 				del self[i]
 		self.is_culling = False
 
+	def copy(self):
+		return AgeBoundList(self.max_age, self.element_age, super())
+
 class AgeBoundSet(AbstractMutableSet):
 	"""
 	Subclass of `set` that enforces a maximum "age" of elements.
@@ -511,6 +521,9 @@ class AgeBoundSet(AbstractMutableSet):
 				self.remove(elem)
 		self.is_culling = False
 
+	def copy(self):
+		return AgeBoundSet(self.max_age, self.element_age, super())
+
 class AgeBoundDict(AbstractMutableDict):
 	"""
 	Subclass of `dict` that enforces a maximum "age" of elements.
@@ -568,3 +581,6 @@ class AgeBoundDict(AbstractMutableDict):
 			if age < cutoff:
 				del self[key]
 		self.is_culling = False
+
+	def copy(self):
+		return AgeBoundDict(self.max_age, self.element_age, super())

storage.py

@@ -1,11 +1,16 @@
+"""
+Handles storage of persisted and non-persisted data for the bot.
+"""
 import json
 from os.path import exists
-
 from discord import Guild
 
 from config import CONFIG
 
 class ConfigKey:
+	"""
+	Common keys in persisted guild storage.
+	"""
 	WARNING_CHANNEL_ID = 'warning_channel_id'
 	WARNING_MENTION = 'warning_mention'
 
@@ -47,16 +52,16 @@ class Storage:
 		cls.set_state_values(guild, { key: value })
 
 	@classmethod
-	def set_state_values(cls, guild: Guild, vars: dict) -> None:
+	def set_state_values(cls, guild: Guild, values: dict) -> None:
 		"""
 		Merges in a set of key-value pairs into the transient state for the
 		given guild. Any pairs with a value of `None` will be removed from the
 		transient state.
 		"""
-		if vars is None or len(vars) == 0:
+		if values is None or len(values) == 0:
 			return
 		state: dict = cls.get_state(guild)
-		for key, value in vars.items():
+		for key, value in values.items():
 			if value is None:
 				del state[key]
 			else:
@@ -105,21 +110,21 @@ class Storage:
 		cls.set_config_values(guild, { key: value })
 
 	@classmethod
-	def set_config_values(cls, guild: Guild, vars: dict) -> None:
+	def set_config_values(cls, guild: Guild, values: dict) -> None:
 		"""
-		Merges the given `vars` dict with the saved config for the given guild
-		and writes it to disk. `vars` must be JSON-encodable or a `ValueError`
+		Merges the given `values` dict with the saved config for the given guild
+		and writes it to disk. `values` must be JSON-encodable or a `ValueError`
 		will be raised. Keys with associated values of `None` will be removed
 		from the persisted config.
 		"""
-		if vars is None or len(vars) == 0:
+		if values is None or len(values) == 0:
 			return
 		config: dict = cls.get_config(guild)
 		try:
-			json.dumps(vars)
-		except:
-			raise ValueError(f'vars not JSON encodable - {vars}')
-		for key, value in vars.items():
+			json.dumps(values)
+		except Exception as e:
+			raise ValueError(f'values not JSON encodable - {values}') from e
+		for key, value in values.items():
 			if value is None:
 				del config[key]
 			else:
@@ -134,7 +139,7 @@ class Storage:
 		path: str = cls.__guild_config_path(guild)
 		cls.__trace(f'Saving config for guild {guild.id} to {path}')
 		cls.__trace(f'config = {config}')
-		with open(path, 'w') as file:
+		with open(path, 'w', encoding='utf8') as file:
 			# Pretty printing to make more legible for debugging
 			# Sorting keys to help with diffs
 			json.dump(config, file, indent='\t', sort_keys=True)
@@ -151,7 +156,7 @@ class Storage:
 			cls.__trace(f'No config on disk for guild {guild.id}. Returning None.')
 			return None
 		cls.__trace(f'Loading config from disk for guild {guild.id}')
-		with open(path, 'r') as file:
+		with open(path, 'r', encoding='utf8') as file:
 			config = json.load(file)
 		cls.__trace('State loaded')
 		return config