Cogs

Setup

To use cog tools, you have to import the module

from discord_ui.cogs import slash_command, subslash_command, context_cog, listening_component

Important

You need a Slash instance for slashcommands cogs and a Component instance for listening components. The best would be to initialze a UI instance, because it will initialize a component instance and a slash instance

Example

from discord.ext import commands
from discord_ui import UI
from discord_ui.cogs import slash_command, subslash_command


bot = commands.Bot(" ")
ui = UI(bot)


class Example(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @slash_command(guild_ids=[785567635802816595])
    async def name(self, ctx):
        """Responds with the name of the bot"""
        await ctx.send("my name is _" + self.bot.user.name + "_")

bot.add_cog(Example(bot))
bot.run("token")

slash_command

cogs.slash_command(description=None, options=None, guild_ids=None, default_permission=None, guild_permissions=None)

A decorator for cogs that will register a slashcommand

command in discord: /name [options]

name: str, optional

1-32 characters long name; default MISSING

Note

The name will be corrected automaticaly (spaces will be replaced with “-” and the name will be lowercased)

description: str, optional

1-100 character description of the command; default the command name

options: List[SlashOptions], optional

The parameters for the command; default MISSING

choices: List[tuple] | List[dict], optional

Choices for string and int types for the user to pick from; default MISSING

guild_ids: List[str | int], optional

A list of guild ids where the command is available; default MISSING

default_permission: bool | discord.Permissions, optional

Permissions that a user needs to have in order to execute the command, default True.: If a bool was passed, it will indicate whether all users can use the command (True) or not (False)

guild_permissions: Dict[guild_id: SlashPermission]

The permissions for the command in guilds: Format: {"guild_id": SlashPermission}

callback: method(ctx)

The asynchron function that will be called if the command was used

ctx: SlashInteraction: The used slash command

Note

ctx is just an example name, you can use whatever you want for that

class My_Cog(commands.Cog)
    ... 

    @slash_command(name="hello_world", options=[
    SlashOption(str, name="parameter", description="this is a parameter", choices=[{ "name": "choice 1", "value": "test" }])
    ], guild_ids=[785567635802816595], default_permission=False, 
    guild_permissions={
            785567635802816595: SlashPermission(allowed={"539459006847254542": SlashPermission.USER})
        }
    )
    async def hello_world(self, ctx, parameter = None):
        ...

subslash_command

cogs.subslash_command(name=None, description=None, options=None, guild_ids=None, default_permission=None, guild_permissions=None)

A decorator for cogs that will register a subcommand/subcommand-group

command in discord: /base_names... name [options]

base_names: List[str] | str

The names of the parent bases, currently limited to 2: If you want to make a subcommand (/base name), you have to use a str instead of a list

name: str, optional

1-32 characters long name; default MISSING

Note

The name will be corrected automaticaly (spaces will be replaced with “-” and the name will be lowercased)

description: str, optional

1-100 character description of the command; default the command name

options: List[SlashOptions], optional

The parameters for the command; default MISSING

choices: List[tuple] | List[dict], optional

Choices for string and int types for the user to pick from; default MISSING

guild_ids: List[str | int], optional

A list of guild ids where the command is available; default MISSING

default_permission: bool | discord.Permissions, optional

Permissions that a user needs to have in order to execute the command, default True.: If a bool was passed, it will indicate whether all users can use the command (True) or not (False)

guild_permissions: Dict[guild_id: SlashPermission]

The permissions for the command in guilds: Format: {"guild_id": SlashPermission}

Note

Permissions will be the same for every subcommand with the same base

callback: method(ctx)

The asynchron function that will be called if the command was used

ctx: SubSlashInteraction: The used slash command

Note

ctx is just an example name, you can use whatever you want for that

subcommand

class My_Cog(commands.Cog):
    ...

    @subslash_command(base_names="hello", name="world", options=[
        SlashOption(type="user", name="user", description="the user to tell the holy words")
    ], guild_ids=[785567635802816595])
    async def command(ctx, user):
        ...

subcommand-group

class My_Cog(commands.Cog):
    ...

    @subslash_command(base_names=["hello", "beautiful"], name="world", options=[
        SlashOption(type="user", name="user", description="the user to tell the holy words")
    ], guild_ids=[785567635802816595])
    async def command(ctx, user):
        ...

context_command

cogs.context_command(name=None, guild_ids=None, default_permission=None, guild_permissions=None)

Decorator for cogs that will register a context command in discord: Right-click message or user -> apps -> commands is displayed here

type: Literal['user', 2 | 'message' | 3]

The type of the contextcommand.: 'user' and 2 are user-commands; 'message' and 3 are message-commansd

name: str, optional

The name of the command; default MISSING

guild_ids: List[str | int]

A list of guilds where the command can be used

default_permission: bool | discord.Permissions, optional

Permissions that a user needs to have in order to execute the command, default True.: If a bool was passed, it will indicate whether all users can use the command (True) or not (False)

guild_permissions: Dict[SlashPermission], optional

Special permissions for guilds; default MISSING

callback: method(ctx, message)

The asynchron function that will be called if the command was used

ctx: SlashCommand: The used slash command
message: Member: The message on which the command was used

class My_Cog(commands.Cog):
    ...

    # message command
    @context_command(type="message", name="quote", guild_ids=[785567635802816595])
    async def quote(ctx, message):
        ...

    # user command
    @context_command(type="user", name="mention", guild_ids=[785567635802816595])
    async def mention(ctx, user):
        ...

listening_component

cogs.listening_component(messages=None, users=None, component_type: Optional[Literal['button', 'select']] = None, check: Callable[[Union[discord_ui.receive.ButtonInteraction, discord_ui.receive.SelectInteraction]], bool] = empty_check)

Decorator for cogs that will register a listening component

custom_id: str

The custom_id of the components to listen to

messages: List[discord.Message | int str], Optional

A list of messages or message ids to filter the listening component

users: List[discord.User | discord.Member | int | str], Optional

A list of users or user ids to filter

component_type: Literal['button' | 'select']

What type the used component has to be of (select: SelectMenu, button: Button)

check: function, Optional

A function that has to return True in order to invoke the listening component: The check function takes to parameters, the component and the message

callback: method(ctx)

The asynchron function that will be called if a component with the custom_id was invoked

There will be one parameters passed

ctx: ButtonInteraction or SelectInteraction
The invoked component

Note

ctx is just an example name, you can use whatever you want for it

@cogs.listening_component("custom_id", [539459006847254542], [53945900682362362], 'button')
async def callback(ctx):
    ...