CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-py-cord

A modern, async-ready Python API wrapper for Discord with comprehensive bot development features

Overall
score

93%

Overview
Eval results
Files

commands-interactions.mddocs/

Commands and Interactions

Modern Discord application commands (slash commands, user commands, message commands) and comprehensive interaction handling. This system provides the foundation for creating interactive Discord applications with rich command interfaces.

Capabilities

Application Commands

Application commands are Discord's modern command system, providing slash commands, context menu commands, and rich interaction capabilities.

def slash_command(
    *,
    name: str = None,
    description: str = None,
    guild_ids: List[int] = None,
    name_localizations: Dict[str, str] = None,
    description_localizations: Dict[str, str] = None,
    default_member_permissions: Optional[Permissions] = None,
    dm_permission: bool = True,
    nsfw: bool = False,
    **kwargs
) -> Callable:
    """
    Create a slash command.
    
    Parameters:
    - name: str - Command name (1-32 characters, lowercase)
    - description: str - Command description (1-100 characters)
    - guild_ids: List[int] - Guilds where command is available
    - name_localizations: Dict[str, str] - Localized names
    - description_localizations: Dict[str, str] - Localized descriptions
    - default_member_permissions: Permissions - Default permissions required
    - dm_permission: bool - Whether command works in DMs
    - nsfw: bool - Whether command is age-restricted
    """

def user_command(
    *,
    name: str = None,
    guild_ids: List[int] = None,
    name_localizations: Dict[str, str] = None,
    default_member_permissions: Optional[Permissions] = None,
    dm_permission: bool = True,
    nsfw: bool = False,
    **kwargs
) -> Callable:
    """
    Create a user context menu command.
    
    Parameters:
    - name: str - Command name
    - guild_ids: List[int] - Guilds where command is available
    - name_localizations: Dict[str, str] - Localized names
    - default_member_permissions: Permissions - Default permissions required
    - dm_permission: bool - Whether command works in DMs
    - nsfw: bool - Whether command is age-restricted
    """

def message_command(
    *,
    name: str = None,
    guild_ids: List[int] = None,
    name_localizations: Dict[str, str] = None,
    default_member_permissions: Optional[Permissions] = None,
    dm_permission: bool = True,
    nsfw: bool = False,
    **kwargs
) -> Callable:
    """
    Create a message context menu command.
    
    Parameters:
    - name: str - Command name
    - guild_ids: List[int] - Guilds where command is available
    - name_localizations: Dict[str, str] - Localized names
    - default_member_permissions: Permissions - Default permissions required
    - dm_permission: bool - Whether command works in DMs
    - nsfw: bool - Whether command is age-restricted
    """

class ApplicationCommand:
    """
    Base class for application commands.
    """
    
    @property
    def id(self) -> Optional[int]:
        """The command's ID after registration."""
    
    @property
    def name(self) -> str:
        """The command name."""
    
    @property
    def description(self) -> str:
        """The command description."""
    
    @property
    def type(self) -> ApplicationCommandType:
        """The command type."""
    
    @property
    def guild_ids(self) -> Optional[List[int]]:
        """Guilds where the command is available."""
    
    @property
    def default_member_permissions(self) -> Optional[Permissions]:
        """Default permissions required."""
    
    @property
    def dm_permission(self) -> bool:
        """Whether the command works in DMs."""
    
    @property
    def nsfw(self) -> bool:
        """Whether the command is age-restricted."""

class SlashCommand(ApplicationCommand):
    """
    Represents a slash command.
    """
    
    @property
    def options(self) -> List[Option]:
        """The command's options."""
    
    @property
    def cog(self) -> Optional[Cog]:
        """The cog this command belongs to."""
    
    def add_option(self, option: Option) -> None:
        """Add an option to the command."""
    
    def remove_option(self, name: str) -> Optional[Option]:
        """Remove an option from the command."""

