Pincer Commands Module¶

Commands¶

command¶

@command(func=None, *, name=None, description='Description not set', enable_default=True, guild=None, cooldown=0, cooldown_scale=60, cooldown_scope=ThrottleScope.USER)¶

A decorator to create a slash command to register and respond to with the discord API from a function.

str - String int - Integer bool - Boolean float - Number pincer.objects.User - User pincer.objects.Channel - Channel pincer.objects.Role - Role pincer.objects.Mentionable - Mentionable

class Bot(Client):
    @command(
        name="test",
        description="placeholder"
    )
    async def test_command(
        self,
        ctx: MessageContext,
        amount: int,
        name: CommandArg[
            str,
            Description["Do something cool"],
            Choices[Choice["first value", 1], 5]
        ],
        optional_int: CommandArg[
            int,
            MinValue[10],
            MaxValue[100],
        ] = 50
    ):
        return Message(
            f"You chose {amount}, {name}, {letter}",
            flags=InteractionFlags.EPHEMERAL
        )

References from above:: Client, Message, MessageContext, InteractionFlags, Choices, Choice, CommandArg, Description, MinValue, MaxValue

Parameters

name (Optional[str]) – The name of the command
Default: None
description (Optional[str]) – The description of the command
Default: Description not set
enable_default (Optional[bool]) – Whether the command is enabled by default
Default: True
guild (Optional[Union[Snowflake, int, str]]) – What guild to add it to (don’t specify for global)
Default: None
cooldown (Optional[int]) – The amount of times in the cooldown_scale the command can be invoked
Default: 0
cooldown_scale (Optional[float]) – The ‘checking time’ of the cooldown
Default: 60
cooldown_scope (ThrottleScope) – What type of cooldown strategy to use
Default: ThrottleScope.USER

Raises

CommandIsNotCoroutine – If the command function is not a coro
InvalidCommandName – If the command name does not follow the regex ^[\w-]{1,32}$
InvalidCommandGuild – If the guild id is invalid
CommandDescriptionTooLong – Descriptions max 100 characters If the annotation on an argument is too long (also max 100)
CommandAlreadyRegistered – If the command already exists
TooManyArguments – Max 25 arguments to pass for commands
InvalidArgumentAnnotation – Annotation amount is max 25, Not a valid argument type, Annotations must consist of name and value

@message_command(func=None, *, name=None, enable_default=True, guild=None, cooldown=0, cooldown_scale=60, cooldown_scope=ThrottleScope.USER)¶

A decorator to create a user command to register and respond to the Discord API from a function.

class Bot(Client):
    @user_command
    async def test_message_command(
        self,
        ctx: MessageContext,
        message: UserMessage,
    ):
        return message.content

References from above:: Client, MessageContext, UserMessage, User, GuildMember,

Parameters

name (Optional[str]) – The name of the command
Default: None
enable_default (Optional[bool]) – Whether the command is enabled by default
Default: True
guild (Optional[Union[Snowflake, int, str]]) – What guild to add it to (don’t specify for global)
Default: None
cooldown (Optional[int]) – The amount of times in the cooldown_scale the command can be invoked
Default: 0
cooldown_scale (Optional[float]) – The ‘checking time’ of the cooldown
Default: 60
cooldown_scope (ThrottleScope) – What type of cooldown strategy to use
Default: ThrottleScope.USER

Raises

CommandIsNotCoroutine – If the command function is not a coro
InvalidCommandName – If the command name does not follow the regex ^[\w-]{1,32}$
InvalidCommandGuild – If the guild id is invalid
CommandDescriptionTooLong – Descriptions max 100 characters If the annotation on an argument is too long (also max 100)
CommandAlreadyRegistered – If the command already exists
InvalidArgumentAnnotation – Annotation amount is max 25, Not a valid argument type, Annotations must consist of name and value

@user_command(func=None, *, name=None, enable_default=True, guild=None, cooldown=0, cooldown_scale=60, cooldown_scope=ThrottleScope.USER)¶

A decorator to create a user command registering and responding to the Discord API from a function.

class Bot(Client):
    @user_command
    async def test_user_command(
        self,
        ctx: MessageContext,
        user: User,
        member: GuildMember
    ):
        if not member:
            # member is missing if this is a DM
            # This bot doesn't like being DMed so it won't respond
            return

        return f"Hello {user.name}, this is a Guild."

References from above:: Client, MessageContext, User, GuildMember,

Parameters

