Commands

Group dataclass

Group(
    name: str | LocaleBuilder,
    description: str | LocaleBuilder | None = None,
    hooks: list[CommandHookCallbackT] = list(),
    after_hooks: list[CommandHookCallbackT] = list(),
    default_member_permissions: UndefinedType
    | int
    | Permissions = UNDEFINED,
    context_types: UndefinedType
    | Iterable[ApplicationContextType] = UNDEFINED,
)

A command group. A command group is a top level command that contains subcommands and SubGroups.

Example

import crescent

utils_group = crescent.Group("utils")

# This command will appear under the `utils` group in discord.
@client.include
@utils_group.child
@crescent.command
async def ping(ctx: crescent.Context):
    await ctx.respond("Pong")

after_hooks class-attribute instance-attribute

after_hooks: list[CommandHookCallbackT] = field(
    default_factory=list
)

A list of hooks to run after all commands in this group.

context_types class-attribute instance-attribute

context_types: (
    UndefinedType | Iterable[ApplicationContextType]
) = UNDEFINED

The contexts in which the command can be used.

default_member_permissions class-attribute instance-attribute

default_member_permissions: (
    UndefinedType | int | Permissions
) = UNDEFINED

The default permissions for all commands in this group.

description class-attribute instance-attribute

description: str | LocaleBuilder | None = None

The description of the group. The discord API supports this feature but it does not do anything.

hooks class-attribute instance-attribute

hooks: list[CommandHookCallbackT] = field(
    default_factory=list
)

A looks of hooks to run before all commands in this group.

name instance-attribute

name: str | LocaleBuilder

The name of the group

child

child(
    includable: Includable[AppCommandMeta],
) -> Includable[AppCommandMeta]

Add a command to this command group.

sub_group

sub_group(
    name: str | LocaleBuilder,
    description: str | LocaleBuilder | None = None,
    hooks: list[CommandHookCallbackT] | None = None,
    after_hooks: list[CommandHookCallbackT] | None = None,
) -> SubGroup

Create a sub group from this group.

SubGroup dataclass

SubGroup(
    name: str | LocaleBuilder,
    parent: Group,
    description: str | LocaleBuilder | None = None,
    hooks: list[CommandHookCallbackT] = list(),
    after_hooks: list[CommandHookCallbackT] = list(),
)

A command subgroup. A command subgroup is a group that is under a top level group.

Example

import crescent

utils_group = crescent.Group("utils")
time_utils_group = utils_group.sub_group("time")

# This command will appear under the `utils time` group in discord.
@client.include
@time_utils_group.child
@crescent.command
async def latency(ctx: crescent.Context):
    await ctx.respond(f"The latency is {bot.heartbeat_latency * 1000}ms")

after_hooks class-attribute instance-attribute

after_hooks: list[CommandHookCallbackT] = field(
    default_factory=list
)

A list of hooks to run after all commands in this group.

hooks class-attribute instance-attribute

hooks: list[CommandHookCallbackT] = field(
    default_factory=list
)

A looks of hooks to run before all commands in this group.

child

child(
    includable: Includable[AppCommandMeta],
) -> Includable[AppCommandMeta]

Add a command to this command group.

command

command(
    callback: CommandCallbackT | type[ClassCommandProto],
) -> Includable[AppCommandMeta]

command(
    *,
    guild: Snowflakeish | None = ...,
    name: str | LocaleBuilder | None = ...,
    description: str | LocaleBuilder | None = ...,
    default_member_permissions: UndefinedType
    | int
    | Permissions = ...,
    context_types: UndefinedOr[
        Iterable[ApplicationContextType]
    ] = ...,
    nsfw: bool | None = ...,
) -> Callable[
    [CommandCallbackT | type[ClassCommandProto]],
    Includable[AppCommandMeta],
]

