hikari.commands#

Models and enums used for application commands on Discord.

Module Contents#

class hikari.commands.CommandType[source]#

Bases: int, hikari.internal.enums.Enum

The type of a command.

SLASH = 1[source]#

A text-based command.

USER = 2[source]#

A user-based command.

MESSAGE = 3[source]#

A message-based command.

class hikari.commands.OptionType[source]#

Bases: int, hikari.internal.enums.Enum

The type of a command option.

SUB_COMMAND = 1[source]#

Denotes a command option where the value will be a sub command.

SUB_COMMAND_GROUP = 2[source]#

Denotes a command option where the value will be a sub command group.

STRING = 3[source]#

Denotes a command option where the value will be a string.

INTEGER = 4[source]#

Denotes a command option where the value will be a int.

This is range limited between -2^53 and 2^53.

BOOLEAN = 5[source]#

Denotes a command option where the value will be a bool.

USER = 6[source]#

Denotes a command option where the value will be resolved to a user.

CHANNEL = 7[source]#

Denotes a command option where the value will be resolved to a channel.

ROLE = 8[source]#

Denotes a command option where the value will be resolved to a role.

MENTIONABLE = 9[source]#

Denotes a command option where the value will be a snowflake ID.

FLOAT = 10[source]#

Denotes a command option where the value will be a float.

This is range limited between -2^53 and 2^53.

ATTACHMENT = 11[source]#

Denotes a command option where the value will be an attachment.

class hikari.commands.CommandChoice[source]#

Represents the choices set for an application command’s argument.

name: str[source]#

The choice’s name (inclusively between 1-100 characters).

value: Union[str, int, float][source]#

Value of the choice (up to 100 characters if a string).

class hikari.commands.CommandOption[source]#

Represents an application command’s argument.

type: Union[OptionType, int][source]#

The type of command option this is.

name: str[source]#

The command option’s name.

Note

This will match the regex ^[-_p{L}p{N}p{sc=Deva}p{sc=Thai}]{1,32}$ in Unicode mode and will be lowercase.

description: str[source]#

The command option’s description.

Note

This will be inclusively between 1-100 characters in length.

is_required: bool[source]#

Whether this command option is required.

choices: Optional[Sequence[CommandChoice]][source]#

A sequence of up to (and including) 25 choices for this command.

This will be None if the input values for this option aren’t limited to specific values or if it’s a subcommand or subcommand-group type option.

options: Optional[Sequence[CommandOption]][source]#

Sequence of up to (and including) 25 of the options for this command option.

channel_types: Optional[Sequence[Union[hikari.channels.ChannelType, int]]][source]#

The channel types that this option will accept.

If None, then all channel types will be accepted.

autocomplete: bool[source]#

Whether this option has autocomplete.

min_value: Union[int, float, None][source]#

The minimum value permitted (inclusive).

This will be int if the type of the option is hikari.commands.OptionType.INTEGER and float if the type is hikari.commands.OptionType.FLOAT.

max_value: Union[int, float, None][source]#

The maximum value permitted (inclusive).

This will be int if the type of the option is hikari.commands.OptionType.INTEGER and float if the type is hikari.commands.OptionType.FLOAT.

name_localizations: Mapping[Union[hikari.locales.Locale, str], str][source]#

A set of name localizations for this option.

description_localizations: Mapping[Union[hikari.locales.Locale, str], str][source]#

A set of description localizations for this option

min_length: Optional[int][source]#

The minimum length permitted (inclusive).

This is only valid for hikari.commands.OptionType.STRING, otherwise it will be None.

max_length: Optional[int][source]#

The maximum length permitted (inclusive).

This is only valid for hikari.commands.OptionType.STRING, otherwise it will be None.

class hikari.commands.PartialCommand[source]#

Bases: hikari.snowflakes.Unique

Represents any application command on Discord.

app: hikari.traits.RESTAware[source]#

Client application that models may use for procedures.

type: CommandType[source]#

The type of a command.

application_id: hikari.snowflakes.Snowflake[source]#

ID of the application this command belongs to.

name: str[source]#

The command’s name.

Note

This will match the regex ^[-_p{L}p{N}p{sc=Deva}p{sc=Thai}]{1,32}$ in Unicode mode and will be lowercase.

default_member_permissions: hikari.permissions.Permissions[source]#

Member permissions necessary to utilize this command by default.

This excludes administrators of the guild and overwrites.

is_dm_enabled: bool[source]#

Whether this command is enabled in DMs with the bot.

is_nsfw: bool[source]#

Whether this command is age-restricted.

guild_id: Optional[hikari.snowflakes.Snowflake][source]#

ID of the guild this command is in.

This will be None if this is a global command.

version: hikari.snowflakes.Snowflake[source]#

