interactions.py Documentation

Discord requires components to be contained within ActionRow objects. A message can have up to 5 action rows, and each row can contain up to 5 buttons or a single select menu.

To control the layout specifically, you have three options:

1. Automatic: Pass components directly; the library wraps them in ActionRows for you.
2. Manual: Define ActionRow() objects explicitly and pass a list of them to components.
3. spread_to_rows(): Use this function to automatically organize a list of components into the appropriate number of ActionRows.

Note: The components are organized in a 5x5 grid.

from interactions import ActionRow, Button, ButtonStyle, spread_to_rows

# Manual layout using ActionRow
components: list[ActionRow] = [
    ActionRow(
        Button(style=ButtonStyle.GREEN, label="Click Me"),
        Button(style=ButtonStyle.GREEN, label="Click Me Too")
    )
]
await channel.send("Look, Buttons!", components=components)

# Automatic layout using spread_to_rows
components: list[ActionRow] = spread_to_rows(
    Button(style=ButtonStyle.GREEN, label="Click Me"),
    Button(style=ButtonStyle.GREEN, label="Click Me Too")
)
await channel.send("Look, Buttons!", components=components)

Extensions allow you to split your commands and listeners into separate files to better organize your project. This prevents your main file from becoming too large and provides the benefit of being able to reload specific parts of your bot without shutting it down.

To use extensions, you must:

1. Create a class that inherits from Extension.
2. Define your commands and listeners within that class.
3. Use bot.load_extension("module_name") in your main file to load the extension (using the module name without the .py extension).

Note: When defining commands inside an Extension class, you must include self as the first argument in your command functions (e.g., async def my_command(self, ctx):).

# File: `test_components.py`
from interactions import ActionRow, Button, ButtonStyle, Extension, slash_command

class ButtonExampleSkin(Extension):
    @slash_command()
    async def multiple_buttons(self, ctx):
        await ctx.send(
            "2 buttons in a row",
            components=[
                Button(style=ButtonStyle.BLURPLE, label="A blurple button"),
                Button(style=ButtonStyle.RED, label="A red button"),
            ],
        )

Subcommands allow you to group related commands under a single base command. This results in a structure like /base group command in Discord.

Note: Using subcommands or groups makes the base command itself unusable as a standalone command.

There are three ways to define them:

1. Decorator Pattern: Define the base command, then use @base_function.subcommand(...) for additional commands.
2. Repeat Definition: Define each subcommand as its own @slash_command with group_name and sub_cmd_name parameters. This is useful for splitting commands across multiple files.
3. Class Definition: Use the SlashCommand and .group() objects explicitly.

# Method 1: Decorator Pattern
@slash_command(
    name="base",
    description="My command base",
    group_name="group",
    group_description="My command group",
    sub_cmd_name="command",
    sub_cmd_description="My command",
)
async def my_command_function(ctx: SlashContext):
    await ctx.send("Hello World")

@my_command_function.subcommand(
    group_name="group",
    group_description="My command group",
    sub_cmd_name="second_command",
    sub_cmd_description="My second command",
)
async def my_second_command_function(ctx: SlashContext):
    await ctx.send("Hello World")

# Method 2: Repeat Definition (Good for multiple files)
@slash_command(
    name="base",
    description="My command base",
    group_name="group",
    group_description="My command group",
    sub_cmd_name="second_command",
    sub_cmd_description="My second command",
) 
async def my_second_command_function(ctx: SlashContext):
    await ctx.send("Hello World")

# Method 3: Class Definition
from interactions import SlashCommand

base = SlashCommand(name="base", description="My command base")
group = base.group(name="group", description="My command group")

@group.subcommand(sub_cmd_name="second_command", sub_cmd_description="My second command")
async def my_second_command_function(ctx: SlashContext):
    await ctx.send("Hello World")