Reorganizing files

README.md

@@ -23,7 +23,7 @@ config.py's "client_token" attribute.
 
 Create a "config" subdirectory under your source folder. This is where guild-specific configuration is written as JSON files.
 
-To start, run `python3 rocketbot.py`. Then visit
+To start, run `python3 bot.py`. Then visit
 https://discord.com/oauth2/authorize?client_id=[application_id]&scope=bot&permissions=395204357318,
 where [application_id] is the "application id" value on your app configuration
 "general information" page. Once invited, test if the bot is working by typing

rocketbot.py → bot.py

@@ -10,12 +10,12 @@ from discord import Intents
 from discord.ext import commands
 
 from config import CONFIG
-from cogs.configcog import ConfigCog
-from cogs.crosspostcog import CrossPostCog
-from cogs.generalcog import GeneralCog
-from cogs.joinraidcog import JoinRaidCog
-from cogs.patterncog import PatternCog
-from cogs.urlspamcog import URLSpamCog
+from rocketbot.cogs.configcog import ConfigCog
+from rocketbot.cogs.crosspostcog import CrossPostCog
+from rocketbot.cogs.generalcog import GeneralCog
+from rocketbot.cogs.joinraidcog import JoinRaidCog
+from rocketbot.cogs.patterncog import PatternCog
+from rocketbot.cogs.urlspamcog import URLSpamCog
 
 CURRENT_CONFIG_VERSION = 3
 if (CONFIG.get('__config_version') or 0) < CURRENT_CONFIG_VERSION:

cogs/basecog.py → rocketbot/cogs/basecog.py

@@ -1,11 +1,14 @@
+"""
+Base cog class and helper classes.
+"""
 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 config import CONFIG
-from rscollections import AgeBoundDict
-from storage import ConfigKey, Storage
+from rocketbot.collections import AgeBoundDict
+from rocketbot.storage import ConfigKey, Storage
 
 class BotMessageReaction:
 	"""
@@ -111,7 +114,7 @@ class BotMessage:
 	def __init__(self,
 			guild: Guild,
 			text: str,
-			type: int = 0, # TYPE_DEFAULT
+			type: int = TYPE_DEFAULT,
 			context = None,
 			reply_to: Message = None):
 		self.guild = guild
@@ -143,6 +146,7 @@ class BotMessage:
 		return self.__message.created_at if self.__message else None
 
 	def has_reactions(self) -> bool:
+		'Whether this message has any reactions defined.'
 		return len(self.__reactions) > 0
 
 	async def set_text(self, new_text: str) -> None:
@@ -329,7 +333,7 @@ class CogSetting:
 		self.name = name
 		self.datatype = datatype
 		self.brief = brief
-		self.description = description or ''  # XXX: Can't be None
+		self.description = description or ''  # Can't be None
 		self.usage = usage
 		self.min_value = min_value
 		self.max_value = max_value
@@ -508,7 +512,7 @@ class BaseCog(commands.Cog):
 				commands.guild_only(),
 			])
 
-		# XXX: Passing `cog` in init gets ignored and set to `None` so set after.
+		# Passing `cog` in init gets ignored and set to `None` so set after.
 		# This ensures the callback is passed `self`.
 		get_command.cog = self
 		set_command.cog = self

cogs/configcog.py → rocketbot/cogs/configcog.py

@@ -1,9 +1,12 @@
+"""
+Cog handling general configuration for a guild.
+"""
 from discord import Guild, TextChannel
 from discord.ext import commands
 
 from config import CONFIG
-from storage import ConfigKey, Storage
-from cogs.basecog import BaseCog
+from rocketbot.storage import ConfigKey, Storage
+from rocketbot.cogs.basecog import BaseCog
 
 class ConfigCog(BaseCog, name='Configuration'):
 	"""

cogs/crosspostcog.py → rocketbot/cogs/crosspostcog.py

@@ -1,11 +1,14 @@
+"""
+Cog for detecting spam messages posted in multiple channels.
+"""
 from datetime import datetime, timedelta
 from discord import Member, Message
 from discord.ext import commands
 
-from cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
 from config import CONFIG
-from rscollections import AgeBoundList, SizeBoundDict
-from storage import Storage
+from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
+from rocketbot.collections import AgeBoundList, SizeBoundDict
+from rocketbot.storage import Storage
 
 class SpamContext:
 	"""

cogs/generalcog.py → rocketbot/cogs/generalcog.py

@@ -1,12 +1,16 @@
+"""
+Cog for handling most ungrouped commands and basic behaviors.
+"""
 import re
 from datetime import datetime, timedelta
 from discord import Message
+from discord.errors import DiscordException
 from discord.ext import commands
 
-from cogs.basecog import BaseCog, BotMessage
 from config import CONFIG
-from rbutils import parse_timedelta, describe_timedelta
-from storage import ConfigKey, Storage
+from rocketbot.cogs.basecog import BaseCog, BotMessage
+from rocketbot.utils import parse_timedelta, describe_timedelta
+from rocketbot.storage import ConfigKey, Storage
 
 class GeneralCog(BaseCog, name='General'):
 	"""
