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
)
- Permissions that a user needs to have in order to execute the command, default
- 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- ctx:
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
)
- Permissions that a user needs to have in order to execute the command, default
- 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- ctx:
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'
and2
are user-commands;'message'
and3
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
)
- Permissions that a user needs to have in order to execute the command, default
- 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
- ctx:
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
orSelectInteraction
The invoked component
Note
ctx
is just an example name, you can use whatever you want for it- ctx:
@cogs.listening_component("custom_id", [539459006847254542], [53945900682362362], 'button') async def callback(ctx): ...
- custom_id: