"""Provides help commands for getting info on using other commands and configuration.""" import re import time from typing import Optional, TypedDict, Union from discord import AppCommandType, Interaction, Permissions from discord.app_commands import ( Choice, Command, Group, autocomplete, command, guild_only, ) from config import CONFIG from rocketbot.bot import Rocketbot from rocketbot.cogs.basecog import BaseCog from rocketbot.ui.pagedcontent import paginate, update_paged_content from rocketbot.utils import MOD_PERMISSIONS, dump_stacktrace HelpTopic = Union[Command, Group, BaseCog] class HelpMeta(TypedDict): id: str text: str topic: HelpTopic # Potential place to break text neatly in large help content PAGE_BREAK = '\f' def choice_from_topic(topic: HelpTopic, include_full_command: bool = False) -> Choice: if isinstance(topic, BaseCog): return Choice(name=f'⚙ {topic.qualified_name}', value=f'cog:{topic.qualified_name}') if isinstance(topic, Group): return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}') if isinstance(topic, Command): if topic.parent: if include_full_command: return Choice(name=f'/{topic.parent.name} {topic.name}', value=f'subcmd:{topic.parent.name}.{topic.name}') return Choice(name=f'{topic.name}', value=f'subcmd:{topic.name}') return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}') return Choice(name='', value='') async def search_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]: try: if len(current) == 0: return [ choice_from_topic(topic, include_full_command=True) for topic in HelpCog.shared.all_accessible_topics(interaction.permissions) ] return [ choice_from_topic(topic, include_full_command=True) for topic in HelpCog.shared.topics_for_keywords(current, interaction.permissions) ][:25] except BaseException as e: dump_stacktrace(e) return [] class HelpCog(BaseCog, name='Help'): shared: Optional['HelpCog'] = None def __init__(self, bot: Rocketbot): super().__init__( bot, config_prefix='help', short_description='Provides help on using this bot.' ) HelpCog.shared = self def __create_help_index(self) -> None: """ Populates self.id_to_topic and self.keyword_index. Bails if already populated. Intended to be run on demand so all cogs and commands have had time to get set up and synced. """ if getattr(self, 'id_to_topic', None) is not None: return self.id_to_topic: dict[str, HelpTopic] = {} self.topics: list[HelpMeta] = [] def process_text(t: str) -> str: return ' '.join([ word for word in re.split(r"[^a-z']+", t.lower()) if word not in trivial_words ]).strip() cmds = self.all_commands() for cmd in cmds: key = f'cmd:{cmd.name}' self.id_to_topic[key] = cmd self.id_to_topic[f'/{cmd.name}'] = cmd text = cmd.name if cmd.description: text += f' {cmd.description}' if cmd.extras.get('long_description', None): text += f' {cmd.extras["long_description"]}' self.topics.append({ 'id': key, 'text': process_text(text), 'topic': cmd }) if isinstance(cmd, Group): for subcmd in cmd.commands: key = f'subcmd:{cmd.name}.{subcmd.name}' self.id_to_topic[key] = subcmd self.id_to_topic[f'/{cmd.name} {subcmd.name}'] = subcmd text = cmd.name text += f' {subcmd.name}' if subcmd.description: text += f' {subcmd.description}' if subcmd.extras.get('long_description', None): text += f' {subcmd.extras["long_description"]}' self.topics.append({ 'id': key, 'text': process_text(text), 'topic': subcmd }) for cog_qname, cog in self.bot.cogs.items(): if not isinstance(cog, BaseCog): continue key = f'cog:{cog_qname}' self.id_to_topic[key] = cog text = cog.qualified_name if cog.short_description: text += f' {cog.short_description}' if cog.long_description: text += f' {cog.long_description}' self.topics.append({ 'id': key, 'text': process_text(text), 'topic': cog }) def topic_for_help_symbol(self, symbol: str) -> Optional[HelpTopic]: self.__create_help_index() return self.id_to_topic.get(symbol, None) def all_commands(self) -> list[Union[Command, Group]]: # PyCharm not interpreting conditional return type correctly. # noinspection PyTypeChecker cmds: list[Union[Command, Group]] = self.bot.tree.get_commands(type=AppCommandType.chat_input) return sorted(cmds, key=lambda cmd: cmd.name) def all_accessible_commands(self, permissions: Optional[Permissions]) -> list[Union[Command, Group]]: return [ cmd for cmd in self.all_commands() if can_use_command(cmd, permissions) ] def all_accessible_subcommands(self, permissions: Optional[Permissions]) -> list[Command]: cmds = self.all_accessible_commands(permissions) subcmds: list[Command] = [] for cmd in cmds: if isinstance(cmd, Group): for subcmd in sorted(cmd.commands, key=lambda cmd: cmd.name): if can_use_command(subcmd, permissions): subcmds.append(subcmd) return subcmds def all_accessible_cogs(self, permissions: Optional[Permissions]) -> list[BaseCog]: return [ cog for cog in self.basecogs if can_use_cog(cog, permissions) ] def all_accessible_topics(self, permissions: Optional[Permissions], *, include_cogs: bool = True, include_commands: bool = True, include_subcommands: bool = True) -> list[HelpTopic]: topics = [] if include_cogs: topics += self.all_accessible_cogs(permissions) if include_commands: topics += self.all_accessible_commands(permissions) if include_subcommands: topics += self.all_accessible_subcommands(permissions) return topics def topics_for_keywords(self, search: str, permissions: Optional[Permissions]) -> list[HelpTopic]: start_time = time.perf_counter() self.__create_help_index() # Break into words (or word fragments) words: list[str] = [ word for word in re.split(r"[^a-z']+", search.lower()) ] # Find matches def topic_matches(meta: HelpMeta) -> bool: for word in words: if word not in meta['text']: return False return True matching_topics: list[HelpTopic] = [ topic['topic'] for topic in self.topics if topic_matches(topic) ] # Filter by accessibility accessible_topics = [ topic for topic in matching_topics if ((isinstance(topic, Command) or isinstance(topic, Group)) and can_use_command(topic, permissions)) or \ (isinstance(topic, BaseCog) and can_use_cog(topic, permissions)) ] # Sort and return result = sorted(accessible_topics, key=lambda topic: ( isinstance(topic, Command), isinstance(topic, BaseCog), topic.qualified_name if isinstance(topic, BaseCog) else topic.name )) duration = time.perf_counter() - start_time if duration > 0.01: self.log(None, f'search "{search}" took {duration} seconds') return result @command( name='help', description='Shows help for using commands and module configuration.', extras={ 'long_description': '`/help` will show a list of top-level topics.\n' '\n' "`/help /` will show help about a specific command or list a command's subcommands.\n" '\n' '`/help / ` will show help about a specific subcommand.\n' '\n' '`/help ` will show help about configuring a module.\n' '\n' '`/help ` will do a text search for topics.', } ) @guild_only() @autocomplete(search=search_autocomplete) async def help_command(self, interaction: Interaction, search: Optional[str]) -> None: """ Shows help for using commands and subcommands and configuring modules. Parameters ---------- interaction: Interaction search: Optional[str] search terms """ self.log(interaction.guild, f'{interaction.user.name} used /help {search}') if search is None: await self.__send_general_help(interaction) return topic = self.topic_for_help_symbol(search) if topic: await self.__send_topic_help(interaction, topic) return matches = self.topics_for_keywords(search, interaction.permissions) await self.__send_keyword_help(interaction, matches) async def __send_topic_help(self, interaction: Interaction, topic: HelpTopic) -> None: if isinstance(topic, Command): await self.__send_command_help(interaction, topic) return if isinstance(topic, Group): await self.__send_command_help(interaction, topic) return if isinstance(topic, BaseCog): await self.__send_cog_help(interaction, topic) return self.log(interaction.guild, f'No help for topic object {topic}') await interaction.response.send_message( f'{CONFIG["failure_emoji"]} Failed to get help info.', ephemeral=True, delete_after=10, ) def get_command_list(self, permissions: Optional[Permissions] = None) -> dict[str, Union[Command, Group]]: return { cmd.name: cmd for cmd in self.bot.tree.get_commands() if can_use_command(cmd, permissions) } def get_subcommand_list(self, cmd: Group, permissions: Optional[Permissions] = None) -> dict[str, Command]: return { subcmd.name: subcmd for subcmd in cmd.commands if can_use_command(subcmd, permissions) } if can_use_command(cmd, permissions) else {} async def __send_general_help(self, interaction: Interaction) -> None: user_permissions: Permissions = interaction.permissions all_commands = sorted(self.get_command_list(user_permissions).items()) all_cog_tuples: list[tuple[str, BaseCog]] = [ cog_tuple for cog_tuple in sorted(self.basecog_map.items()) if can_use_cog(cog_tuple[1], user_permissions) and \ (len(cog_tuple[1].settings) > 0) ] text = '## :information_source: Help' if len(all_commands) + len(all_cog_tuples) == 0: text = 'Nothing available for your permissions!' if len(all_commands) > 0: text += '\n### Commands' text += '\nType `/help /commandname` for more information.' for cmd_name, cmd in sorted(self.get_command_list(user_permissions).items()): text += f'\n- `/{cmd_name}`: {cmd.description}' if isinstance(cmd, Group): subcommand_count = len(cmd.commands) text += f' ({subcommand_count} subcommands)' text += PAGE_BREAK if len(all_cog_tuples) > 0: text += '\n### Module Configuration' for cog_name, cog in all_cog_tuples: has_enabled = next((s for s in cog.settings if s.name == 'enabled'), None) is not None text += f'\n- **{cog_name}**: {cog.short_description}' if has_enabled: text += f'\n - `/enable {cog.config_prefix}` or `/disable {cog.config_prefix}`' for setting in cog.settings: if setting.name == 'enabled': continue text += f'\n - `/get` or `/set {cog.config_prefix}_{setting.name}`' text += PAGE_BREAK await self.__send_paged_help(interaction, text) async def __send_keyword_help(self, interaction: Interaction, matching_topics: Optional[list[HelpTopic]]) -> None: matching_commands = [ cmd for cmd in matching_topics or [] if isinstance(cmd, Command) or isinstance(cmd, Group) ] matching_cogs = [ cog for cog in matching_topics or [] if isinstance(cog, BaseCog) ] if len(matching_commands) + len(matching_cogs) == 0: await interaction.response.send_message( f'{CONFIG["failure_emoji"]} No available help topics found.', ephemeral=True, delete_after=10, ) return if len(matching_topics) == 1: topic = matching_topics[0] await self.__send_topic_help(interaction, topic) return text = '## :information_source: Matching Help Topics' if len(matching_commands) > 0: text += '\n### Commands' for cmd in matching_commands: if cmd.parent: text += f'\n- `/{cmd.parent.name} {cmd.name}`' else: text += f'\n- `/{cmd.name}`' if len(matching_cogs) > 0: text += '\n### Modules' for cog in matching_cogs: text += f'\n- {cog.qualified_name}' await self.__send_paged_help(interaction, text) async def __send_command_help(self, interaction: Interaction, command_or_group: Union[Command, Group], addendum: Optional[str] = None) -> None: text = '' if addendum is not None: text += addendum + '\n\n' if command_or_group.parent: text += '## :information_source: Subcommand Help' text += f'\n`/{command_or_group.parent.name} {command_or_group.name}`' else: text += '## :information_source: Command Help' if isinstance(command_or_group, Group): text += f'\n`/{command_or_group.name} subcommand_name`' else: text += f'\n`/{command_or_group.name}`' if isinstance(command_or_group, Command): optional_nesting = 0 for param in command_or_group.parameters: text += ' ' if not param.required: text += '[' optional_nesting += 1 text += f'_{param.name}_' if optional_nesting > 0: text += ']' * optional_nesting text += f'\n\n{command_or_group.description}' if command_or_group.extras.get('long_description'): text += f'\n\n{command_or_group.extras["long_description"]}' if isinstance(command_or_group, Group): subcmds: dict[str, Command] = self.get_subcommand_list(command_or_group, permissions=interaction.permissions) if len(subcmds) > 0: text += '\n### Subcommands:' for subcmd_name, subcmd in sorted(subcmds.items()): text += f'\n- `{subcmd_name}`: {subcmd.description}' text += f'\n-# To use a subcommand, type it after the command. e.g. `/{command_or_group.name} subcommand_name`' text += f'\n-# Get help on a subcommand by typing `/help /{command_or_group.name} subcommand_name`' else: params = command_or_group.parameters if len(params) > 0: text += '\n### Parameters:' for param in params: text += f'\n- `{param.name}`: {param.description}' if not param.required: text += ' (optional)' await self.__send_paged_help(interaction, text) async def __send_cog_help(self, interaction: Interaction, cog: BaseCog) -> None: text = '## :information_source: Module Help' text += f'\n**{cog.qualified_name}** module' if cog.short_description is not None: text += f'\n\n{cog.short_description}' if cog.long_description is not None: text += f'\n\n{cog.long_description}' cmds = [ cmd for cmd in sorted(cog.get_app_commands(), key=lambda c: c.name) if can_use_command(cmd, interaction.permissions) ] if len(cmds) > 0: text += '\n### Commands:' for cmd in cmds: text += f'\n- `/{cmd.name}` - {cmd.description}' if isinstance(cmd, Group): subcmds = [ subcmd for subcmd in cmd.commands if can_use_command(subcmd, interaction.permissions) ] if len(subcmds) > 0: text += f' ({len(subcmds)} subcommands)' settings = cog.settings if len(settings) > 0: text += '\n### Configuration' enabled_setting = next((s for s in settings if s.name == 'enabled'), None) if enabled_setting is not None: text += f'\n- `/enable {cog.config_prefix}` or `/disable {cog.config_prefix}`' for setting in sorted(settings, key=lambda s: s.name): if setting.name == 'enabled': continue text += f'\n- `/get` or `/set {cog.config_prefix}_{setting.name}` - {setting.brief}' await self.__send_paged_help(interaction, text) async def __send_paged_help(self, interaction: Interaction, text: str) -> None: pages = paginate(text) await update_paged_content(interaction, None, 0, pages, delete_after=60) # Exclusions from keyword indexing trivial_words = { 'a', 'an', 'and', 'are', "aren't", 'as', 'by', 'can', 'for', 'have', 'if', 'in', 'is', 'it', 'its', "it's", 'not', 'of', 'on', 'or', 'than', 'that', 'the', 'then', 'there', 'them', 'they', "they're", 'this', 'to', 'when', 'with', } def can_use_command(cmd: Union[Group, Command], user_permissions: Optional[Permissions]) -> bool: if user_permissions is None: return False if cmd.parent and not can_use_command(cmd.parent, user_permissions): return False return cmd.default_permissions is None or cmd.default_permissions.is_subset(user_permissions) def can_use_cog(cog: BaseCog, user_permissions: Optional[Permissions]) -> bool: # "Using" a cog for now means configuring it, and only mods can configure cogs. return user_permissions is not None and MOD_PERMISSIONS.is_subset(user_permissions)