tux.help ¶

async def _get_prefix(self) -> str:
    """
    Get the guild-specific command prefix.

    Returns
    -------
    str
        The command prefix for the current guild.
    """
    guild_id = self.context.guild.id if self.context.guild else None

    if guild_id not in self._prefix_cache:
        # Fetch and cache the prefix specific to the guild
        self._prefix_cache[guild_id] = self.context.clean_prefix or CONFIG.DEFAULT_PREFIX

    return self._prefix_cache[guild_id]

def _embed_base(self, title: str, description: str | None = None) -> discord.Embed:
    """
    Create a base embed with consistent styling.

    Parameters
    ----------
    title : str
        The embed title.
    description : str or None, optional
        The embed description (default is None).

    Returns
    -------
    discord.Embed
        A styled embed object.
    """
    return discord.Embed(
        title=title,
        description=description,
        color=CONST.EMBED_COLORS["DEFAULT"],
    )

def _format_flag_details(self, command: commands.Command[Any, Any, Any]) -> str:
    """
    Format the details of command flags.

    Parameters
    ----------
    command : commands.Command
        The command for which to format the flags.

    Returns
    -------
    str
        Formatted string of flag details.
    """
    flag_details: list[str] = []

    try:
        type_hints = get_type_hints(command.callback)
    except Exception:
        return ""

    for param_annotation in type_hints.values():
        if not isinstance(param_annotation, type) or not issubclass(param_annotation, commands.FlagConverter):
            continue

        for flag in param_annotation.__commands_flags__.values():
            flag_str = self._format_flag_name(flag)
            if flag.aliases and not getattr(flag, "positional", False):
                flag_str += f" ({', '.join(flag.aliases)})"
            flag_str += f"\n\t{flag.description or 'No description provided'}"
            if flag.default is not discord.utils.MISSING:
                flag_str += f"\n\tDefault: {flag.default}"
            flag_details.append(flag_str)

    return "\n\n".join(flag_details)

@staticmethod
def _format_flag_name(flag: commands.Flag) -> str:
    """
    Format a flag name based on its properties.

    Parameters
    ----------
    flag : commands.Flag
        The flag to format.

    Returns
    -------
    str
        Formatted flag name string.
    """
    if getattr(flag, "positional", False):
        return f"<{flag.name}>" if flag.required else f"[{flag.name}]"
    return f"-{flag.name}" if flag.required else f"[-{flag.name}]"

def _generate_default_usage(self, command: commands.Command[Any, Any, Any]) -> str:
    """
    Generate a default usage string for a command.

    Parameters
    ----------
    command : commands.Command
        The command for which to generate usage.

    Returns
    -------
    str
        Formatted usage string.
    """
    signature = command.signature.strip()
    if not signature:
        return command.qualified_name

    # Format the signature to look more like Discord's native format
    # Replace things like [optional] with <optional>
    formatted_signature = signature.replace("[", "<").replace("]", ">")
    return f"{command.qualified_name} {formatted_signature}"

async def _add_command_help_fields(self, embed: discord.Embed, command: commands.Command[Any, Any, Any]) -> None:
    """
    Add usage and alias fields to the command embed.

    Parameters
    ----------
    embed : discord.Embed
        The embed object to add fields to.
    command : commands.Command
        The command for which to add help fields.
    """
    prefix = await self._get_prefix()
    usage = command.usage or self._generate_default_usage(command)
    embed.add_field(name="Usage", value=f"`{prefix}{usage}`", inline=False)
    embed.add_field(
        name="Aliases",
        value=(f"`{', '.join(command.aliases)}`" if command.aliases else "No aliases"),
        inline=False,
    )

@staticmethod
def _add_command_field(embed: discord.Embed, command: commands.Command[Any, Any, Any], prefix: str) -> None:
    """
    Add a command as a field in the embed.

    Parameters
    ----------
    embed : discord.Embed
        The embed object to update.
    command : commands.Command
        The command to add.
    prefix : str
        The command prefix.
    """
    command_aliases = ", ".join(command.aliases) if command.aliases else "No aliases"
    embed.add_field(
        name=f"{prefix}{command.qualified_name} ({command_aliases})",
        value=f"> {command.short_doc or 'No documentation summary'}",
        inline=False,
    )