class SlashCommandGroup(ApplicationCommand):
    """
    Represents a group of slash commands.
    """
    
    @property
    def subcommands(self) -> List[SlashCommand]:
        """Subcommands in this group."""
    
    def command(
        self,
        *,
        name: str = None,
        description: str = None,
        **kwargs
    ) -> Callable:
        """Add a subcommand to the group."""
    
    def create_subgroup(
        self,
        name: str,
        description: str,
        **kwargs
    ) -> SlashCommandGroup:
        """Create a subgroup within this group."""

class ContextMenuCommand(ApplicationCommand):
    """
    Base class for context menu commands.
    """
    pass

class UserCommand(ContextMenuCommand):
    """
    Represents a user context menu command.
    """
    pass

class MessageCommand(ContextMenuCommand):
    """
    Represents a message context menu command.
    """
    pass

Command Options and Parameters

Options define the parameters that users can provide to slash commands.

class Option:
    """
    Represents a slash command option.
    """
    
    def __init__(
        self,
        input_type: SlashCommandOptionType,
        /,
        description: str,
        *,
        name: str = None,
        name_localizations: Dict[str, str] = None,
        description_localizations: Dict[str, str] = None,
        required: bool = True,
        default: Any = None,
        choices: List[OptionChoice] = None,
        channel_types: List[ChannelType] = None,
        min_value: Union[int, float] = None,
        max_value: Union[int, float] = None,
        min_length: int = None,
        max_length: int = None,
        autocomplete: bool = False,
        **kwargs
    ) -> None:
        """
        Create a command option.
        
        Parameters:
        - input_type: SlashCommandOptionType - The option type
        - description: str - Option description
        - name: str - Option name (defaults to parameter name)
        - name_localizations: Dict[str, str] - Localized names
        - description_localizations: Dict[str, str] - Localized descriptions
        - required: bool - Whether the option is required
        - default: Any - Default value if not provided
        - choices: List[OptionChoice] - Predefined choices
        - channel_types: List[ChannelType] - Allowed channel types
        - min_value: Union[int, float] - Minimum numeric value
        - max_value: Union[int, float] - Maximum numeric value
        - min_length: int - Minimum string length
        - max_length: int - Maximum string length
        - autocomplete: bool - Whether to enable autocomplete
        """
    
    @property
    def name(self) -> str: ...
    @property
    def description(self) -> str: ...
    @property
    def type(self) -> SlashCommandOptionType: ...
    @property
    def required(self) -> bool: ...
    @property
    def choices(self) -> Optional[List[OptionChoice]]: ...
    @property
    def channel_types(self) -> Optional[List[ChannelType]]: ...
    @property
    def min_value(self) -> Optional[Union[int, float]]: ...
    @property
    def max_value(self) -> Optional[Union[int, float]]: ...
    @property
    def min_length(self) -> Optional[int]: ...
    @property
    def max_length(self) -> Optional[int]: ...
    @property
    def autocomplete(self) -> bool: ...

class OptionChoice:
    """
    Represents a predefined choice for a command option.
    """
    
    def __init__(
        self,
        name: str,
        value: Union[str, int, float],
        *,
        name_localizations: Dict[str, str] = None
    ) -> None:
        """
        Create an option choice.
        
        Parameters:
        - name: str - Choice display name
        - value: Union[str, int, float] - Choice value
        - name_localizations: Dict[str, str] - Localized names
        """
    
    @property
    def name(self) -> str: ...
    @property
    def value(self) -> Union[str, int, float]: ...
    @property
    def name_localizations(self) -> Optional[Dict[str, str]]: ...

def option(
    name: str = None,
    *,
    description: str = None,
    input_type: SlashCommandOptionType = None,
    required: bool = None,
    default: Any = None,
    choices: List[Union[OptionChoice, str, int, float]] = None,
    autocomplete: bool = None,
    **kwargs
) -> Callable:
    """
    Decorator to define a command option inline.
    
    Parameters:
    - name: str - Option name
    - description: str - Option description
    - input_type: SlashCommandOptionType - Option type
    - required: bool - Whether required
    - default: Any - Default value
    - choices: List - Predefined choices
    - autocomplete: bool - Enable autocomplete
    """

