tanjun.commands#

Standard implementations of Tanjun's command objects.

Menu command implementations.

Bases: PartialCommand[MenuContext], MenuCommand[_AnyMenuCallbackSigT, _MenuTypeT]

Base class used for the standard menu command implementations.

wrapped_command

The command object this wraps, if any.

__init__(callback: _UserCallbackSigT, type_: typing.Literal[hikari.CommandType.USER], name: str | collections.Mapping[str, str], /, *, always_defer: bool = False, default_member_permissions: hikari.Permissions | int | None = None, default_to_ephemeral: bool | None = None, dm_enabled: bool | None = None, is_global: bool = True, nsfw: bool = False, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback: _AnyCommandT[_UserCallbackSigT], type_: typing.Literal[hikari.CommandType.USER], name: str | collections.Mapping[str, str], /, *, always_defer: bool = False, default_member_permissions: hikari.Permissions | int | None = None, default_to_ephemeral: bool | None = None, dm_enabled: bool | None = None, is_global: bool = True, nsfw: bool = False, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback: _MessageCallbackSigT, type_: typing.Literal[hikari.CommandType.MESSAGE], name: str | collections.Mapping[str, str], /, *, always_defer: bool = False, default_member_permissions: hikari.Permissions | int | None = None, default_to_ephemeral: bool | None = None, dm_enabled: bool | None = None, is_global: bool = True, nsfw: bool = False, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback: _AnyCommandT[_MessageCallbackSigT], type_: typing.Literal[hikari.CommandType.MESSAGE], name: str | collections.Mapping[str, str], /, *, always_defer: bool = False, default_member_permissions: hikari.Permissions | int | None = None, default_to_ephemeral: bool | None = None, dm_enabled: bool | None = None, is_global: bool = True, nsfw: bool = False, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback, type_, name, /, *, always_defer=False, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, is_global=True, nsfw=False, _wrapped_command=None)

Initialise a user or message menu command.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Note

If you want your first response to be ephemeral while using always_defer, you must set default_to_ephemeral to True.

Parameters:

callback (MenuCallbackSig) –

Callback to execute when the command is invoked.

This should be an asynchronous callback which takes one positional argument of type tanjun.abc.MenuContext, returns None and may use dependency injection to access other services.
type_ (CommandType) –

The type of menu command this is.

Only CommandType.USER and CommandType.MESSAGE are valid here.
name (str | Mapping[str, str]) –

The command's name (supports localisation).

This must be between 1 and 32 characters in length.
always_defer (bool, default: False ) –

Whether the contexts this command is executed with should always be deferred before being passed to the command's callback.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.

Returns:

Callable[[MenuCallbackSig], MenuCommand] –

The decorator callback used to make a MenuCommand.

This can either wrap a raw command callback or another callable command instance (e.g. MenuCommand, tanjun.MessageCommand, tanjun.SlashCommand) and will manage loading the other command into a component when using Component.load_from_scope.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name isn't in the length range of 1 to 32.
- If the command name has uppercase characters.

set_ephemeral_default(state)

Set whether this command's responses should default to ephemeral.

Parameters:

state (bool | None) –

Whether this command's responses should default to ephemeral. This will be overridden by any response calls which specify flags.

Setting this to None will let the default set on the parent command(s), component or client propagate and decide the ephemeral default for contexts used by this command.

Returns:

Self –

This command to allow for chaining.

as_message_menu(name, /, *, always_defer=False, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, is_global=True, nsfw=False)

Build a message MenuCommand by decorating a function.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Note

If you want your first response to be ephemeral while using always_defer, you must set default_to_ephemeral to True.

Examples:

@as_message_menu("message")
async def message_command(self, ctx: tanjun.abc.MenuContext, message: hikari.Message) -> None:
    await ctx.respond(
        embed=hikari.Embed(title="Message content", description=message.content or "N/A")
    )

Parameters:

name (str | Mapping[str, str]) –

The command's name (supports localisation).

This must be between 1 and 32 characters in length.
always_defer (bool, default: False ) –

Whether the contexts this command is executed with should always be deferred before being passed to the command's callback.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.

Returns:

Callable[[MenuCallbackSig], MenuCommand] –

The decorator callback used to make a MenuCommand.

This can either wrap a raw command callback or another callable command instance (e.g. MenuCommand, tanjun.MessageCommand, tanjun.SlashCommand) and will manage loading the other command into a component when using Component.load_from_scope.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name isn't in the length range of 1 to 32.
- If the command name has uppercase characters.

as_user_menu(name, /, *, always_defer=False, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, is_global=True, nsfw=False)

Build a user MenuCommand by decorating a function.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Note

If you want your first response to be ephemeral while using always_defer, you must set default_to_ephemeral to True.

Examples:

@as_user_menu("user")
async def user_command(
    self,
    ctx: tanjun.abc.MenuContext,
    user: hikari.User | hikari.InteractionMember,
) -> None:
    await ctx.respond(f"Hello {user}")

