More annotations

rocketbot/botmessage.py

@@ -2,6 +2,8 @@
 Classes for crafting messages from the bot. Content can change as information
 changes, and mods can perform actions on the message via emoji reactions.
 """
+from typing import Any, Optional, Union
+
 from datetime import datetime
 from discord import Guild, Message, PartialEmoji, TextChannel
 
@@ -20,9 +22,16 @@ class BotMessageReaction:
 	to explain why an action is no longer available.
 	"""
 	def __init__(self, emoji: str, is_enabled: bool, description: str):
-		self.emoji = emoji
-		self.is_enabled = is_enabled
-		self.description = description
+		"""
+		Creates a bot message reaction.
+		- emoji: The emoji string
+		- is_enabled: Whether the emoji can be used
+		- description: What reacting with this emoji does (or an explanation of
+		  why it's disabled)
+		"""
+		self.emoji: str = emoji
+		self.is_enabled: bool = is_enabled
+		self.description: str = description
 
 	def __eq__(self, other):
 		return other is not None and \
@@ -36,7 +45,7 @@ class BotMessageReaction:
 			message_count: int = 1,
 			did_kick: bool = None,
 			did_ban: bool = None,
-			user_count: int = 1) -> list:
+			user_count: int = 1) -> list[BotMessageReaction]:
 		"""
 		Convenience factory for generating any of the three most common
 		commands: delete message(s), kick user(s), and ban user(s). All
@@ -55,7 +64,7 @@ class BotMessageReaction:
 		- user_count     How many users there are. Used for pluralizing
 		                 description. Defaults to 1. Omit if n/a.
 		"""