async def _get_command_categories(
    self,
    mapping: Mapping[commands.Cog | None, list[commands.Command[Any, Any, Any]]],
) -> tuple[dict[str, dict[str, str]], dict[str, dict[str, commands.Command[Any, Any, Any]]]]:
    """
    Retrieve command categories and mapping.

    Parameters
    ----------
    mapping : Mapping[commands.Cog | None, list[commands.Command]]
        Mapping of cogs to their commands.

    Returns
    -------
    tuple
        A tuple containing:
        - dict: Category cache mapping category names to command details.
        - dict: Command mapping of categories to command objects.
    """
    if self._category_cache:
        return self._category_cache, self.command_mapping or {}

    self._category_cache, self.command_mapping = create_cog_category_mapping(mapping)
    return self._category_cache, self.command_mapping

def _paginate_subcommands(
    self,
    commands_list: list[commands.Command[Any, Any, Any]],
    preserve_page: bool = False,
) -> None:
    """
    Split subcommands into pages for pagination.

    Parameters
    ----------
    commands_list : list of commands.Command
        List of commands to paginate.
    preserve_page : bool, optional
        If True, preserve the current page index; otherwise, reset to first page.
    """
    current_page = self.current_subcommand_page if preserve_page else 0
    self.subcommand_pages = paginate_items(commands_list, 10)

    # Restore or reset page counter
    if preserve_page:
        # Make sure the page index is valid for the new pagination
        self.current_subcommand_page = min(current_page, len(self.subcommand_pages) - 1)
    else:
        # Reset to first page when paginating
        self.current_subcommand_page = 0

def _find_command(self, command_name: str) -> commands.Command[Any, Any, Any] | None:
    """
    Find and return the command object for a given command name.

    Parameters
    ----------
    command_name : str
        The name of the command to search for.

    Returns
    -------
    commands.Command or None
        The command object if found; otherwise, None.
    """
    if (
        self.current_category
        and self.command_mapping
        and (found := self.command_mapping[self.current_category].get(command_name))
    ):
        return found
    if (
        self.current_command_obj
        and isinstance(self.current_command_obj, commands.Group)
        and (found := discord.utils.get(self.current_command_obj.commands, name=command_name))
    ):
        return found
    if self.command_mapping:
        for category_commands in self.command_mapping.values():
            for cmd in category_commands.values():
                if isinstance(cmd, commands.Group) and (
                    found := discord.utils.get(cmd.commands, name=command_name)
                ):
                    return found
    return None

def _find_parent_command(self, subcommand_name: str) -> tuple[str, commands.Command[Any, Any, Any]] | None:
    """
    Find the parent command for a given subcommand.

    Parameters
    ----------
    subcommand_name : str
        The subcommand name to find the parent for.

    Returns
    -------
    tuple of (str, commands.Command) or None
        A tuple containing the parent command name and object, or None if not found.
    """
    if self.command_mapping:
        for category_commands in self.command_mapping.values():
            for parent_name, cmd in category_commands.items():
                if isinstance(cmd, commands.Group) and discord.utils.get(cmd.commands, name=subcommand_name):
                    return parent_name, cmd
    return None

async def _create_category_options(self) -> list[discord.SelectOption]:
    """
    Create select options for category selection.

    Returns
    -------
    list of discord.SelectOption
        A list of select options for available command categories.
    """
    category_emoji_map = {
        "info": "🔍",
        "moderation": "🛡",
        "utility": "🔧",
        "snippets": "📝",
        "admin": "👑",
        "fun": "🎉",
        "levels": "📈",
        "services": "🔌",
        "guild": "🏰",
    }

    options: list[discord.SelectOption] = []
    for category in self._category_cache:
        if any(self._category_cache[category].values()):
            emoji = category_emoji_map.get(category, "❓")
            options.append(
                discord.SelectOption(
                    label=category.capitalize(),
                    value=category,
                    emoji=emoji,
                    description=f"View {category.capitalize()} commands",
                ),
            )

    return sorted(options, key=lambda o: o.label)