Parameters:

name (str | Mapping[str, str]) –

The command's name (supports localisation).

This must be between 1 and 32 characters in length.
always_defer (bool, default: False ) –

Whether the contexts this command is executed with should always be deferred before being passed to the command's callback.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.

Returns:

Callable[[MenuCallbackSig], MenuCommand] –

The decorator callback used to make a MenuCommand.

This can either wrap a raw command callback or another callable command instance (e.g. MenuCommand, tanjun.MessageCommand, tanjun.SlashCommand) and will manage loading the other command into a component when using Component.load_from_scope.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name isn't in the length range of 1 to 32.
- If the command name has uppercase characters.

tanjun.commands.message #

Message command implementations.

MessageCommand #

Bases: PartialCommand[MessageContext], MessageCommand[_MessageCallbackSigT]

Standard implementation of a message command.

wrapped_command `property` #

wrapped_command

The command object this wraps, if any.

init #

__init__(callback: _MessageCallbackSigT, name: str, /, *names: str, validate_arg_keys: bool = True, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback: _AnyCommandT[_MessageCallbackSigT], name: str, /, *names: str, validate_arg_keys: bool = True, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback, name, /, *names, validate_arg_keys=True, _wrapped_command=None)

Initialise a message command.

Parameters:

callback (MessageCallbackSig) –

Callback to execute when the command is invoked.

This should be an asynchronous callback which takes one positional argument of type tanjun.abc.MessageContext, returns None and may use dependency injection to access other services.
name (str) –

The command name.
*names (str, default: () ) –

Other names for the command.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

MessageCommandGroup #

Bases: MessageCommand[_MessageCallbackSigT], MessageCommandGroup[_MessageCallbackSigT]

Standard implementation of a message command group.

wrapped_command `property` #

wrapped_command

The command object this wraps, if any.

init #

__init__(callback: _MessageCallbackSigT, name: str, /, *names: str, strict: bool = False, validate_arg_keys: bool = True, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback: _AnyCommandT[_MessageCallbackSigT], name: str, /, *names: str, strict: bool = False, validate_arg_keys: bool = True, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback, name, /, *names, strict=False, validate_arg_keys=True, _wrapped_command=None)

Initialise a message command group.

Parameters:

callback (MessageCallbackSig) –

Callback to execute when the command is invoked.

This should be an asynchronous callback which takes one positional argument of type tanjun.abc.MessageContext, returns None and may use dependency injection to access other services.
name (str) –

The command name.
*names (str, default: () ) –

Other names for the command.
strict (bool, default: False ) –

Whether this command group should only allow commands without spaces in their names.

This allows for a more optimised command search pattern to be used and enforces that command names are unique to a single command within the group.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

add_command #

add_command(command)

Add a command to this group.

Parameters:

command (MessageCommand[Any]) –

The command to add.

Returns:

Self –

The group instance to enable chained calls.

Raises:

ValueError –

If one of the command's names is already registered in a strict command group.

as_sub_command #

as_sub_command(name, /, *names, validate_arg_keys=True)

Build a message command in this group from a decorated callback.

Parameters:

name (str) –

The command name.
*names (str, default: () ) –

Other names for the command.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Returns:

Callable[[MessageCallbackSig], MessageCommand] –

The decorator callback used to make a sub-command.

This can either wrap a raw command callback or another callable command instance (e.g. tanjun.MenuCommand, MessageCommand, tanjun.SlashCommand).

as_sub_group #

as_sub_group(name, /, *names, strict=False, validate_arg_keys=True)

Build a message command group in this group from a decorated callback.

Parameters:

name (str) –

The command name.
*names (str, default: () ) –

Other names for the command.
strict (bool, default: False ) –

Whether this command group should only allow commands without spaces in their names.

This allows for a more optimised command search pattern to be used and enforces that command names are unique to a single command within the group.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Returns:

Callable[[MessageCallbackSig], MessageCommand] –

The decorator callback used to make a sub-command group.

This can either wrap a raw command callback or another callable command instance (e.g. tanjun.MenuCommand, MessageCommand, tanjun.SlashCommand).

as_message_command #

as_message_command(name, /, *names, validate_arg_keys=True)

Build a message command from a decorated callback.

Parameters:

name (str) –

The command name.
*names (str, default: () ) –

Other names for the command.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Returns:

Callable[[MessageCallbackSig], MessageCommand] –

The decorator callback used to make a MessageCommand.

This can either wrap a raw command callback or another callable command instance (e.g. tanjun.MenuCommand, MessageCommand, tanjun.SlashCommand) and will manage loading the other command into a component when using Component.load_from_scope.

as_message_command_group #

as_message_command_group(name, /, *names, strict=False, validate_arg_keys=True)

Build a message command group from a decorated callback.

Parameters:

name (str) –

The command name.
*names (str, default: () ) –

Other names for the command.
strict (bool, default: False ) –

Whether this command group should only allow commands without spaces in their names.

This allows for a more optimised command search pattern to be used and enforces that command names are unique to a single command within the group.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Returns:

Callable[[MessageCallbackSig], MessageCommand] –

The decorator callback used to make a MessageCommandGroup.

This can either wrap a raw command callback or another callable command instance (e.g. tanjun.MenuCommand, MessageCommandGroup, tanjun.SlashCommand) and will manage loading the other command into a component when using Component.load_from_scope.

tanjun.commands.slash #

Slash command implementations.

ConverterSig `module-attribute` #

ConverterSig = Callable[Concatenate[_ConvertT, ...], Coroutine[Any, Any, Any] | Any]

Type hint of a slash command option converter.

This represents the signatures def (int | float | str, ...) -> Any and async def (int | float | str, ...) -> None where dependency injection is supported.

UNDEFINED_DEFAULT `module-attribute` #

UNDEFINED_DEFAULT = NO_DEFAULT

Deprecated alias for tanjun.abc.NO_DEFAULT.

BaseSlashCommand #

Bases: PartialCommand[SlashContext], BaseSlashCommand

Base class used for the standard slash command implementations.

build `abstractmethod` #

build(*, component=None)

Get a builder object for this command.

Parameters:

component (Component | None, default: None ) –

The component to inherit config like default_member_permissions and is_dm_enabled from if not explicitly set on the command.

This defaults to the command's linked component.

Returns:

SlashCommandBuilder –

A builder object for this command. Use to declare this command on globally or for a specific guild.

set_ephemeral_default #

set_ephemeral_default(state)

Set whether this command's responses should default to ephemeral.

Parameters:

state (bool | None) –

Whether this command's responses should default to ephemeral. This will be overridden by any response calls which specify flags.

Setting this to None will let the default set on the parent command(s), component or client propagate and decide the ephemeral default for contexts used by this command.

Returns:

Self –

This command to allow for chaining.

SlashCommand #

Bases: BaseSlashCommand, SlashCommand[_SlashCallbackSigT]

Standard implementation of a slash command.

wrapped_command `property` #

wrapped_command

The command object this wraps, if any.

init #

__init__(callback: _SlashCallbackSigT, name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, always_defer: bool = False, default_member_permissions: hikari.Permissions | int | None = None, default_to_ephemeral: bool | None = None, dm_enabled: bool | None = None, is_global: bool = True, nsfw: bool = False, sort_options: bool = True, validate_arg_keys: bool = True, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback: _AnyCommandT[_SlashCallbackSigT], name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, always_defer: bool = False, default_member_permissions: hikari.Permissions | int | None = None, default_to_ephemeral: bool | None = None, dm_enabled: bool | None = None, is_global: bool = True, nsfw: bool = False, sort_options: bool = True, validate_arg_keys: bool = True, _wrapped_command: tanjun.ExecutableCommand[typing.Any] | None = None) -> None

__init__(callback, name, description, /, *, always_defer=False, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, is_global=True, nsfw=False, sort_options=True, validate_arg_keys=True, _wrapped_command=None)

Initialise a slash command.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Warning

default_member_permissions, dm_enabled and is_global are ignored for commands within slash command groups.

Note

If you want your first response to be ephemeral while using always_defer, you must set default_to_ephemeral to True.

Parameters:

callback (SlashCallbackSig) –

Callback to execute when the command is invoked.

This should be an asynchronous callback which takes one positional argument of type tanjun.abc.SlashContext, returns None and may use dependency injection to access other services.
name (str | Mapping[str, str]) –

The command's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The command's description (supports localisation).

This should be inclusively between 1-100 characters in length.
always_defer (bool, default: False ) –

Whether the contexts this command is executed with should always be deferred before being passed to the command's callback.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.
sort_options (bool, default: True ) –

Whether this command should sort its set options based on whether they're required.

If this is True then the options are re-sorted to meet the requirement from Discord that required command options be listed before optional ones.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name doesn't fit Discord's requirements.
- If the command name has uppercase characters.
- If the description is over 100 characters long.

add_attachment_option #

add_attachment_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add an attachment option to the slash command.

Note

This will result in options of type hikari.Attachment.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used and the converters field will be ignored.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_bool_option #

add_bool_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a boolean option to a slash command.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_channel_option #

add_channel_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, types=None, pass_as_kwarg=True)

Add a channel option to a slash command.

Note

This will always result in hikari.InteractionChannel.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
types (Collection[type[PartialChannel] | int] | None, default: None ) –

A collection of the channel classes and types this option should accept.

If left as None or empty then the option will allow all channel types.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the command already has 25 options.
- If an invalid type is passed in types.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_float_option #

add_float_option(name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, always_float: bool = True, autocomplete: tanjun.AutocompleteSig[float] | None = None, choices: collections.Mapping[str, float] | collections.Sequence[hikari.CommandChoice] | None = None, converters: collections.Sequence[ConverterSig[float]] | ConverterSig[float] = (), default: typing.Any = tanjun.NO_DEFAULT, key: str | None = None, min_value: float | None = None, max_value: float | None = None, pass_as_kwarg: bool = True, _stack_level: int = 0) -> Self