command(
    callback: CommandCallbackT
    | type[ClassCommandProto]
    | None = None,
    /,
    *,
    guild: Snowflakeish | None = None,
    name: str | LocaleBuilder | None = None,
    description: str | LocaleBuilder | None = None,
    default_member_permissions: UndefinedType
    | int
    | Permissions = UNDEFINED,
    context_types: UndefinedOr[
        Iterable[ApplicationContextType]
    ] = UNDEFINED,
    nsfw: bool | None = None,
) -> (
    Includable[AppCommandMeta]
    | Callable[
        [CommandCallbackT | type[ClassCommandProto]],
        Includable[AppCommandMeta],
    ]
)

Register a slash command.

Example

import hikari
import crescent

bot = hikari.GatewayBot("YOUR_TOKEN_HERE")
client = crescent.Client(bot)

@client.include
@crescent.command
async def ping(ctx: crescent.Context):
    await ctx.respond("Pong")

PARAMETER	DESCRIPTION
name	The name of this command. If not specified the function name will be used. TYPE: str | LocaleBuilder | None DEFAULT: None
description	The description of this command. If not specified the description will be set to "No Description". TYPE: str | LocaleBuilder | None DEFAULT: None
guild	The guild to register this command to. If not specified this command will be registered globally. TYPE: Snowflakeish | None DEFAULT: None
default_member_permissions	The default permissions for this command. For more information see the discord api docs and the hikari docs. TYPE: UndefinedType | int | Permissions DEFAULT: UNDEFINED
context_types	The contexts in which the command can be used. Defaults to all. TYPE: UndefinedOr[Iterable[ApplicationContextType]] DEFAULT: UNDEFINED
nsfw	Set to True to mark this command as nsfw. Defaults to None. TYPE: bool | None DEFAULT: None

message_command

message_command(
    callback: MessageCommandCallbackT,
) -> Includable[AppCommandMeta]

message_command(
    *,
    guild: Snowflakeish | None = ...,
    name: str | None = ...,
    default_member_permissions: UndefinedType
    | int
    | Permissions = ...,
    context_types: UndefinedOr[
        list[ApplicationContextType]
    ] = ...,
    nsfw: bool | None = ...,
) -> Callable[
    [MessageCommandCallbackT], Includable[AppCommandMeta]
]

message_command(
    callback: MessageCommandCallbackT | None = None,
    /,
    *,
    guild: Snowflakeish | None = None,
    name: str | None = None,
    default_member_permissions: UndefinedType
    | int
    | Permissions = UNDEFINED,
    context_types: UndefinedOr[
        list[ApplicationContextType]
    ] = UNDEFINED,
    nsfw: bool | None = None,
) -> (
    Callable[
        [MessageCommandCallbackT],
        Includable[AppCommandMeta],
    ]
    | Includable[AppCommandMeta]
)

Register a message command. A message command can be used by right clicking on a discord message. Your bot can have up to 5 message commands.

Example

import hikari
import crescent

bot = hikari.GatewayBot("YOUR_TOKEN_HERE")
client = crescent.Client(bot)

@client.include
@crescent.message_command
async def ping(ctx: crescent.Context, message: hikari.Message):
    await ctx.respond(message.contents)

PARAMETER	DESCRIPTION
name	The name of this command. If not specified the function name will be used. TYPE: str | None DEFAULT: None
guild	The guild to register this command to. If not specified this command will be registered globally. TYPE: Snowflakeish | None DEFAULT: None
default_member_permissions	The default permissions for this command. For more information see the discord api docs and the hikari docs. TYPE: UndefinedType | int | Permissions DEFAULT: UNDEFINED
context_types	The contexts in which the command can be used. Defaults to all. TYPE: UndefinedOr[list[ApplicationContextType]] DEFAULT: UNDEFINED
nsfw	Set to True to mark this command as nsfw. Defaults to None. TYPE: bool | None DEFAULT: None

option