async def _create_command_options(self, category: str) -> list[discord.SelectOption]:
    """
    Create select options for commands within a specified category.

    Parameters
    ----------
    category : str
        The category for which to create command options.

    Returns
    -------
    list of discord.SelectOption
        A list of select options corresponding to the commands in the category.
    """
    options: list[discord.SelectOption] = []

    if self.command_mapping and category in self.command_mapping:
        for cmd_name, cmd in self.command_mapping[category].items():
            description = truncate_description(cmd.short_doc or "No description")

            # Add an indicator for group commands
            is_group = isinstance(cmd, commands.Group) and len(cmd.commands) > 0
            label = f"{cmd_name}{'†' if is_group else ''}"

            options.append(SelectOption(label=label, value=cmd_name, description=description))

    else:
        logger.warning(f"No commands found for category {category}")

    return sorted(options, key=lambda o: o.label)

async def _create_subcommand_options(self, command: commands.Group[Any, Any, Any]) -> list[SelectOption]:
    """
    Create select options for subcommands within a command group.

    Parameters
    ----------
    command : commands.Group
        The command group for which to create subcommand options.

    Returns
    -------
    list of discord.SelectOption
        A list of select options for the subcommands.
    """
    # Special handling for jishaku to prevent loading all subcommands
    if command.name not in {"jsk", "jishaku"}:
        # Normal handling for other command groups
        return [
            SelectOption(
                label=subcmd.name,
                value=subcmd.name,
                description=truncate_description(subcmd.short_doc or "No description"),
            )
            for subcmd in sorted(command.commands, key=lambda x: x.name)
        ]
    # Only include a few important jishaku commands
    essential_subcmds = ["py", "shell", "cat", "curl", "pip", "git", "help"]

    subcommand_options: list[SelectOption] = []
    for subcmd_name in essential_subcmds:
        if subcmd := discord.utils.get(command.commands, name=subcmd_name):
            description = truncate_description(subcmd.short_doc or "No description")
            subcommand_options.append(SelectOption(label=subcmd.name, value=subcmd.name, description=description))

    # Add an option to suggest using jsk help
    subcommand_options.append(
        SelectOption(
            label="See all commands",
            value="_see_all",
            description="Use jsk help command for complete list",
        ),
    )

    return subcommand_options

async def _create_main_embed(self) -> discord.Embed:
    """
    Create the main help embed.

    Returns
    -------
    discord.Embed
        The main help embed to be displayed.
    """
    if CONFIG.BOT_NAME != "Tux":
        logger.info("Bot name is not Tux, using different help message.")
        embed = self._embed_base(
            "Hello! Welcome to the help command.",
            f"{CONFIG.BOT_NAME} is a self-hosted instance of Tux. The bot is written in Python using discord.py.\n\nIf you enjoy using {CONFIG.BOT_NAME}, consider contributing to the original project.",
        )
    else:
        embed = self._embed_base(
            "Hello! Welcome to the help command.",
            "Tux is an all-in-one bot by the All Things Linux Discord server. The bot is written in Python using discord.py, and we are actively seeking contributors.",
        )

    await self._add_bot_help_fields(embed)
    return embed

async def _create_category_embed(self, category: str) -> discord.Embed:
    """
    Create an embed for a specific category.

    Parameters
    ----------
    category : str
        The category name.

    Returns
    -------
    discord.Embed
        The embed displaying commands for the category.
    """
    prefix = await self._get_prefix()
    embed = self._embed_base(f"{category.capitalize()} Commands")

    embed.set_footer(
        text="Select a command from the dropdown to see details.",
    )

    sorted_commands = sorted(self._category_cache[category].items())
    description = "\n".join(f"**`{prefix}{cmd}`** | {command_list}" for cmd, command_list in sorted_commands)
    embed.description = description

    return embed

async def _create_command_embed(self, command_name: str) -> discord.Embed:
    """
    Create an embed for a specific command.

    Parameters
    ----------
    command_name : str
        The name of the command.

    Returns
    -------
    discord.Embed
        The embed with command details.
    """
    command = self._find_command(command_name)
    if not command:
        logger.error(
            f"Command '{command_name}' not found. Category: {self.current_category}, Current command: {self.current_command}",
        )
        return self._embed_base("Error", "Command not found")

    # Store the current command object for reference
    self.current_command_obj = command
    self.current_command = command_name

    prefix = await self._get_prefix()
    help_text = format_multiline_description(command.help)
    embed = self._embed_base(
        title=f"{prefix}{command.qualified_name}",
        description=help_text,
    )

    # Add command fields
    await self._add_command_help_fields(embed, command)

    # Add flag details if present
    if flag_details := self._format_flag_details(command):
        embed.add_field(name="Flags", value=f"```\n{flag_details}\n```", inline=False)

    # Add subcommands section if this is a group
    if isinstance(command, commands.Group) and command.commands:
        sorted_cmds = sorted(command.commands, key=lambda x: x.name)

        if nested_groups := [cmd for cmd in sorted_cmds if isinstance(cmd, commands.Group) and cmd.commands]:
            nested_groups_text = "\n".join(
                f"• `{g.name}` - {truncate_description(g.short_doc or 'No description')} ({len(g.commands)} subcommands)"
                for g in nested_groups
            )
            embed.add_field(
                name="Nested Command Groups",
                value=(
                    f"This command has the following subcommand groups:\n\n{nested_groups_text}\n\nSelect a group command to see its subcommands."
                ),
                inline=False,
            )

        self._paginate_subcommands(sorted_cmds, preserve_page=True)

        # For large command groups like JSK, show paginated view
        if command.name in {"jsk", "jishaku"} or len(sorted_cmds) > 15:
            valid_page = self.subcommand_pages and 0 <= self.current_subcommand_page < len(self.subcommand_pages)
            current_page_cmds = (
                self.subcommand_pages[self.current_subcommand_page] if valid_page else sorted_cmds[:10]
            )
            if not valid_page:
                logger.warning(
                    f"Invalid page index: {self.current_subcommand_page}, pages: {len(self.subcommand_pages)}",
                )

            subcommands_list = "\n".join(
                f"• `{c.name}{'†' if isinstance(c, commands.Group) and c.commands else ''}` - {c.short_doc or 'No description'}"
                for c in current_page_cmds
            )

            total_count = len(sorted_cmds)
            page_num = self.current_subcommand_page + 1
            total_pages = len(self.subcommand_pages) or 1

            embed.add_field(
                name=f"Subcommands (Page {page_num}/{total_pages})",
                value=(
                    f"This command has {total_count} subcommands:\n\n{subcommands_list}\n\nUse the navigation buttons to browse all subcommands."
                ),
                inline=False,
            )
        else:
            subcommands_list = "\n".join(
                f"• `{c.name}{'†' if isinstance(c, commands.Group) and c.commands else ''}` - {c.short_doc or 'No description'}"
                for c in sorted_cmds
            )
            embed.add_field(
                name="Subcommands",
                value=(
                    f"This command group has the following subcommands:\n\n{subcommands_list}\n\nSelect a subcommand from the dropdown to see more details."
                ),
                inline=False,
            )
    return embed

async def _create_subcommand_embed(self, subcommand_name: str) -> discord.Embed:
    """
    Create an embed for a specific subcommand.

    Parameters
    ----------
    subcommand_name : str
        The name of the subcommand.

    Returns
    -------
    discord.Embed
        The embed with subcommand details.
    """
    if not self.current_command_obj or not isinstance(self.current_command_obj, commands.Group):
        return self._embed_base("Error", "Parent command not found")

    # Find the subcommand
    subcommand = discord.utils.get(self.current_command_obj.commands, name=subcommand_name)
    if not subcommand:
        return self._embed_base("Error", "Subcommand not found")

    prefix = await self._get_prefix()

    # Format help text with proper quoting
    help_text = format_multiline_description(subcommand.help)

    embed = self._embed_base(
        title=f"{prefix}{subcommand.qualified_name}",
        description=help_text,
    )

    await self._add_command_help_fields(embed, subcommand)

    if flag_details := self._format_flag_details(subcommand):
        embed.add_field(name="Flags", value=f"```\n{flag_details}\n```", inline=False)

    return embed