add_float_option(name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, always_float: bool = True, autocomplete: tanjun.AutocompleteSig[float] | None = None, choices: collections.Sequence[tuple[str, float]], converters: collections.Sequence[ConverterSig[float]] | ConverterSig[float] = (), default: typing.Any = tanjun.NO_DEFAULT, key: str | None = None, min_value: float | None = None, max_value: float | None = None, pass_as_kwarg: bool = True, _stack_level: int = 0) -> Self

add_float_option(name, description, /, *, always_float=True, autocomplete=None, choices=None, converters=(), default=tanjun.NO_DEFAULT, key=None, min_value=None, max_value=None, pass_as_kwarg=True, _stack_level=0)

Add a float option to a slash command.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
always_float (bool, default: True ) –

If this is set to True then the value will always be converted to a float (this will happen before it's passed to converters).

This masks behaviour from Discord where we will either be provided a float or int dependent on what the user provided.
autocomplete (AutocompleteSig[float] | None, default: None ) –

The autocomplete callback for the option.

More information on this callback's signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type float.
choices (Mapping[str, float] | None, default: None ) –

The option's choices.

This is a mapping of [option_name, option_value] where option_name should be a string of up to 100 characters and option_value should be a float.
converters (Sequence[ConverterSig[float]] | ConverterSig[float], default: () ) –

The option's converters.

This may be either one or multiple converter callbacks used to convert the option's value to the final form. If no converters are provided then the raw value will be passed.

Only the first converter to pass will be used.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
min_value (float | None, default: None ) –

The option's (inclusive) minimum value.
max_value (float | None, default: None ) –

The option's (inclusive) maximum value.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used and the fields converters, and always_float will be ignored.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the option has more than 25 choices.
- If the command already has 25 options.
- If min_value is greater than max_value.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_int_option #

add_int_option(name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, autocomplete: tanjun.AutocompleteSig[int] | None = None, choices: collections.Mapping[str, int] | collections.Sequence[hikari.CommandChoice] | None = None, converters: collections.Sequence[ConverterSig[int]] | ConverterSig[int] = (), default: typing.Any = tanjun.NO_DEFAULT, key: str | None = None, min_value: int | None = None, max_value: int | None = None, pass_as_kwarg: bool = True, _stack_level: int = 0) -> Self

add_int_option(name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, autocomplete: tanjun.AutocompleteSig[int] | None = None, choices: collections.Sequence[tuple[str, int]], converters: collections.Sequence[ConverterSig[int]] | ConverterSig[int] = (), default: typing.Any = tanjun.NO_DEFAULT, key: str | None = None, min_value: int | None = None, max_value: int | None = None, pass_as_kwarg: bool = True, _stack_level: int = 0) -> Self

add_int_option(name, description, /, *, autocomplete=None, choices=None, converters=(), default=tanjun.NO_DEFAULT, key=None, min_value=None, max_value=None, pass_as_kwarg=True, _stack_level=0)

Add an integer option to the slash command.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
autocomplete (AutocompleteSig[int] | None, default: None ) –

The autocomplete callback for the option.

More information on this callback's signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type int.
choices (Mapping[str, int] | None, default: None ) –

The option's choices.

This is a mapping of [option_name, option_value] where option_name should be a string of up to 100 characters and option_value should be an integer.
converters (Sequence[ConverterSig[int]] | ConverterSig[int], default: () ) –

The option's converters.

This may be either one or multiple converter callbacks used to convert the option's value to the final form. If no converters are provided then the raw value will be passed.

Only the first converter to pass will be used.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as undefined then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
min_value (int | None, default: None ) –

The option's (inclusive) minimum value.
max_value (int | None, default: None ) –

The option's (inclusive) maximum value.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used and the converters field will be ignored.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the option has more than 25 choices.
- If the command already has 25 options.
- If min_value is greater than max_value.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_member_option #

add_member_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None)

Add a member option to a slash command.

Note

This will always result in hikari.InteractionMember.

Warning

Unlike the other options, this is an artificial option which adds a restraint to the USER option type and therefore cannot have pass_as_kwarg set to False as this artificial constraint isn't present when its not being passed as a keyword argument.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_mentionable_option #

add_mentionable_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a mentionable option to a slash command.

Note

This may target roles, guild members or users and results in hikari.User | hikari.InteractionMember | hikari.Role.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_role_option #

add_role_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a role option to a slash command.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.

add_str_option #

add_str_option(name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, autocomplete: tanjun.AutocompleteSig[str] | None = None, choices: collections.Mapping[str, str] | collections.Sequence[str] | collections.Sequence[hikari.CommandChoice] | None = None, converters: collections.Sequence[ConverterSig[str]] | ConverterSig[str] = (), default: typing.Any = tanjun.NO_DEFAULT, key: str | None = None, min_length: int | None = None, max_length: int | None = None, pass_as_kwarg: bool = True, _stack_level: int = 0) -> Self

