Skip to content

hikari.commands#

Models and enums used for application commands on Discord.

CommandChoice #

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

name class-attribute instance-attribute #

name: str = field(repr=True)

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

name_localizations class-attribute instance-attribute #

name_localizations: Mapping[Union[Locale, str], str] = field(
    eq=False, factory=dict, hash=False, repr=False
)

A mapping of name localizations for this command choice.

value class-attribute instance-attribute #

value: Union[str, int, float] = field(repr=True)

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

CommandOption #

Represents an application command's argument.

autocomplete class-attribute instance-attribute #

autocomplete: bool = field(default=False, repr=False)

Whether this option has autocomplete.

channel_types class-attribute instance-attribute #

channel_types: Optional[Sequence[Union[ChannelType, int]]] = field(
    default=None, repr=False
)

The channel types that this option will accept.

If None, then all channel types will be accepted.

choices class-attribute instance-attribute #

choices: Optional[Sequence[CommandChoice]] = field(default=None, repr=False)

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.

description class-attribute instance-attribute #

description: str = field(repr=False)

The command option's description.

Note

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

description_localizations class-attribute instance-attribute #

description_localizations: Mapping[Union[Locale, str], str] = field(
    eq=False, factory=dict, hash=False, repr=False
)

A mapping of description localizations for this option.

is_required class-attribute instance-attribute #

is_required: bool = field(default=False, repr=False)

Whether this command option is required.

max_length class-attribute instance-attribute #

max_length: Optional[int] = field(default=None, repr=False)

The maximum length permitted (inclusive).

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

max_value class-attribute instance-attribute #

max_value: Union[int, float, None] = field(default=None, repr=False)

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.

min_length class-attribute instance-attribute #

min_length: Optional[int] = field(default=None, repr=False)

The minimum length permitted (inclusive).

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

min_value class-attribute instance-attribute #

min_value: Union[int, float, None] = field(default=None, repr=False)

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.

name class-attribute instance-attribute #

name: str = field(repr=True)

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.

name_localizations class-attribute instance-attribute #

name_localizations: Mapping[Union[Locale, str], str] = field(
    eq=False, factory=dict, hash=False, repr=False
)

A mapping of name localizations for this option.

options class-attribute instance-attribute #

options: Optional[Sequence[CommandOption]] = field(default=None, repr=False)

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

type class-attribute instance-attribute #

type: Union[OptionType, int] = field(repr=True)

The type of command option this is.

CommandPermission #

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

has_access class-attribute instance-attribute #

has_access: bool = field()

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

id class-attribute instance-attribute #

id: Snowflake = field(converter=Snowflake)

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 class-attribute instance-attribute #

type: Union[CommandPermissionType, int] = field(converter=CommandPermissionType)

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

CommandPermissionType #

Bases: int, Enum

The type of entity a command permission targets.

CHANNEL class-attribute instance-attribute #

CHANNEL = 3

A command permission which toggles access in a specific channel.

ROLE class-attribute instance-attribute #

ROLE = 1

A command permission which toggles access for a specific role.

USER class-attribute instance-attribute #

USER = 2

A command permission which toggles access for a specific user.

name property #

name: str

Return the name of the enum member as a str.

value property #

value

Return the value of the enum member.

CommandType #

Bases: int, Enum

The type of a command.

MESSAGE class-attribute instance-attribute #

MESSAGE = 3

A message-based command.

SLASH class-attribute instance-attribute #

SLASH = 1

A text-based command.

USER class-attribute instance-attribute #

USER = 2

A user-based command.

name property #

name: str

Return the name of the enum member as a str.

value property #

value

Return the value of the enum member.

ContextMenuCommand #

Bases: PartialCommand

Represents a context menu command on Discord.

GuildCommandPermissions #

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

application_id class-attribute instance-attribute #

application_id: Snowflake = field()

ID of the application the relevant command belongs to.

command_id class-attribute instance-attribute #

command_id: Snowflake = field()

ID of the command these permissions are for.

guild_id class-attribute instance-attribute #

guild_id: Snowflake = field()

ID of the guild these permissions are in.

id class-attribute instance-attribute #

id: Snowflake = field()

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.

permissions class-attribute instance-attribute #

permissions: Sequence[CommandPermission] = field()

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

OptionType #

Bases: int, Enum

The type of a command option.

ATTACHMENT class-attribute instance-attribute #

ATTACHMENT = 11

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

BOOLEAN class-attribute instance-attribute #

BOOLEAN = 5

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

CHANNEL class-attribute instance-attribute #

CHANNEL = 7

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

FLOAT class-attribute instance-attribute #