async def _add_bot_help_fields(self, embed: discord.Embed) -> None:
    """
    Add additional help information about the bot to the embed.

    Parameters
    ----------
    embed : discord.Embed
        The embed to which the help information will be added.
    """
    prefix = await self._get_prefix()

    embed.add_field(
        name="How to Use",
        value=f"Most commands are hybrid meaning they can be used via prefix `{prefix}` OR slash `/`. Commands strictly available via `/` are not listed in the help menu.",
        inline=False,
    )
    embed.add_field(
        name="Command Help",
        value="Select a category from the dropdown, then select a command to view details.",
        inline=False,
    )
    embed.add_field(
        name="Flag Help",
        value=f"Flags in `[]` are optional. Most flags have aliases that can be used.\n> e.g. `{prefix}ban @user spamming` or `{prefix}b @user spamming -silent true`",
        inline=False,
    )
    embed.add_field(
        name="Support Server",
        value="-# [Need support? Join Server](https://discord.gg/gpmSjcjQxg)",
        inline=True,
    )
    embed.add_field(
        name="GitHub Repository",
        value="-# [Help contribute! View Repo](https://github.com/allthingslinux/tux)",
        inline=True,
    )

    bot_name_display = "Tux" if CONFIG.BOT_NAME == "Tux" else f"{CONFIG.BOT_NAME} (Tux)"
    environment = get_current_env()
    owner_info = f"Bot Owner: <@{CONFIG.BOT_OWNER_ID}>" if not CONFIG.HIDE_BOT_OWNER and CONFIG.BOT_OWNER_ID else ""

    embed.add_field(
        name="Bot Instance",
        value=f"-# Running {bot_name_display} version `{CONFIG.BOT_VERSION}` in `{environment}` mode | {owner_info}",
        inline=False,
    )

async def _create_main_view(self) -> HelpView:
    """
    Create the main help view with category selection.

    Returns
    -------
    HelpView
        A view containing category selection and a close button.
    """
    view = HelpView(self)

    # Add category select
    category_options = await self._create_category_options()
    category_select = CategorySelectMenu(self, category_options, "Select a category")
    view.add_item(category_select)

    # Add close button
    view.add_item(CloseButton())

    return view

async def _create_category_view(self, category: str) -> HelpView:
    """
    Create a view for a specific category with command selection.

    Parameters
    ----------
    category : str
        The category name.

    Returns
    -------
    HelpView
        The view for the selected category.
    """
    view = HelpView(self)

    # Add command select for this category
    command_options = await self._create_command_options(category)
    command_select = CommandSelectMenu(self, command_options, f"Select a {category} command")
    view.add_item(command_select)

    # Add back button and close button
    view.add_item(BackButton(self))
    view.add_item(CloseButton())

    return view

async def _create_command_view(self) -> HelpView:
    """
    Create a view for a command with navigation options.

    Returns
    -------
    HelpView
        A view for navigating command details.
    """
    view = HelpView(self)

    # Add back button first
    view.add_item(BackButton(self))

    # If this is a command group, handle navigation
    if (
        self.current_command_obj
        and isinstance(self.current_command_obj, commands.Group)
        and len(self.current_command_obj.commands) > 0
    ):
        sorted_cmds = sorted(self.current_command_obj.commands, key=lambda x: x.name)

        # For large command groups like JSK, use pagination buttons and add a select menu for the current page
        if self.current_command_obj.name in {"jsk", "jishaku"} or len(sorted_cmds) > 15:
            if not self.subcommand_pages:
                self._paginate_subcommands(sorted_cmds, preserve_page=True)

            if len(self.subcommand_pages) > 1:
                view.add_item(PrevButton(self))
                view.add_item(NextButton(self))

            valid_page = self.subcommand_pages and 0 <= self.current_subcommand_page < len(self.subcommand_pages)
            current_page_cmds = self.subcommand_pages[self.current_subcommand_page] if valid_page else []
            if not valid_page:
                logger.warning(
                    f"Invalid page index: {self.current_subcommand_page}, pages: {len(self.subcommand_pages)}",
                )

            if jsk_select_options := [
                discord.SelectOption(
                    label=cmd.name,
                    value=cmd.name,
                    description=truncate_description(cmd.short_doc or "No description"),
                )
                for cmd in current_page_cmds
            ]:
                jsk_select = CommandSelectMenu(self, jsk_select_options, "Select a command")
                view.add_item(jsk_select)
        else:
            logger.info(
                f"Creating dropdown for command group: {self.current_command_obj.name} with {len(sorted_cmds)} subcommands",
            )

            if subcommand_options := await self._create_subcommand_options(self.current_command_obj):
                subcommand_select = SubcommandSelectMenu(self, subcommand_options, "Select a subcommand")
                view.add_item(subcommand_select)

            if nested_groups := [cmd for cmd in sorted_cmds if isinstance(cmd, commands.Group) and cmd.commands]:
                for group_cmd in nested_groups:
                    logger.info(
                        f"Adding nested group handling for {group_cmd.name} with {len(group_cmd.commands)} subcommands",
                    )

    # Add close button last
    view.add_item(CloseButton())

    return view