Skip to content

Commands

Autocomplete dataclass #

Bases: Arg, Generic[AutocompleteValueT]

Specify an autocomplete callback for functional command syntax.

ChannelTypes #

ChannelTypes(*channel_types: ChannelType)

Bases: Arg

Specify channel types a command can be used in for functional syntax.

Choices #

Choices(*choices: CommandChoice)

Bases: Arg

Specify choices for functional command syntax.

Description dataclass #

Bases: Arg

Specify the description for functional command syntax.

Group dataclass #

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[HookCallbackT] | None = None

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

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.

dm_enabled class-attribute instance-attribute #

dm_enabled: bool = True

Whether commands in this group can be used in DMs.

hooks class-attribute instance-attribute #

hooks: list[HookCallbackT] | None = None

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[HookCallbackT] | None = None,
    after_hooks: list[HookCallbackT] | None = None,
) -> SubGroup

Create a sub group from this group.

HookResult dataclass #

An object return by hooks to provide information about what to do after the hook is run.

PARAMETER DESCRIPTION
exit

If true, don't run any following hooks or the command.

TYPE: bool DEFAULT: False

MaxValue dataclass #

Bases: Arg

Specify the max value of a number for functional command syntax.

MinValue dataclass #

Bases: Arg

Specify the min value of a number for functional command syntax.

Name dataclass #

Bases: Arg

Specify the name for functional command syntax.

SubGroup dataclass #

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[HookCallbackT] | None = None

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

hooks class-attribute instance-attribute #

hooks: list[HookCallbackT] | None = None

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.

hook #

hook(*callbacks: HookCallbackT, after: bool = False)

Register a hook to a command.

Example#
async def say_hi(ctx: crescent.Context) -> None:
    await ctx.respond("Hello there")

@client.include
@crescent.hook(say_hi)
@crescent.command
async def ping(ctx: crescent.Context):
    await ctx.respond("Pong")
PARAMETER DESCRIPTION
after

If true, run this hook after the command has completed.

TYPE: bool DEFAULT: False

command #

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,
    dm_enabled: bool = True,
    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)[https://discord.com/developers/docs/topics/permissions] and (the hikari docs)[https://docs.hikari-py.dev/en/latest/reference/hikari/permissions/].

TYPE: UndefinedType | int | Permissions DEFAULT: UNDEFINED

dm_enabled

Set to False to disable in dms. Defaults to True.

TYPE: bool DEFAULT: True

nsfw

Set to True to mark this command as nsfw. Defaults to None.

TYPE: bool | None DEFAULT: None

message_command #

message_command(
    callback: MessageCommandCallbackT | None = None,
    /,
    *,
    guild: Snowflakeish | None = None,
    name: str | None = None,
    default_member_permissions: UndefinedType
    | int
    | Permissions = UNDEFINED,
    dm_enabled: bool = True,
    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)[https://discord.com/developers/docs/topics/permissions] and (the hikari docs)[https://docs.hikari-py.dev/en/latest/reference/hikari/permissions/].

TYPE: UndefinedType | int | Permissions DEFAULT: UNDEFINED

dm_enabled

Set to False to disable in dms. Defaults to True.

TYPE: bool DEFAULT: True

nsfw

Set to True to mark this command as nsfw. Defaults to None.

TYPE: bool | None DEFAULT: None

option #

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]

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 | None = None,
    /,
    *,
    guild: Snowflakeish | None = None,
    name: str | None = None,
    default_member_permissions: UndefinedType
    | int
    | Permissions = UNDEFINED,
    dm_enabled: bool = True,
    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

dm_enabled

Set to False to disable in dms. Defaults to True.

TYPE: bool DEFAULT: True

nsfw

Set to True to mark this command as nsfw. Defaults to None.

TYPE: bool | None DEFAULT: None