FLOAT = 10

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

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

INTEGER class-attribute instance-attribute #

INTEGER = 4

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

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

MENTIONABLE class-attribute instance-attribute #

MENTIONABLE = 9

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

ROLE class-attribute instance-attribute #

ROLE = 8

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

STRING class-attribute instance-attribute #

STRING = 3

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

SUB_COMMAND class-attribute instance-attribute #

SUB_COMMAND = 1

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

SUB_COMMAND_GROUP class-attribute instance-attribute #

SUB_COMMAND_GROUP = 2

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

USER class-attribute instance-attribute #

USER = 6

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

name property #

name: str

Return the name of the enum member as a str.

value property #

value

Return the value of the enum member.

PartialCommand #

Bases: Unique

Represents any application command on Discord.

app class-attribute instance-attribute #

app: RESTAware = field(eq=False, hash=False, repr=False)

Client application that models may use for procedures.

application_id class-attribute instance-attribute #

application_id: Snowflake = field(eq=False, hash=False, repr=True)

ID of the application this command belongs to.

created_at property #

created_at: datetime

When the object was created.

default_member_permissions class-attribute instance-attribute #

default_member_permissions: Permissions = field(eq=False, hash=False, repr=True)

Member permissions necessary to utilize this command by default.

This excludes administrators of the guild and overwrites.

guild_id class-attribute instance-attribute #

guild_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

ID of the guild this command is in.

This will be None if this is a global command.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

ID of this entity.

is_dm_enabled class-attribute instance-attribute #

is_dm_enabled: bool = field(eq=False, hash=False, repr=True)

Whether this command is enabled in DMs with the bot.

is_nsfw class-attribute instance-attribute #

is_nsfw: bool = field(eq=False, hash=False, repr=True)

Whether this command is age-restricted.

name class-attribute instance-attribute #

name: str = field(eq=False, hash=False, repr=True)

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.

name_localizations class-attribute instance-attribute #

name_localizations: Mapping[Union[Locale, str], str] = field(
    eq=False, hash=False, repr=False
)

A mapping of name localizations for this command.

type class-attribute instance-attribute #

type: CommandType = field(hash=True, repr=True)

The type of a command.

version class-attribute instance-attribute #

version: Snowflake = field(eq=False, hash=False, repr=True)

Auto-incrementing version identifier updated during substantial record changes.

delete async #

delete() -> None

Delete this command.

RAISES DESCRIPTION
ForbiddenError

If you cannot access the application's commands.
NotFoundError

If the application or command isn't found.
UnauthorizedError

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

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

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    description: UndefinedOr[str] = undefined.UNDEFINED,
    options: UndefinedOr[Sequence[CommandOption]] = undefined.UNDEFINED
) -> PartialCommand

Edit this command.

PARAMETER DESCRIPTION
name

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

TYPE: UndefinedOr[str]

description

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

TYPE: UndefinedOr[str]

options

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

TYPE: UndefinedOr[Sequence[CommandOption]]

RETURNS DESCRIPTION
PartialCommand

The edited command object.
RAISES DESCRIPTION
ForbiddenError

If you cannot access the application's commands.
NotFoundError

If the application or command isn't found.
BadRequestError

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

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

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

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

fetch_guild_permissions async #

fetch_guild_permissions(
    guild: SnowflakeishOr[PartialGuild],
) -> GuildCommandPermissions

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

PARAMETER DESCRIPTION
guild

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

TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

RETURNS DESCRIPTION
GuildCommandPermissions

Object of the command permissions set for the specified command.
RAISES DESCRIPTION
ForbiddenError

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

If the provided application or command isn't found.
UnauthorizedError

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

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

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

fetch_self async #

fetch_self() -> PartialCommand

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

RETURNS DESCRIPTION
PartialCommand

Object of the fetched command.
RAISES DESCRIPTION
ForbiddenError

If you cannot access the target command.
NotFoundError

If the command isn't found.
UnauthorizedError

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

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

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

set_guild_permissions async #

set_guild_permissions(
    guild: SnowflakeishOr[PartialGuild],
    permissions: Sequence[CommandPermission],
) -> GuildCommandPermissions

Set permissions for this command in a specific guild.

Note

This overwrites any previously set permissions.

PARAMETER DESCRIPTION
guild

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

TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

permissions

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

TYPE: Sequence[CommandPermission]

RETURNS DESCRIPTION
GuildCommandPermissions

Object of the set permissions.
RAISES DESCRIPTION
ForbiddenError

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

If the provided application or command isn't found.
UnauthorizedError

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

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

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

SlashCommand #