class ThreadOption:
    """
    Special option for thread selection.
    """
    
    def __init__(
        self,
        description: str,
        *,
        name: str = None,
        required: bool = True
    ) -> None: ...

Application Context and Interaction Handling

Context objects provide access to interaction data and methods for responding to users.

class ApplicationContext:
    """
    Represents the context for an application command.
    """
    
    @property
    def bot(self) -> Bot:
        """The bot instance."""
    
    @property
    def interaction(self) -> Interaction:
        """The underlying interaction."""
    
    @property
    def command(self) -> ApplicationCommand:
        """The command being invoked."""
    
    @property
    def user(self) -> Union[User, Member]:
        """The user who invoked the command."""
    
    @property
    def author(self) -> Union[User, Member]:
        """Alias for user."""
    
    @property
    def guild(self) -> Optional[Guild]:
        """The guild where the command was invoked."""
    
    @property
    def channel(self) -> Union[GuildChannel, DMChannel, PartialMessageable]:
        """The channel where the command was invoked."""
    
    @property
    def guild_id(self) -> Optional[int]:
        """The guild ID."""
    
    @property
    def channel_id(self) -> int:
        """The channel ID."""
    
    @property
    def locale(self) -> str:
        """The user's locale."""
    
    @property
    def guild_locale(self) -> Optional[str]:
        """The guild's locale."""
    
    @property
    def created_at(self) -> datetime:
        """When the interaction was created."""
    
    @property
    def selected_options(self) -> Dict[str, Any]:
        """Selected command options."""
    
    def get_parameter(self, name: str) -> Any:
        """Get a parameter value by name."""
    
    async def respond(
        self,
        content: str = None,
        *,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        tts: bool = False,
        ephemeral: bool = False,
        allowed_mentions: AllowedMentions = None,
        file: File = None,
        files: List[File] = None,
        suppress_embeds: bool = False,
        **kwargs
    ) -> Union[Interaction, InteractionMessage]:
        """
        Respond to the interaction.
        
        Parameters:
        - content: str - Response content
        - embed: Embed - Rich embed
        - embeds: List[Embed] - Multiple embeds
        - view: View - UI components
        - tts: bool - Text-to-speech
        - ephemeral: bool - Whether response is ephemeral
        - allowed_mentions: AllowedMentions - Mention settings
        - file: File - File attachment
        - files: List[File] - Multiple files
        - suppress_embeds: bool - Suppress embeds
        """
    
    async def defer(self, *, ephemeral: bool = False, invisible: bool = True) -> None:
        """
        Defer the interaction response.
        
        Parameters:
        - ephemeral: bool - Whether the deferred response is ephemeral
        - invisible: bool - Whether to show a loading state
        """
    
    async def followup(
        self,
        content: str = None,
        *,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        tts: bool = False,
        ephemeral: bool = False,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> InteractionMessage:
        """Send a followup message after responding or deferring."""
    
    async def edit(
        self,
        *,
        content: str = None,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> InteractionMessage:
        """Edit the original interaction response."""
    
    async def delete(self, *, delay: float = None) -> None:
        """Delete the original interaction response."""
    
    async def send_modal(self, modal: Modal) -> None:
        """Send a modal dialog in response to the interaction."""

class AutocompleteContext:
    """
    Context for autocomplete interactions.
    """
    
    @property
    def bot(self) -> Bot: ...
    @property
    def interaction(self) -> Interaction: ...
    @property
    def user(self) -> Union[User, Member]: ...
    @property
    def guild(self) -> Optional[Guild]: ...
    @property
    def channel(self) -> Union[GuildChannel, DMChannel]: ...
    @property
    def focused(self) -> Option:
        """The option being autocompleted."""
    
    @property
    def value(self) -> str:
        """The current input value."""
    
    @property
    def options(self) -> Dict[str, Any]:
        """All current option values."""
    
    async def send_choices(
        self,
        choices: Union[List[OptionChoice], List[str], List[int], List[float]]
    ) -> None:
        """Send autocomplete choices."""

Interaction Objects

Core interaction classes that handle Discord's interaction system.

class Interaction:
    """
    Represents a Discord interaction.
    """
    
    @property
    def id(self) -> int:
        """The interaction ID."""
    
    @property
    def type(self) -> InteractionType:
        """The interaction type."""
    
    @property
    def data(self) -> Optional[Dict[str, Any]]:
        """The interaction data."""
    
    @property
    def guild_id(self) -> Optional[int]:
        """The guild ID."""
    
    @property
    def guild(self) -> Optional[Guild]:
        """The guild."""
    
    @property
    def channel_id(self) -> Optional[int]:
        """The channel ID."""
    
    @property
    def channel(self) -> Optional[Union[GuildChannel, DMChannel, PartialMessageable]]:
        """The channel."""
    
    @property
    def user(self) -> Union[User, Member]:
        """The user who created the interaction."""
    
    @property
    def message(self) -> Optional[Message]:
        """The message associated with the interaction."""
    
    @property
    def token(self) -> str:
        """The interaction token."""
    
    @property
    def version(self) -> int:
        """The interaction version."""
    
    @property
    def application_id(self) -> int:
        """The application ID."""
    
    @property
    def locale(self) -> str:
        """The user's locale."""
    
    @property
    def guild_locale(self) -> Optional[str]:
        """The guild's locale."""
    
    @property
    def created_at(self) -> datetime:
        """When the interaction was created."""
    
    @property
    def expires_at(self) -> datetime:
        """When the interaction expires."""
    
    @property
    def is_expired(self) -> bool:
        """Whether the interaction has expired."""
    
    @property
    def response(self) -> InteractionResponse:
        """The interaction response handler."""
    
    async def original_response(self) -> InteractionMessage:
        """Get the original interaction response."""
    
    async def edit_original_response(
        self,
        *,
        content: str = None,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> InteractionMessage:
        """Edit the original response."""
    
    async def delete_original_response(self) -> None:
        """Delete the original response."""
    
    async def followup(
        self,
        content: str = None,
        *,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        tts: bool = False,
        ephemeral: bool = False,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> InteractionMessage:
        """Send a followup message."""

class InteractionResponse:
    """
    Handles responding to interactions.
    """
    
    def __init__(self, interaction: Interaction) -> None: ...
    
    @property
    def is_done(self) -> bool:
        """Whether a response has been sent."""
    
    async def send_message(
        self,
        content: str = None,
        *,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        tts: bool = False,
        ephemeral: bool = False,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> None:
        """Send a response message."""
    
    async def defer(self, *, ephemeral: bool = False, invisible: bool = True) -> None:
        """Defer the response."""
    
    async def edit_message(
        self,
        *,
        content: str = None,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> None:
        """Edit the original message (for component interactions)."""
    
    async def send_modal(self, modal: Modal) -> None:
        """Send a modal response."""
    
    async def autocomplete(
        self,
        choices: List[OptionChoice]
    ) -> None:
        """Send autocomplete choices."""

class InteractionMessage:
    """
    Represents a message sent via interaction.
    """
    
    @property
    def id(self) -> int: ...
    @property
    def type(self) -> MessageType: ...
    @property
    def author(self) -> Union[User, Member]: ...
    @property
    def content(self) -> str: ...
    @property
    def embeds(self) -> List[Embed]: ...
    @property
    def attachments(self) -> List[Attachment]: ...
    @property
    def created_at(self) -> datetime: ...
    @property
    def edited_at(self) -> Optional[datetime]: ...
    @property
    def flags(self) -> MessageFlags: ...
    @property
    def components(self) -> List[Component]: ...
    
    async def edit(
        self,
        *,
        content: str = None,
        embed: Embed = None,
        embeds: List[Embed] = None,
        view: View = None,
        file: File = None,
        files: List[File] = None,
        **kwargs
    ) -> InteractionMessage:
        """Edit the message."""
    
    async def delete(self, *, delay: float = None) -> None:
        """Delete the message."""

class MessageInteraction:
    """
    Represents the interaction that created a message.
    """
    
    @property
    def id(self) -> int: ...
    @property
    def type(self) -> InteractionType: ...
    @property
    def name(self) -> str: ...
    @property
    def user(self) -> Union[User, Member]: ...

Command Permissions and Restrictions

Functions and decorators for controlling command access and behavior.

def default_permissions(**perms) -> Callable:
    """
    Set default permissions required for a command.
    
    Parameters:
    **perms: Permission flags (e.g., manage_messages=True)
    """

def guild_only() -> Callable:
    """Restrict command to guilds only (not DMs)."""

def is_nsfw() -> Callable:
    """Mark command as NSFW (age-restricted)."""

def describe(**kwargs) -> Callable:
    """
    Add descriptions to command parameters.
    
    Parameters:
    **kwargs: Parameter descriptions (parameter_name="description")
    """

def checks_any(*checks) -> Callable:
    """
    Require that any of the given checks pass.
    
    Parameters:
    *checks: Check functions to evaluate
    """

def has_permissions(**perms) -> Callable:
    """
    Check if user has specific permissions.
    
    Parameters:
    **perms: Permission flags to check
    """

def has_role(role: Union[int, str, Role]) -> Callable:
    """
    Check if user has a specific role.
    
    Parameters:
    - role: Role ID, name, or Role object
    """

def has_any_role(*roles: Union[int, str, Role]) -> Callable:
    """
    Check if user has any of the specified roles.
    
    Parameters:
    *roles: Role IDs, names, or Role objects
    """

def bot_has_permissions(**perms) -> Callable:
    """
    Check if bot has specific permissions.
    
    Parameters:
    **perms: Permission flags to check
    """

def is_owner() -> Callable:
    """Check if user is the bot owner."""

class Permissions:
    """Check class for permission verification."""
    
    def __init__(self, **perms) -> None: ...
    
    def predicate(self, ctx: ApplicationContext) -> bool:
        """Check if permissions are satisfied."""

Enumerations for Commands

Command-related enumerations and constants.

class ApplicationCommandType(Enum):
    """Application command types."""
    chat_input = 1      # Slash command
    user = 2            # User context menu
    message = 3         # Message context menu

class SlashCommandOptionType(Enum):
    """Slash command option types."""
    sub_command = 1
    sub_command_group = 2
    string = 3
    integer = 4
    boolean = 5
    user = 6
    channel = 7
    role = 8
    mentionable = 9
    number = 10
    attachment = 11

class InteractionType(Enum):
    """Interaction types."""
    ping = 1
    application_command = 2
    message_component = 3
    application_command_autocomplete = 4
    modal_submit = 5

class InteractionResponseType(Enum):
    """Interaction response types."""
    pong = 1
    channel_message_with_source = 4
    deferred_channel_message_with_source = 5
    deferred_update_message = 6
    update_message = 7
    application_command_autocomplete_result = 8
    modal = 9

class InteractionContextType(Enum):
    """Where interactions can be used."""
    guild = 0
    bot_dm = 1
    private_channel = 2

class IntegrationType(Enum):
    """Integration types for applications."""
    guild_install = 0
    user_install = 1

The commands and interactions system provides comprehensive support for Discord's modern application command framework, enabling rich interactive experiences with slash commands, context menus, autocomplete, and sophisticated user interfaces.

Install with Tessl CLI

npx tessl i tessl/pypi-py-cord

docs

commands-interactions.md

core-clients.md

discord-objects.md

error-handling.md

extensions.md

index.md

ui-components.md

utilities-helpers.md

tile.json