@@ -106,7 +110,7 @@ class GeneralCog(BaseCog, name='General'):
 		for channel in context.guild.text_channels:
 			try:
 				deleted_messages += await channel.purge(limit=100, check=predicate)
-			except:
+			except DiscordException:
 				# XXX: Sloppily glossing over access errors instead of checking access
 				pass
 		await context.message.reply(

cogs/joinraidcog.py → rocketbot/cogs/joinraidcog.py

@@ -1,12 +1,15 @@
+"""
+Cog for detecting large numbers of guild joins in a short period of time.
+"""
 import weakref
 from datetime import datetime, timedelta
 from discord import Guild, Member
 from discord.ext import commands
 
-from cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
 from config import CONFIG
-from rscollections import AgeBoundList
-from storage import Storage
+from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
+from rocketbot.collections import AgeBoundList
+from rocketbot.storage import Storage
 
 class JoinRaidContext:
 	"""

cogs/patterncog.py → rocketbot/cogs/patterncog.py

@@ -1,12 +1,16 @@
+"""
+Cog for matching messages against guild-configurable criteria and taking
+automated actions on them.
+"""
 import re
-from abc import ABC, abstractmethod
+from abc import ABCMeta, abstractmethod
 from discord import Guild, Member, Message
 from discord.ext import commands
 
-from cogs.basecog import BaseCog, BotMessage, BotMessageReaction
 from config import CONFIG
-from rbutils import parse_timedelta
-from storage import Storage
+from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction
+from rocketbot.storage import Storage
+from rocketbot.utils import parse_timedelta
 
 class PatternAction:
 	"""
@@ -20,7 +24,7 @@ class PatternAction:
 		arg_str = ', '.join(self.arguments)
 		return f'{self.action}({arg_str})'
 
-class PatternExpression(ABC):
+class PatternExpression(metaclass=ABCMeta):
 	"""
 	Abstract message matching expression.
 	"""
@@ -165,8 +169,9 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 					try:
 						ps = PatternCompiler.parse_statement(name, statement)
 						patterns[name] = ps
-					except Exception as e:
-						self.log(guild, f'Error parsing saved statement "{name}". Skipping: {statement}. Error: {e}')
+					except PatternError as e:
+						self.log(guild, 'Error parsing saved statement ' + \
+							f'"{name}": "{e}" Statement: {statement}')
 			Storage.set_state_value(guild, 'PatternCog.patterns', patterns)
 		return patterns
 
@@ -302,7 +307,7 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			await context.message.reply(
 				f'{CONFIG["success_emoji"]} Pattern `{name}` added.',
 				mention_author=False)
-		except Exception as e:
+		except PatternError as e:
 			await context.message.reply(
 				f'{CONFIG["failure_emoji"]} Error parsing statement. {e}',
 				mention_author=False)
@@ -339,6 +344,11 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			msg += f'Pattern `{name}`:\n```\n{statement.original}\n```\n'
 		await context.message.reply(msg, mention_author=False)
 
+class PatternError(RuntimeError):
+	"""
+	Error thrown when parsing a pattern statement.
+	"""
+
 class PatternCompiler:
 	"""
 	Parses a user-provided message filter statement into a PatternStatement.
@@ -457,7 +467,7 @@ class PatternCompiler:
 					in_quote = ch
 					current_token = ch
 				elif ch == '\\':
-					raise RuntimeError("Unexpected \\")
+					raise PatternError("Unexpected \\ outside quoted string")
 				elif ch in cls.WHITESPACE_CHARS:
 					if len(current_token) > 0:
 						tokens.append(current_token)
@@ -528,7 +538,7 @@ class PatternCompiler:
 				return (actions, token_index)
 			elif token == ',':
 				if len(current_action_tokens) < 1:
-					raise RuntimeError('Unexpected ,')
+					raise PatternError('Unexpected ,')
 				a = PatternAction(current_action_tokens[0], current_action_tokens[1:])
 				cls.__validate_action(a)
 				actions.append(a)
@@ -536,19 +546,19 @@ class PatternCompiler:
 			else:
 				current_action_tokens.append(token)
 			token_index += 1
-		raise RuntimeError('Unexpected end of line')
+		raise PatternError('Unexpected end of line in action list')
 
 	@classmethod
 	def __validate_action(cls, action: PatternAction) -> None:
 		args = cls.ACTION_TO_ARGS.get(action.action)
 		if args is None:
-			raise RuntimeError(f'Unknown action "{action.action}"')
+			raise PatternError(f'Unknown action "{action.action}"')
 		if len(action.arguments) != len(args):
 			if len(args) == 0:
-				raise RuntimeError(f'Action "{action.action}" expects no arguments, ' + \
+				raise PatternError(f'Action "{action.action}" expects no arguments, ' + \
 					f'got {len(action.arguments)}.')
 			else:
-				raise RuntimeError(f'Action "{action.action}" expects {len(args)} ' + \
+				raise PatternError(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)
@@ -573,11 +583,11 @@ class PatternCompiler:
 				if len(subexpressions) == 1:
 					return (subexpressions[0], token_index)
 				if len(subexpressions) > 1:
-					raise RuntimeError('Too many subexpressions')
+					raise PatternError('Too many subexpressions')
 			compound_operator = None
 			if tokens[token_index] == ')':
 				if len(subexpressions) == 0:
-					raise RuntimeError('No subexpressions')
+					raise PatternError('No subexpressions')
 				if len(subexpressions) == 1:
 					return (subexpressions[0], token_index)
 				return (PatternCompoundExpression(last_compound_operator, subexpressions), token_index)
@@ -597,7 +607,7 @@ class PatternCompiler:
 			elif tokens[token_index] == '(':
 				(exp, next_index) = cls.read_expression(tokens, token_index + 1, depth + 1)
 				if tokens[next_index] != ')':
-					raise RuntimeError('Expected )')
+					raise PatternError('Expected )')
 				subexpressions.append(exp)
 				token_index = next_index + 1
 			else:
@@ -605,7 +615,7 @@ class PatternCompiler:
 				subexpressions.append(simple)
 				token_index = next_index
 		if len(subexpressions) == 0:
-			raise RuntimeError('No subexpressions')
+			raise PatternError('No subexpressions')
 		elif len(subexpressions) == 1:
 			return (subexpressions[0], token_index)
 		else:
@@ -619,39 +629,41 @@ class PatternCompiler:
 		the token index it left off at.
 		"""
 		if depth > 8:
-			raise RuntimeError('Expression nests too deeply')
+			raise PatternError('Expression nests too deeply')
 		if token_index >= len(tokens):
-			raise RuntimeError('Expected field name, found EOL')
+			raise PatternError('Expected field name, found EOL')
 		field = tokens[token_index]
 		token_index += 1
 
 		datatype = cls.FIELD_TO_TYPE.get(field)
 		if datatype is None:
-			raise RuntimeError(f'No such field "{field}"')
+			raise PatternError(f'No such field "{field}"')
 
 		if token_index >= len(tokens):
-			raise RuntimeError('Expected operator, found EOL')
+			raise PatternError('Expected operator, found EOL')
 		op = tokens[token_index]
 		token_index += 1
 
 		if op == '!':
 			if token_index >= len(tokens):
-				raise RuntimeError('Expected operator, found EOL')
+				raise PatternError('Expected operator, found EOL')
 			op = '!' + tokens[token_index]
 			token_index += 1
 
 		allowed_ops = cls.TYPE_TO_OPERATORS[datatype]
 		if op not in allowed_ops:
 			if op in cls.OPERATORS_ALL:
-				raise RuntimeError(f'Operator {op} cannot be used with field "{field}"')
-			else:
-				raise RuntimeError(f'Unrecognized operator "{op}" - allowed: {list(allowed_ops)}')
+				raise PatternError(f'Operator {op} cannot be used with field "{field}"')
+			raise PatternError(f'Unrecognized operator "{op}" - allowed: {list(allowed_ops)}')
 
 		if token_index >= len(tokens):
-			raise RuntimeError('Expected value, found EOL')
+			raise PatternError('Expected value, found EOL')
 		value = tokens[token_index]
 
-		value = cls.parse_value(value, datatype)
+		try:
+			value = cls.parse_value(value, datatype)
+		except ValueError as cause:
+			raise PatternError(f'Bad value {value}') from cause
 
 		token_index += 1
 		exp = PatternSimpleExpression(field, op, value)
@@ -660,7 +672,7 @@ class PatternCompiler:
 	@classmethod
 	def parse_value(cls, value: str, datatype: str):
 		"""
-		Converts a value token to its Python value.
+		Converts a value token to its Python value. Raises ValueError on failure.
 		"""
 		if datatype == cls.TYPE_ID:
 			p = re.compile('^[0-9]+$')

cogs/urlspamcog.py → rocketbot/cogs/urlspamcog.py

@@ -1,11 +1,14 @@
+"""
+Cog for detecting URLs posted by new users.
+"""
 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 rbutils import describe_timedelta
+from rocketbot.cogs.basecog import BaseCog, BotMessage, BotMessageReaction, CogSetting
+from rocketbot.utils import describe_timedelta
 
 class URLSpamContext:
 	"""

rbutils.py → rocketbot/utils.py

@@ -1,3 +1,6 @@
+"""
+General utility functions.
+"""
 import re
 from datetime import timedelta