name (Optional[str]) – The name of the command
Default: None
enable_default (Optional[bool]) – Whether the command is enabled by default
Default: True
guild (Optional[Union[Snowflake, int, str]]) – What guild to add it to (don’t specify for global)
Default: None
cooldown (Optional[int]) – The amount of times in the cooldown_scale the command can be invoked
Default: 0
cooldown_scale (Optional[float]) – The ‘checking time’ of the cooldown
Default: 60
cooldown_scope (ThrottleScope) – What type of cooldown strategy to use
Default: ThrottleScope.USER

Raises

CommandIsNotCoroutine – If the command function is not a coro
InvalidCommandName – If the command name does not follow the regex ^[\w-]{1,32}$
InvalidCommandGuild – If the guild id is invalid
CommandDescriptionTooLong – Descriptions max 100 characters If the annotation on an argument is too long (also max 100)
CommandAlreadyRegistered – If the command already exists
InvalidArgumentAnnotation – Annotation amount is max 25, Not a valid argument type, Annotations must consist of name and value

Command Types¶

class Modifier¶

Bases: object

Modifies a CommandArg by being added to CommandArg’s args.

class Description¶

Bases: pincer.commands.arg_types.Modifier

Represents the description of an application command option

# Creates an int argument with the description "example description"
CommandArg[
    int,
    Description["example description"]
]

Parameters: desc (str) – The description for the command.

class Choices¶

Bases: pincer.commands.arg_types.Modifier

Represents a group of application command choices that a user can pick from

CommandArg[
    int,
    Choices[
        Choice["First Number", 10],
        20,
        50
    ]
]

Parameters: *choices (Union[Choice, str, int, float]) – A choice. If the type is not Choice, the same value will be used for the choice name and value.

class Choice¶

Bases: pincer.commands.arg_types.Modifier

Represents a choice that the user can pick from

Choices[
    Choice["First Number", 10],
    Choice["Second Number", 20]
]

Parameters

name (str) – The name of the choice
value (Union[int, str, float]) – The value of the choice

class MaxValue¶

Bases: pincer.commands.arg_types.Modifier

Represents the max value for a number

CommandArg[
    int,
    # The user can't pick a number above 10
    MaxValue[10]
]

Parameters: max_value (Union[float, int]) – The max value a user can choose.

class MinValue¶

Bases: pincer.commands.arg_types.Modifier

Represents the minimum value for a number

CommandArg[
    int,
    # The user can't pick a number below 10
    MinValue[10]
]

Parameters: min_value (Union[float, int]) – The minimum value a user can choose.

class ChannelTypes¶

Bases: pincer.commands.arg_types.Modifier

Represents a group of channel types that a user can pick from

CommandArg[
    Channel,
    # The user will only be able to choice between GUILD_TEXT and
    GUILD_TEXT channels.
    ChannelTypes[
        ChannelType.GUILD_TEXT,
        ChannelType.GUILD_VOICE
    ]
]

Parameters: *types (ChannelType) – A list of channel types that the user can pick from.

ChatCommandHandler¶

Attributes

client
managers
register

Methods

asyncadd_command
asyncadd_commands
asyncget_commands
asyncinitialize
asyncremove_command
asyncremove_commands
asyncupdate_command
asyncupdate_commands

class ChatCommandHandler¶

Bases: object

Metaclass containing methods used to handle various commands

client¶

The client object

Type: Client

managers¶

Dictionary of managers

Type: Dict[str, Any]

register¶

Dictionary of ClientCommandStructure

Type: Dict[str, ClientCommandStructure]

await add_command(cmd)¶

This function is a coroutine.

Add an app command

Parameters: cmd (AppCommand) – Command to add

await add_commands(commands)¶

This function is a coroutine.

Add a list of app commands

Parameters: commands (List[AppCommand]) – List of command objects to add

await get_commands()¶

This function is a coroutine.

Get a list of app commands

Returns: List of commands.
Return type: List[AppCommand]

await initialize()¶

This function is a coroutine.

Call methods of this class to refresh all app commands

await remove_command(cmd, keep=False)¶

This function is a coroutine.

Remove a specific command

Parameters

cmd (AppCommand) – What command to delete
keep (bool) – Whether the command should be removed from the ChatCommandHandler. Set to True to keep the command.
Default: False

await remove_commands(commands, /, keep=None)¶

This function is a coroutine.

Remove a list of commands

Parameters

commands (List[AppCommand]) – List of commands to delete
keep (List[AppCommand]) – List of commands that should not be removed from the ChatCommandHandler.
Default: None

await update_command(cmd, changes)¶

This function is a coroutine.

Update a command with changes

Parameters

cmd (AppCommand) – What command to update
changes (Dict[str, Any]) – Dictionary of changes

await update_commands(to_update)¶

This function is a coroutine.

Update a list of app commands with changes

Parameters: to_update (Dict[AppCommand, Dict[str, Any]]) – Dictionary of commands to changes where changes is a dictionary too