option(
    option_type: type[PartialChannel]
    | Sequence[type[PartialChannel]],
    description: str | LocaleBuilder = ...,
    *,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[
    InteractionChannel, InteractionChannel
]

option(
    option_type: type[PartialChannel]
    | Sequence[type[PartialChannel]],
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[
    InteractionChannel | DEFAULT,
    InteractionChannel | DEFAULT,
]

option(
    option_type: USER,
    description: str | LocaleBuilder = ...,
    *,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[User, User]

option(
    option_type: USER,
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[User | DEFAULT, User | DEFAULT]

option(
    option_type: ROLE,
    description: str | LocaleBuilder = ...,
    *,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[Role, Role]

option(
    option_type: ROLE,
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[Role | DEFAULT, Role | DEFAULT]

option(
    option_type: ATTACHMENT,
    description: str | LocaleBuilder = ...,
    *,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[Attachment, Attachment]

option(
    option_type: ATTACHMENT,
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[
    Attachment | DEFAULT, Attachment | DEFAULT
]

option(
    option_type: type[Mentionable],
    description: str | LocaleBuilder = ...,
    *,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[Mentionable, Mentionable]

option(
    option_type: type[Mentionable],
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[
    Mentionable | DEFAULT, Mentionable | DEFAULT
]

option(
    option_type: type[bool],
    description: str | LocaleBuilder = ...,
    *,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[bool, bool]

option(
    option_type: type[bool],
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[bool | DEFAULT, bool | DEFAULT]

option(
    option_type: type[int],
    description: str | LocaleBuilder = ...,
    *,
    choices: Sequence[tuple[str | LocaleBuilder, int]]
    | None = ...,
    autocomplete: AutocompleteCallbackT[int] | None = ...,
    min_value: int | None = ...,
    max_value: int | None = ...,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[int, int]

option(
    option_type: type[int],
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    choices: Sequence[tuple[str | LocaleBuilder, int]]
    | None = ...,
    autocomplete: AutocompleteCallbackT[int] | None = ...,
    min_value: int | None = ...,
    max_value: int | None = ...,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[int | DEFAULT, int | DEFAULT]

option(
    option_type: type[float],
    description: str | LocaleBuilder = ...,
    *,
    choices: Sequence[tuple[str | LocaleBuilder, float]]
    | None = ...,
    autocomplete: AutocompleteCallbackT[float] | None = ...,
    min_value: float | None = ...,
    max_value: float | None = ...,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[float, float]

option(
    option_type: type[float],
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    choices: Sequence[tuple[str | LocaleBuilder, float]]
    | None = ...,
    autocomplete: AutocompleteCallbackT[float] | None = ...,
    min_value: float | None = ...,
    max_value: float | None = ...,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[float | DEFAULT, float | DEFAULT]

option(
    option_type: type[str],
    description: str | LocaleBuilder = ...,
    *,
    min_length: int | None = ...,
    max_length: int | None = ...,
    choices: Sequence[tuple[str | LocaleBuilder, str]]
    | None = ...,
    autocomplete: AutocompleteCallbackT[str] | None = ...,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[str, str]

option(
    option_type: type[str],
    description: str | LocaleBuilder = ...,
    *,
    default: DEFAULT,
    min_length: int | None = ...,
    max_length: int | None = ...,
    choices: Sequence[tuple[str | LocaleBuilder, str]]
    | None = ...,
    autocomplete: AutocompleteCallbackT[str] | None = ...,
    name: str | LocaleBuilder | None = ...,
) -> ClassCommandOption[str | DEFAULT, int | DEFAULT]

option(
    option_type: type[OptionTypesT]
    | Sequence[type[PartialChannel]],
    description: str | LocaleBuilder = "No Description",
    *,
    name: str | LocaleBuilder | None = None,
    default: UndefinedOr[Any] = UNDEFINED,
    choices: Sequence[
        tuple[str | LocaleBuilder, str | int | float]
    ]
    | None = None,
    min_value: int | float | None = None,
    max_value: int | float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    autocomplete: AutocompleteCallbackT[Any] | None = None,
) -> ClassCommandOption[Any, Any]

An option when declaring a command using class syntax.

Example

@client.include
@crescent.command(name="say")
class Say:
    word = crescent.option(str)

    async def callback(self, ctx: crescent.Context):
        await ctx.respond(self.word)

PARAMETER	DESCRIPTION
description	The description for this option. Defaults to "No Description". TYPE: str | LocaleBuilder DEFAULT: 'No Description'
name	The name to use for this option. By default, the name of the property on the option the option is set to will be used for the name. In the above example the name would be word. TYPE: str | LocaleBuilder | None DEFAULT: None
default	The default value for this option. Specifying this will make this option optional. TYPE: UndefinedOr[Any] DEFAULT: UNDEFINED
choices	A set of choices a user can pick from for this option. Only available for int, str, and float option types. TYPE: Sequence[tuple[str | LocaleBuilder, str | int | float]] | None DEFAULT: None
min_value	The minimum value for a number the user inputs. Only available for int and float option types. TYPE: int | float | None DEFAULT: None
man_value	The maximum value for a number the user inputs. Only available for int and float option types.
min_length	The minimum length for a str that the user inputs. TYPE: int | None DEFAULT: None
max_length	The maximum length for a str that the user inputs. TYPE: int | None DEFAULT: None
autocomplete	An autocomplete callback for this option. Example async def autocomplete_response( ctx: crescent.AutocompleteContext, option: hikari.AutocompleteInteractionOption ) -> list[tuple[str, str]]: # Return a list of tuples of (option name, option value) return [("Some Option", "1234")] @client.include @crescent.command class autocomplete: result = crescent.option(str, "Respond to the message", autocomplete=autocomplete_response) async def callback(self, ctx: crescent.Context) -> None: await ctx.respond(self.result, ephemeral=True) TYPE: AutocompleteCallbackT[Any] | None DEFAULT: None

user_command

user_command(
    callback: UserCommandCallbackT,
) -> Includable[AppCommandMeta]

user_command(
    *,
    guild: Snowflakeish | None = ...,
    name: str | None = ...,
    default_member_permissions: UndefinedType
    | int
    | Permissions = ...,
    context_types: UndefinedOr[
        list[ApplicationContextType]
    ] = ...,
    nsfw: bool | None = ...,
) -> Callable[
    [UserCommandCallbackT], Includable[AppCommandMeta]
]

user_command(
    callback: UserCommandCallbackT | None = None,
    /,
    *,
    guild: Snowflakeish | None = None,
    name: str | None = None,
    default_member_permissions: UndefinedType
    | int
    | Permissions = UNDEFINED,
    context_types: UndefinedOr[
        list[ApplicationContextType]
    ] = UNDEFINED,
    nsfw: bool | None = None,
) -> (
    Callable[
        [UserCommandCallbackT], Includable[AppCommandMeta]
    ]
    | Includable[AppCommandMeta]
)

Register a user command. A user command can be used by right clicking on a discord user. Your bot can have up to 5 user commands.

Example

import hikari
import crescent

bot = hikari.GatewayBot("YOUR_TOKEN_HERE")
client = crescent.Client(bot)

@client.include
@crescent.user_command
async def ping(ctx: crescent.Context, user: hikari.User):
    await ctx.respond(user.username)

PARAMETER	DESCRIPTION
name	The name of this command. If not specified the function name will be used. TYPE: str | None DEFAULT: None
guild	The guild to register this command to. If not specified this command will be registered globally. TYPE: Snowflakeish | None DEFAULT: None
default_member_permissions	The default permissions for this command. For more information see the discord api docs and the hikari docs. TYPE: UndefinedType | int | Permissions DEFAULT: UNDEFINED
context_types	The contexts in which the command can be used. Defaults to all. TYPE: UndefinedOr[list[ApplicationContextType]] DEFAULT: UNDEFINED
nsfw	Set to True to mark this command as nsfw. Defaults to None. TYPE: bool | None DEFAULT: None