Auto-incrementing version identifier updated during substantial record changes.

name_localizations: Mapping[Union[hikari.locales.Locale, str], str][source]#

A set of name localizations for this command

description_localizations: Mapping[Union[hikari.locales.Locale, str], str][source]#

A set of description localizations for this command

async fetch_self()[source]#

Fetch an up-to-date version of this command object.

Returns
PartialCommand

Object of the fetched command.

Raises
hikari.errors.ForbiddenError

If you cannot access the target command.

hikari.errors.NotFoundError

If the command isn’t found.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async edit(*, name=undefined.UNDEFINED, description=undefined.UNDEFINED, options=undefined.UNDEFINED)[source]#

Edit this command.

Other Parameters
namehikari.undefined.UndefinedOr[str]

The name to set for the command. Leave as hikari.undefined.UNDEFINED to not change.

descriptionhikari.undefined.UndefinedOr[str]

The description to set for the command. Leave as hikari.undefined.UNDEFINED to not change.

optionshikari.undefined.UndefinedOr[typing.Sequence[CommandOption]]

A sequence of up to 10 options to set for this command. Leave this as hikari.undefined.UNDEFINED to not change.

Returns
PartialCommand

The edited command object.

Raises
hikari.errors.ForbiddenError

If you cannot access the application’s commands.

hikari.errors.NotFoundError

If the application or command isn’t found.

hikari.errors.BadRequestError

If any of the fields that are passed have an invalid value.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async delete()[source]#

Delete this command.

Raises
hikari.errors.ForbiddenError

If you cannot access the application’s commands.

hikari.errors.NotFoundError

If the application or command isn’t found.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async fetch_guild_permissions(guild, /)[source]#

Fetch the permissions registered for this command in a specific guild.

Parameters
guildhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]

Object or ID of the guild to fetch the command permissions for.

Returns
GuildCommandPermissions

Object of the command permissions set for the specified command.

Raises
hikari.errors.ForbiddenError

If you cannot access the provided application’s commands or guild.

hikari.errors.NotFoundError

If the provided application or command isn’t found.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async set_guild_permissions(guild, permissions)[source]#

Set permissions for this command in a specific guild.

Note

This overwrites any previously set permissions.

Parameters
guildhikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]

Object or ID of the guild to set the command permissions in.

permissionstyping.Sequence[CommandPermission]

Sequence of up to 10 of the permission objects to set.

Returns
GuildCommandPermissions

Object of the set permissions.

Raises
hikari.errors.ForbiddenError

If you cannot access the provided application’s commands or guild.

hikari.errors.NotFoundError

If the provided application or command isn’t found.

hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

class hikari.commands.SlashCommand[source]#

Bases: PartialCommand

Represents a slash command on Discord.

description: str[source]#

The command’s description.

None if this command is not a slash command.

Note

This will be inclusively between 1-100 characters in length.

options: Optional[Sequence[CommandOption]][source]#

Sequence of up to (and including) 25 of the options for this command.

class hikari.commands.ContextMenuCommand[source]#

Bases: PartialCommand

Represents a context menu command on Discord.

class hikari.commands.CommandPermissionType[source]#

Bases: int, hikari.internal.enums.Enum

The type of entity a command permission targets.

ROLE = 1[source]#

A command permission which toggles access for a specific role.

USER = 2[source]#

A command permission which toggles access for a specific user.

CHANNEL = 3[source]#

A command permission which toggles access in a specific channel.

class hikari.commands.CommandPermission[source]#

Representation of a permission which enables or disables a command for a user or role.

id: hikari.snowflakes.Snowflake[source]#

ID of the role or user this permission changes the permission’s state for.

There are some special constants for this field:

  • If equals to guild_id, then it applies to all members in a guild.

  • If equals to (guild_id - 1), then it applies to all channels in a guild.

type: Union[CommandPermissionType, int][source]#

The entity this permission overrides the command’s state for.

has_access: bool[source]#

Whether this permission marks the target entity as having access to the command.

class hikari.commands.GuildCommandPermissions[source]#

Representation of the permissions set for a command within a guild.

id: hikari.snowflakes.Snowflake[source]#

ID of the entity these permissions apply to.

This may be the ID of a specific command or the application ID. When this is equal to application_id, the permissions apply to all commands that do not contain explicit overwrites.

application_id: hikari.snowflakes.Snowflake[source]#

ID of the application the relevant command belongs to.

command_id: hikari.snowflakes.Snowflake[source]#

ID of the command these permissions are for.

guild_id: hikari.snowflakes.Snowflake[source]#

ID of the guild these permissions are in.

permissions: Sequence[CommandPermission][source]#

Sequence of up to (and including) 100 of the command permissions set in this guild.