Bases: PartialCommand

Represents a slash command on Discord.

app class-attribute instance-attribute #

app: RESTAware = field(eq=False, hash=False, repr=False)

Client application that models may use for procedures.

application_id class-attribute instance-attribute #

application_id: Snowflake = field(eq=False, hash=False, repr=True)

ID of the application this command belongs to.

created_at property #

created_at: datetime

When the object was created.

default_member_permissions class-attribute instance-attribute #

default_member_permissions: Permissions = field(eq=False, hash=False, repr=True)

Member permissions necessary to utilize this command by default.

This excludes administrators of the guild and overwrites.

description class-attribute instance-attribute #

description: str = field(eq=False, hash=False, repr=False)

The command's description.

None if this command is not a slash command.

Note

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

description_localizations class-attribute instance-attribute #

description_localizations: Mapping[Union[Locale, str], str] = field(
    eq=False, hash=False, repr=False
)

A set of description localizations for this command.

guild_id class-attribute instance-attribute #

guild_id: Optional[Snowflake] = field(eq=False, hash=False, repr=False)

ID of the guild this command is in.

This will be None if this is a global command.

id class-attribute instance-attribute #

id: Snowflake = field(hash=True, repr=True)

ID of this entity.

is_dm_enabled class-attribute instance-attribute #

is_dm_enabled: bool = field(eq=False, hash=False, repr=True)

Whether this command is enabled in DMs with the bot.

is_nsfw class-attribute instance-attribute #

is_nsfw: bool = field(eq=False, hash=False, repr=True)

Whether this command is age-restricted.

name class-attribute instance-attribute #

name: str = field(eq=False, hash=False, repr=True)

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.

name_localizations class-attribute instance-attribute #

name_localizations: Mapping[Union[Locale, str], str] = field(
    eq=False, hash=False, repr=False
)

A mapping of name localizations for this command.

options class-attribute instance-attribute #

options: Optional[Sequence[CommandOption]] = field(
    eq=False, hash=False, repr=False
)

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

type class-attribute instance-attribute #

type: CommandType = field(hash=True, repr=True)

The type of a command.

version class-attribute instance-attribute #

version: Snowflake = field(eq=False, hash=False, repr=True)

Auto-incrementing version identifier updated during substantial record changes.

delete async #

delete() -> None

Delete this command.

RAISES DESCRIPTION
ForbiddenError

If you cannot access the application's commands.
NotFoundError

If the application or command isn't found.
UnauthorizedError

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

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

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

edit async #

edit(
    *,
    name: UndefinedOr[str] = undefined.UNDEFINED,
    description: UndefinedOr[str] = undefined.UNDEFINED,
    options: UndefinedOr[Sequence[CommandOption]] = undefined.UNDEFINED
) -> PartialCommand

Edit this command.

PARAMETER DESCRIPTION
name

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

TYPE: UndefinedOr[str]

description

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

TYPE: UndefinedOr[str]

options

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

TYPE: UndefinedOr[Sequence[CommandOption]]

RETURNS DESCRIPTION
PartialCommand

The edited command object.
RAISES DESCRIPTION
ForbiddenError

If you cannot access the application's commands.
NotFoundError

If the application or command isn't found.
BadRequestError

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

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

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

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

fetch_guild_permissions async #

fetch_guild_permissions(
    guild: SnowflakeishOr[PartialGuild],
) -> GuildCommandPermissions

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

PARAMETER DESCRIPTION
guild

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

TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

RETURNS DESCRIPTION
GuildCommandPermissions

Object of the command permissions set for the specified command.
RAISES DESCRIPTION
ForbiddenError

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

If the provided application or command isn't found.
UnauthorizedError

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

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

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

fetch_self async #

fetch_self() -> PartialCommand

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

RETURNS DESCRIPTION
PartialCommand

Object of the fetched command.
RAISES DESCRIPTION
ForbiddenError

If you cannot access the target command.
NotFoundError

If the command isn't found.
UnauthorizedError

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

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

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

set_guild_permissions async #

set_guild_permissions(
    guild: SnowflakeishOr[PartialGuild],
    permissions: Sequence[CommandPermission],
) -> GuildCommandPermissions

Set permissions for this command in a specific guild.

Note

This overwrites any previously set permissions.

PARAMETER DESCRIPTION
guild

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

TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

permissions

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

TYPE: Sequence[CommandPermission]

RETURNS DESCRIPTION
GuildCommandPermissions

Object of the set permissions.
RAISES DESCRIPTION
ForbiddenError

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

If the provided application or command isn't found.
UnauthorizedError

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

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

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