-		reactions = []
+		reactions: list[BotMessageReaction] = []
 		if did_delete is not None:
 			if did_delete:
 				reactions.append(BotMessageReaction(
@@ -104,29 +113,38 @@ class BotMessage:
 	actions that can be taken via a mod reacting to the message.
 	"""
 
-	TYPE_DEFAULT = 0
-	TYPE_INFO = 1
-	TYPE_MOD_WARNING = 2
-	TYPE_SUCCESS = 3
-	TYPE_FAILURE = 4
+	TYPE_DEFAULT: int = 0
+	TYPE_INFO: int = 1
+	TYPE_MOD_WARNING: int = 2
+	TYPE_SUCCESS: int = 3
+	TYPE_FAILURE: int = 4
 
 	def __init__(self,
 			guild: Guild,
 			text: str,
 			type: int = TYPE_DEFAULT, # pylint: disable=redefined-builtin
-			context = None,
-			reply_to: Message = None):
-		self.guild = guild
-		self.text = text
-		self.type = type
-		self.context = context
-		self.quote = None
+			context: Optional[Any] = None,
+			reply_to: Optional[Message] = None):
+		"""
+		Creates a bot message.
+		- guild: The Discord guild to send the message to.
+		- text: Main text of the message.
+		- type: One of the TYPE_ constants.
+		- context: Arbitrary value that will be passed in the callback. Can be
+		  associated data for performing some action. (optional)
+		- reply_to: Existing message this message is in reply to. (optional)
+		"""
+		self.guild: Guild = guild
+		self.text: str = text
+		self.type: int = type
+		self.context: Optional[Any] = context
+		self.quote: Optional[str] = None
 		self.source_cog = None  # Set by `BaseCog.post_message()`
-		self.__posted_text = None  # last text posted, to test for changes
-		self.__posted_emoji = set()
-		self.__message = None  # Message
-		self.__reply_to = reply_to
-		self.__reactions = []  # BotMessageReaction[]
+		self.__posted_text: str = None  # last text posted, to test for changes
+		self.__posted_emoji: set[str] = set()  # last emoji list posted
+		self.__message: Optional[Message] = None  # set once the message has been posted
+		self.__reply_to: Optional[Message] = reply_to
+		self.__reactions: list[BotMessageReaction] = []
 
 	def is_sent(self) -> bool:
 		"""
@@ -136,11 +154,11 @@ class BotMessage:
 		"""
 		return self.__message is not None
 
-	def message_id(self):
+	def message_id(self) -> Optional[int]:
 		'Returns the Message id or None if not sent.'
 		return self.__message.id if self.__message else None
 
-	def message_sent_at(self) -> datetime:
+	def message_sent_at(self) -> Optional[datetime]:
 		'Returns when the message was sent or None if not sent.'
 		return self.__message.created_at if self.__message else None
 
@@ -156,7 +174,7 @@ class BotMessage:
 		self.text = new_text
 		await self.update_if_sent()
 
-	async def set_reactions(self, reactions: list) -> None:
+	async def set_reactions(self, reactions: list[BotMessageReaction]) -> None:
 		"""
 		Replaces all BotMessageReactions with a new list. If the message has
 		been sent, it will be updated.
@@ -194,7 +212,7 @@ class BotMessage:
 			self.__reactions.append(reaction)
 		await self.update_if_sent()
 
-	async def remove_reaction(self, reaction_or_emoji) -> None:
+	async def remove_reaction(self, reaction_or_emoji: Union[BotMessageReaction, str]) -> None:
 		"""
 		Removes a reaction. Can pass either a BotMessageReaction or just the
 		emoji string. If the message has been sent, it will be updated.
@@ -207,7 +225,7 @@ class BotMessage:
 				await self.update_if_sent()
 				return
 
-	def reaction_for_emoji(self, emoji) -> BotMessageReaction:
+	def reaction_for_emoji(self, emoji) -> Optional[BotMessageReaction]:
 		"""
 		Finds the BotMessageReaction for the given emoji or None if not found.
 		Accepts either a PartialEmoji or str.
@@ -245,11 +263,15 @@ class BotMessage:
 			else:
 				channel_id = Storage.get_config_value(self.guild, ConfigKey.WARNING_CHANNEL_ID)
 				if channel_id is None:
-					bot_log(self.guild, None, '\u0007No warning channel set! No warning issued.')
+					bot_log(self.guild, \
+						type(self.source_cog) if self.source_cog else None, \
+						'\u0007No warning channel set! No warning issued.')
 					return
 				channel: TextChannel = self.guild.get_channel(channel_id)
 				if channel is None:
-					bot_log(self.guild, None, '\u0007Configured warning channel does not exist!')
+					bot_log(self.guild, \
+						type(self.source_cog) if self.source_cog else None, \
+						'\u0007Configured warning channel does not exist!')
 					return
 				self.__message = await channel.send(content=content)
 				self.__posted_text = content
@@ -267,6 +289,10 @@ class BotMessage:
 				self.__posted_emoji.remove(emoji)
 
 	def __formatted_message(self) -> str:
+		"""
+		Composes the entire message markdown from components. Includes the main
+		message, quoted text, summary of available reactions, etc.
+		"""
 		s: str = ''
 
 		if self.type == self.TYPE_INFO:

rocketbot/cogsetting.py

@@ -1,6 +1,9 @@
 """
 A guild configuration setting available for editing via bot commands.
 """
+from types import coroutine
+from typing import Any, Optional, Type
+
 from discord.ext import commands
 from discord.ext.commands import Bot, Cog, Command, Context, Group
 
@@ -11,19 +14,19 @@ from rocketbot.utils import first_command_group
 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.
+	mods of those guilds. BaseCog can generate "get" and "set" commands (or
+	"enable" and "disable" commands for boolean values) automatically, reducing
+	the boilerplate of generating commands manually. Offers simple validation rules.
 	"""
 	def __init__(self,
 			name: str,
-			datatype,
-			brief: str = None,
-			description: str = None,
-			usage: str = None,
-			min_value = None,
-			max_value = None,
-			enum_values: set = None):
+			datatype: Type,
+			brief: Optional[str] = None,
+			description: Optional[str] = None,
+			usage: Optional[str] = None,
+			min_value: Optional[Any] = None,
+			max_value: Optional[Any] = None,
+			enum_values: Optional[set[Any]] = None):
 		"""
 		Params:
 		- name         Setting identifier. Must follow variable naming
@@ -41,14 +44,14 @@ class CogSetting:
 		- 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
-		self.description = description or ''  # Can't be None
-		self.usage = usage
-		self.min_value = min_value
-		self.max_value = max_value
-		self.enum_values = enum_values
+		self.name: str = name
+		self.datatype: Type = datatype
+		self.brief: Optional[str] = brief
+		self.description: str = description or ''  # Can't be None
+		self.usage: Optional[str] = usage
+		self.min_value: Optional[Any] = min_value
+		self.max_value: Optional[Any] = max_value
+		self.enum_values: Optional[set[Any]] = 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:
@@ -86,7 +89,7 @@ class CogSetting:
 			(group or bot).add_command(self.__make_setter_command(cog))
 
 	def __make_getter_command(self, cog: Cog) -> Command:
-		setting = self
+		setting: CogSetting = self
 		async def getter(cog: Cog, context: Context) -> None:
 			setting_name = setting.name
 			if context.command.parent:
@@ -144,7 +147,7 @@ class CogSetting:
 		async def setter_bool(cog, context, new_value: bool):
 			await setter_common(cog, context, new_value)
 
-		setter = None
+		setter: coroutine = None
 		if setting.datatype == int:
 			setter = setter_int
 		elif setting.datatype == float:
@@ -167,7 +170,7 @@ class CogSetting:
 				commands.guild_only(),
 			])
 		# Passing `cog` in init gets ignored and set to `None` so set after.
-		# This ensures the callback is passed `self`.
+		# This ensures the callback is passed the cog as `self` argument.
 		command.cog = cog
 		return command
 
@@ -218,7 +221,7 @@ class CogSetting:
 		return command
 
 	@classmethod
-	def set_up_all(cls, cog: Cog, bot: Bot, settings: list) -> None:
+	def set_up_all(cls, cog: Cog, bot: Bot, settings: list[CogSetting]) -> None:
 		"""
 		Sets up editing commands for a list of CogSettings and adds them to a
 		cog. If the cog has a command Group, commands will be added to it.

rocketbot/utils.py

@@ -3,7 +3,7 @@ General utility functions.
 """
 import re
 from datetime import datetime, timedelta
-from typing import Any, Union
+from typing import Any, Optional, Type, Union
 
 from discord import Guild
 from discord.ext.commands import Cog, Group
@@ -86,7 +86,7 @@ def first_command_group(cog: Cog) -> Group:
 			return member
 	return None
 
-def bot_log(guild: Guild, cog_class, message: Any) -> None:
+def bot_log(guild: Optional[Guild], cog_class: Optional[Type], message: Any) -> None:
 	'Logs a message to stdout with time, cog, and guild info.'
 	now: datetime = datetime.now() # local
 	s = f'[{now.strftime("%Y-%m-%dT%H:%M:%S")}|'