add_str_option(name: str | collections.Mapping[str, str], description: str | collections.Mapping[str, str], /, *, autocomplete: tanjun.AutocompleteSig[str] | None = None, choices: collections.Sequence[tuple[str, str]], converters: collections.Sequence[ConverterSig[str]] | ConverterSig[str] = (), default: typing.Any = tanjun.NO_DEFAULT, key: str | None = None, min_length: int | None = None, max_length: int | None = None, pass_as_kwarg: bool = True, _stack_level: int = 0) -> Self

add_str_option(name, description, /, *, autocomplete=None, choices=None, converters=(), default=tanjun.NO_DEFAULT, key=None, min_length=None, max_length=None, pass_as_kwarg=True, _stack_level=0)

Add a string option to the slash command.

Note

As a shorthand, choices also supports passing a list of strings rather than a dict of names to values (each string will used as both the choice's name and value with the names being capitalised).

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
autocomplete (AutocompleteSig[str] | None, default: None ) –

The autocomplete callback for the option.

More information on this callback's signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type str.
choices ((Mapping[str, str], Sequence[str] | None), default: None ) –

The option's choices.

This either a mapping of [option_name, option_value] where both option_name and option_value should be strings of up to 100 characters or a sequence of strings where the string will be used for both the choice's name and value.

Passing a sequence of tuples here is deprecated.
converters (Sequence[ConverterSig[str]] | ConverterSig[str], default: () ) –

The option's converters.

This may be either one or multiple converter callbacks used to convert the option's value to the final form. If no converters are provided then the raw value will be passed.

Only the first converter to pass will be used.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
min_length (int | None, default: None ) –

The minimum length of this string.

This must be greater than or equal to 0, and less than or equal to max_length and 6000.
max_length (int | None, default: None ) –

The maximum length of this string.

This must be greater then or equal to min_length and 1, and less than or equal to 6000.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used and the converters field will be ignored.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the option has more than 25 choices.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.
- If min_length is greater than max_length.
- If min_length is less than 0 or greater than 6000.
- If max_length is less than 1 or greater than 6000.

add_user_option #

add_user_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a user option to a slash command.

Note

This may result in hikari.InteractionMember or hikari.User if the user isn't in the current guild or if this command was executed in a DM channel.

Parameters:

name (str | Mapping[str, str]) –

The option's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The option's description (supports localisation).

This should be inclusively between 1-100 characters in length.
default (Any, default: NO_DEFAULT ) –

The option's default value.

If this is left as no default then this option will be required.

If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.
key (str | None, default: None ) –

Name of the argument this option's value should be passed to.

This defaults to the first name provided in name and is no-op if pass_as_kwarg is False.
pass_as_kwarg (bool, default: True ) –

Whether or not to pass this option as a keyword argument to the command callback.

If False is passed here then default will only decide whether the option is required without the actual value being used.

Returns:

Self –

The command object for chaining.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the option name doesn't fit Discord's requirements.
- If the option name has uppercase characters.
- If the option description is over 100 characters in length.
- If the option has more than 25 choices.
- If the command already has 25 options.
- If name isn't valid for this command's callback when validate_arg_keys is True.

set_ephemeral_default #

set_ephemeral_default(state)

Set whether this command's responses should default to ephemeral.

Parameters:

state (bool | None) –

Whether this command's responses should default to ephemeral. This will be overridden by any response calls which specify flags.

Setting this to None will let the default set on the parent command(s), component or client propagate and decide the ephemeral default for contexts used by this command.

Returns:

Self –

This command to allow for chaining.

set_float_autocomplete #

set_float_autocomplete(name, callback)

Set the autocomplete callback for a float option.

Parameters:

name (str) –

The option's name.

If localised names were provided for the option then this should be the default name.
callback (AutocompleteSig[float] | None) –

The autocomplete callback for the option.

More information on this callback's signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type float.

Passing None here will remove the autocomplete callback for the option.

Returns:

Self –

The command object for chaining.

Raises:

KeyError –

Raises a key error if the option doesn't exist.
TypeError –

Raises a type error if the option isn't of type float.

set_int_autocomplete #

set_int_autocomplete(name, callback)

Set the autocomplete callback for a string option.

Parameters:

name (str) –

The option's name.

If localised names were provided for the option then this should be the default name.
callback (AutocompleteSig[int]) –

The autocomplete callback for the option.

More information on this callback's signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type str.

Passing None here will remove the autocomplete callback for the option.

Returns:

Self –

The command object for chaining.

Raises:

KeyError –

Raises a key error if the option doesn't exist.
TypeError –

Raises a type error if the option isn't of type str.

set_str_autocomplete #

set_str_autocomplete(name, callback)

Set the autocomplete callback for a str option.

Parameters:

name (str) –

The option's name.

If localised names were provided for the option then this should be the default name.
callback (AutocompleteSig[str]) –

The autocomplete callback for the option.

More information on this callback's signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type str.

Passing None here will remove the autocomplete callback for the option.

Returns:

Self –

The command object for chaining.

Raises:

KeyError –

Raises a key error if the option doesn't exist.
TypeError –

Raises a type error if the option isn't of type str.

with_float_autocomplete #

with_float_autocomplete(name)

Set the autocomplete callback for a float option through a decorator call.

Parameters:

name (str) –

The option's name.

If localised names were provided for the option then this should be the default name.

Returns:

Callable[[AutocompleteSig[float]], AutocompleteSig[float]] –

Decorator callback used to capture the autocomplete callback.

More information on the autocomplete signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type float.

Raises:

KeyError –

Raises a key error if the option doesn't exist.
TypeError –

Raises a type error if the option isn't of type float.

with_int_autocomplete #

with_int_autocomplete(name)

Set the autocomplete callback for a integer option through a decorator call.

Parameters:

name (str) –

The option's name.

If localised names were provided for the option then this should be the default name.

Returns:

Callable[[AutocompleteSig[int]], AutocompleteSig[int]] –

Decorator callback used to capture the autocomplete callback.

More information on the autocomplete signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type int.

Raises:

KeyError –

Raises a key error if the option doesn't exist.
TypeError –

Raises a type error if the option isn't of type int.

with_str_autocomplete #

with_str_autocomplete(name)

Set the autocomplete callback for a string option through a decorator call.

Parameters:

name (str) –

The option's name.

If localised names were provided for the option then this should be the default name.

Returns:

Callable[[AutocompleteSig[str]], AutocompleteSig[str]] –

Decorator callback used to capture the autocomplete callback.

More information on the autocomplete signature can be found at tanjun.abc.AutocompleteSig and the 2nd positional argument should be of type str.

Raises:

KeyError –

Raises a key error if the option doesn't exist.
TypeError –

Raises a type error if the option isn't of type str.

SlashCommandGroup #

Bases: BaseSlashCommand, SlashCommandGroup

Standard implementation of a slash command group.

Note

Unlike message command groups, slash command groups cannot be callable functions themselves.

init #

__init__(name, description, /, *, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, is_global=True, nsfw=False)

Initialise a slash command group.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Warning

default_member_permissions, dm_enabled and is_global are ignored for commands groups within another slash command groups.

Parameters:

name (str | Mapping[str, str]) –

The name of the command group (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The description of the command group (supports localisation).

This should be inclusively between 1-100 characters in length.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name doesn't fit Discord's requirements.
- If the command name has uppercase characters.
- If the description is over 100 characters long.

add_command #

add_command(command)

Add a slash command to this group.

Warning

Command groups are only supported within top-level groups.

Parameters:

command (BaseSlashCommand) –

Command to add to this group.

Returns:

Self –

Object of this group to enable chained calls.

as_sub_command #

as_sub_command(name, description, /, *, always_defer=False, default_to_ephemeral=None, sort_options=True, validate_arg_keys=True)

Build a SlashCommand in this command group by decorating a function.

Note

If you want your first response to be ephemeral while using always_defer, you must set default_to_ephemeral to True.

Parameters:

name (str | Mapping[str, str]) –

The command's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The command's description. This should be inclusively between 1-100 characters in length.
always_defer (bool, default: False ) –

Whether the contexts this command is executed with should always be deferred before being passed to the command's callback.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
sort_options (bool, default: True ) –

Whether this command should sort its set options based on whether they're required.

If this is True then the options are re-sorted to meet the requirement from Discord that required command options be listed before optional ones.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Returns:

Callable[[SlashCallbackSig], SlashCommand] –

The decorator callback used to make a sub-command.

This can either wrap a raw command callback or another callable command instance (e.g. tanjun.MenuCommand, tanjun.MessageCommand, SlashCommand).

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name doesn't fit Discord's requirements.
- If the command name has uppercase characters.
- If the description is over 100 characters long.

make_sub_group #

make_sub_group(name, description, /, *, default_to_ephemeral=None)

Create a sub-command group in this group.

Note

Unlike message command groups, slash command groups cannot be callable functions themselves.

Parameters:

name (str | Mapping[str, str]) –

The name of the command group (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The description of the command group.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.

Returns:

SlashCommandGroup –

The created sub-command group.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name doesn't fit Discord's requirements.
- If the command name has uppercase characters.
- If the description is over 100 characters long.

remove_command #

remove_command(command)

Remove a command from this group.

Parameters:

command (BaseSlashCommand) –

Command to remove from this group.

Returns:

Self –

Object of this group to enable chained calls.

set_ephemeral_default #

set_ephemeral_default(state)

Set whether this command's responses should default to ephemeral.

Parameters:

state (bool | None) –

Whether this command's responses should default to ephemeral. This will be overridden by any response calls which specify flags.

Setting this to None will let the default set on the parent command(s), component or client propagate and decide the ephemeral default for contexts used by this command.

Returns:

Self –

This command to allow for chaining.

with_command #

with_command(command)

Add a slash command to this group through a decorator call.

Parameters:

command (BaseSlashCommand) –

Command to add to this group.

Returns:

BaseSlashCommand –

Command which was added to this group.

as_slash_command #

as_slash_command(name, description, /, *, always_defer=False, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, is_global=True, nsfw=False, sort_options=True, validate_arg_keys=True)

Build a SlashCommand by decorating a function.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Warning

default_member_permissions, dm_enabled and is_global are ignored for commands within slash command groups.

Note

If you want your first response to be ephemeral while using always_defer, you must set default_to_ephemeral to True.

Examples:

@as_slash_command("ping", "Get the bot's latency")
async def ping_command(self, ctx: tanjun.abc.SlashContext) -> None:
    start_time = time.perf_counter()
    await ctx.rest.fetch_my_user()
    time_taken = (time.perf_counter() - start_time) * 1_000
    await ctx.respond(f"PONG\n - REST: {time_taken:.0f}mss")

Parameters:

name (str | Mapping[str, str]) –

The command's name (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The command's description (supports localisation).

This should be inclusively between 1-100 characters in length.
always_defer (bool, default: False ) –

Whether the contexts this command is executed with should always be deferred before being passed to the command's callback.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.
sort_options (bool, default: True ) –

Whether this command should sort its set options based on whether they're required.

If this is True then the options are re-sorted to meet the requirement from Discord that required command options be listed before optional ones.
validate_arg_keys (bool, default: True ) –

Whether to validate that option keys match the command callback's signature.

Returns:

Callable[[SlashCallbackSig], SlashCommand] –

The decorator callback used to make a SlashCommand.

This can either wrap a raw command callback or another callable command instance (e.g. tanjun.MenuCommand, tanjun.MessageCommand, SlashCommand) and will manage loading the other command into a component when using Component.load_from_scope.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name doesn't fit Discord's requirements.
- If the command name has uppercase characters.
- If the description is over 100 characters long.

slash_command_group #

slash_command_group(name, description, /, *, default_member_permissions=None, default_to_ephemeral=None, dm_enabled=None, nsfw=False, is_global=True)

Create a slash command group.

Note

Unlike message command groups, slash command groups cannot be callable functions themselves.

Warning

default_member_permissions, dm_enabled and is_global are ignored for command groups within other slash command groups.

Note

Under the standard implementation, is_global is used to determine whether the command should be bulk set by Client.declare_global_commands or when declare_global_commands is True

Examples:

Sub-commands can be added to the created slash command object through the following decorator based approach:

help_group = tanjun.slash_command_group("help", "get help")

@tanjun.with_str_slash_option("command_name", "command name")
@help_group.as_sub_command("command", "Get help with a command")
async def help_command_command(ctx: tanjun.abc.SlashContext, command_name: str) -> None:
    ...

@help_group.as_sub_command("me", "help me")
async def help_me_command(ctx: tanjun.abc.SlashContext) -> None:
    ...

component = tanjun.Component().add_slash_command(help_group)

Parameters:

name (str | Mapping[str, str]) –

The name of the command group (supports localisation).

This must fit discord's requirements.
description (str | Mapping[str, str]) –

The description of the command group (supports localisation).

This should be inclusively between 1-100 characters in length.
default_member_permissions (Permissions | int | None, default: None ) –

Member permissions necessary to utilize this command by default.

If this is None then the configuration for the parent component or client will be used.
default_to_ephemeral (bool | None, default: None ) –

Whether this command's responses should default to ephemeral unless flags are set to override this.

If this is left as None then the default set on the parent command(s), component or client will be in effect.
dm_enabled (bool | None, default: None ) –

Whether this command is enabled in DMs with the bot.

If this is None then the configuration for the parent component or client will be used.
is_global (bool, default: True ) –

Whether this command is a global command.
nsfw (bool, default: False ) –

Whether this command should only be accessible in channels marked as nsfw.

Returns:

SlashCommandGroup –

The command group.

Raises:

ValueError –
Raises a value error for any of the following reasons:
- If the command name doesn't fit Discord's requirements.
- If the command name has uppercase characters.
- If the description is over 100 characters long.

with_attachment_slash_option #

with_attachment_slash_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add an attachment option to a slash command.

For more information on this function's parameters see SlashCommand.add_attachment_option.

Examples:

@with_attachment_slash_option("name", "A name.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, name: hikari.Attachment) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_bool_slash_option #

with_bool_slash_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a boolean option to a slash command.

For information on this function's parameters see SlashCommand.add_bool_option.

Examples:

@with_bool_slash_option("flag", "Whether this flag should be enabled.", default=False)
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, flag: bool) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_channel_slash_option #

with_channel_slash_option(name, description, /, *, types=None, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a channel option to a slash command.

For information on this function's parameters see SlashCommand.add_channel_option.

Note

This will always result in hikari.InteractionChannel.

Examples:

@with_channel_slash_option("channel", "channel to target.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, channel: hikari.InteractionChannel) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_float_slash_option #

with_float_slash_option(name, description, /, *, always_float=True, autocomplete=None, choices=None, converters=(), default=tanjun.NO_DEFAULT, key=None, min_value=None, max_value=None, pass_as_kwarg=True)

Add a float option to a slash command.

For information on this function's parameters see SlashCommand.add_float_option.

Examples:

@with_float_slash_option("float_value", "Float value.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, float_value: float) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_int_slash_option #

with_int_slash_option(name, description, /, *, autocomplete=None, choices=None, converters=(), default=tanjun.NO_DEFAULT, key=None, min_value=None, max_value=None, pass_as_kwarg=True)

Add an integer option to a slash command.

For information on this function's parameters see SlashCommand.add_int_option.

Examples:

@with_int_slash_option("int_value", "Int value.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, int_value: int) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_member_slash_option #

with_member_slash_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None)

Add a member option to a slash command.

For information on this function's arguments see SlashCommand.add_member_option.

Note

This will always result in hikari.InteractionMember.

Examples:

@with_member_slash_option("member", "member to target.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, member: hikari.InteractionMember) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_mentionable_slash_option #

with_mentionable_slash_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a mentionable option to a slash command.

For information on this function's arguments see SlashCommand.add_mentionable_option.

Note

This may target roles, guild members or users and results in hikari.User | hikari.InteractionMember | hikari.Role.

Examples:

@with_mentionable_slash_option("mentionable", "Mentionable entity to target.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, mentionable: [Role, InteractionMember, User]) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_role_slash_option #

with_role_slash_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a role option to a slash command.

For information on this function's parameters see SlashCommand.add_role_option.

Examples:

@with_role_slash_option("role", "Role to target.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, role: hikari.Role) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_str_slash_option #

with_str_slash_option(name, description, /, *, autocomplete=None, choices=None, converters=(), default=tanjun.NO_DEFAULT, key=None, min_length=None, max_length=None, pass_as_kwarg=True)

Add a string option to a slash command.

For more information on this function's parameters see SlashCommand.add_str_option.

Examples:

@with_str_slash_option("name", "A name.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, name: str) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

with_user_slash_option #

with_user_slash_option(name, description, /, *, default=tanjun.NO_DEFAULT, key=None, pass_as_kwarg=True)

Add a user option to a slash command.

For information on this function's parameters see SlashCommand.add_user_option.

Note

This may result in hikari.InteractionMember or hikari.User if the user isn't in the current guild or if this command was executed in a DM channel.

Examples:

@with_user_slash_option("user", "user to target.")
@as_slash_command("command", "A command")
async def command(self, ctx: tanjun.abc.SlashContext, user: Union[InteractionMember, User]) -> None:
    ...

Returns:

Callable[[SlashCommand], SlashCommand] –

Decorator callback which adds the option to the command.

tanjun.commands#

tanjun.commands.menu #

MenuCommand #

wrapped_command property #

__init__ #

set_ephemeral_default #

as_message_menu #

as_user_menu #

tanjun.commands.message #

MessageCommand #

wrapped_command property #

__init__ #

MessageCommandGroup #

wrapped_command property #

__init__ #

add_command #

as_sub_command #

as_sub_group #

as_message_command #

as_message_command_group #

tanjun.commands.slash #

ConverterSig module-attribute #

UNDEFINED_DEFAULT module-attribute #

BaseSlashCommand #

build abstractmethod #

set_ephemeral_default #

SlashCommand #

wrapped_command property #

__init__ #

add_attachment_option #

add_bool_option #

add_channel_option #

add_float_option #

add_int_option #

add_member_option #

add_mentionable_option #

add_role_option #

add_str_option #

add_user_option #

set_ephemeral_default #

set_float_autocomplete #

set_int_autocomplete #

set_str_autocomplete #

with_float_autocomplete #

with_int_autocomplete #

with_str_autocomplete #

SlashCommandGroup #

__init__ #

add_command #

as_sub_command #

make_sub_group #

remove_command #

set_ephemeral_default #

with_command #

as_slash_command #

slash_command_group #

with_attachment_slash_option #

with_bool_slash_option #

with_channel_slash_option #

with_float_slash_option #

with_int_slash_option #

with_member_slash_option #

with_mentionable_slash_option #

with_role_slash_option #

with_str_slash_option #

with_user_slash_option #

wrapped_command `property` #

init #

wrapped_command `property` #

init #

wrapped_command `property` #

init #

ConverterSig `module-attribute` #

UNDEFINED_DEFAULT `module-attribute` #

build `abstractmethod` #

wrapped_command `property` #

init #

init #