Models and enums used for application commands on Discord.

This module

Expand source code
Browse git
# -*- coding: utf-8 -*-
# cython: language_level=3
# Copyright (c) 2020 Nekokatt
# Copyright (c) 2021-present davfsa
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Models and enums used for application commands on Discord."""
from __future__ import annotations

__all__: typing.Sequence[str] = (
    "PartialCommand",
    "ContextMenuCommand",
    "SlashCommand",
    "CommandChoice",
    "CommandOption",
    "CommandPermission",
    "CommandPermissionType",
    "CommandType",
    "GuildCommandPermissions",
    "OptionType",
)

import typing

import attr

from hikari import permissions
from hikari import snowflakes
from hikari import traits
from hikari import undefined
from hikari.internal import attr_extensions
from hikari.internal import enums

if typing.TYPE_CHECKING:
    from hikari import channels
    from hikari import guilds
    from hikari import locales


class CommandType(int, enums.Enum):
    """The type of a command."""

    SLASH = 1
    """A text-based command."""

    USER = 2
    """A user-based command."""

    MESSAGE = 3
    """A message-based command."""


@typing.final
class OptionType(int, enums.Enum):
    """The type of a command option."""

    SUB_COMMAND = 1
    """Denotes a command option where the value will be a sub command."""

    SUB_COMMAND_GROUP = 2
    """Denotes a command option where the value will be a sub command group."""

    STRING = 3
    """Denotes a command option where the value will be a string."""

    INTEGER = 4
    """Denotes a command option where the value will be a int.

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

    BOOLEAN = 5
    """Denotes a command option where the value will be a bool."""

    USER = 6
    """Denotes a command option where the value will be resolved to a user."""

    CHANNEL = 7
    """Denotes a command option where the value will be resolved to a channel."""

    ROLE = 8
    """Denotes a command option where the value will be resolved to a role."""

    MENTIONABLE = 9
    """Denotes a command option where the value will be a snowflake ID."""

    FLOAT = 10
    """Denotes a command option where the value will be a float.

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

    ATTACHMENT = 11
    """Denotes a command option where the value will be an attachment."""


@attr_extensions.with_copy
@attr.define(hash=False, kw_only=True, weakref_slot=False)
class CommandChoice:
    """Represents the choices set for an application command's argument."""

    name: str = attr.field(repr=True)
    """The choice's name (inclusively between 1-100 characters)."""

    value: typing.Union[str, int, float] = attr.field(repr=True)
    """Value of the choice (up to 100 characters if a string)."""


@attr_extensions.with_copy
@attr.define(hash=False, kw_only=True, weakref_slot=False)
class CommandOption:
    """Represents an application command's argument."""

    type: typing.Union[OptionType, int] = attr.field(repr=True)
    """The type of command option this is."""

    name: str = attr.field(repr=True)
    r"""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 = attr.field(repr=False)
    """The command option's description.

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

    is_required: bool = attr.field(default=False, repr=False)
    """Whether this command option is required."""

    choices: typing.Optional[typing.Sequence[CommandChoice]] = attr.field(default=None, repr=False)
    """A sequence of up to (and including) 25 choices for this command.

    This will be `builtins.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: typing.Optional[typing.Sequence[CommandOption]] = attr.field(default=None, repr=False)
    """Sequence of up to (and including) 25 of the options for this command option."""

    channel_types: typing.Optional[typing.Sequence[typing.Union[channels.ChannelType, int]]] = attr.field(
        default=None, repr=False
    )
    """The channel types that this option will accept.

    If `builtins.None`, then all channel types will be accepted.
    """

    autocomplete: bool = attr.field(default=False, repr=False)
    """Whether this option has autocomplete."""

    min_value: typing.Union[int, float, None] = attr.field(default=None, repr=False)
    """The minimum value permitted (inclusive).

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

    max_value: typing.Union[int, float, None] = attr.field(default=None, repr=False)
    """The maximum value permitted (inclusive).

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

    name_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of name localizations for this option."""

    description_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of description localizations for this option"""

    min_length: typing.Optional[int] = attr.field(default=None, repr=False)
    """The minimum length permitted (inclusive).

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

    max_length: typing.Optional[int] = attr.field(default=None, repr=False)
    """The maximum length permitted (inclusive).

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


@attr_extensions.with_copy
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class PartialCommand(snowflakes.Unique):
    """Represents any application command on Discord."""

    app: traits.RESTAware = attr.field(eq=False, hash=False, repr=False)
    """The client application that models may use for procedures."""

    id: snowflakes.Snowflake = attr.field(hash=True, repr=True)
    # <<inherited docstring from Unique>>.

    type: CommandType = attr.field(hash=True, repr=True)
    """The type of a command."""

    application_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
    """ID of the application this command belongs to."""

    name: str = attr.field(eq=False, hash=False, repr=True)
    r"""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: permissions.Permissions = attr.field(eq=False, hash=False, repr=True)
    """Member permissions necessary to utilize this command by default.

    This excludes administrators of the guild and overwrites.
    """

    is_dm_enabled: bool = attr.field(eq=False, hash=False, repr=True)
    """Whether this command is enabled in DMs with the bot."""

    guild_id: typing.Optional[snowflakes.Snowflake] = attr.field(eq=False, hash=False, repr=False)
    """ID of the guild this command is in.

    This will be `builtins.None` if this is a global command.
    """

    version: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
    """Auto-incrementing version identifier updated during substantial record changes."""

    name_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of name localizations for this command"""

    description_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of description localizations for this command"""

    async def fetch_self(self) -> PartialCommand:
        """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.
        """
        command = await self.app.rest.fetch_application_command(
            self.application_id, self.id, undefined.UNDEFINED if self.guild_id is None else self.guild_id
        )
        return command

    async def edit(
        self,
        *,
        name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
        description: undefined.UndefinedOr[str] = undefined.UNDEFINED,
        options: undefined.UndefinedOr[typing.Sequence[CommandOption]] = undefined.UNDEFINED,
    ) -> PartialCommand:
        """Edit this command.

        Other Parameters
        ----------------
        guild : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]
            Object or ID of the guild to edit a command for if this is a guild
            specific command. Leave this as `hikari.undefined.UNDEFINED` to delete
            a global command.
        name : hikari.undefined.UndefinedOr[builtins.str]
            The name to set for the command. Leave as `hikari.undefined.UNDEFINED`
            to not change.
        description : hikari.undefined.UndefinedOr[builtins.str]
            The description to set for the command. Leave as `hikari.undefined.UNDEFINED`
            to not change.
        options : hikari.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.
        """
        command = await self.app.rest.edit_application_command(
            self.application_id,
            self.id,
            undefined.UNDEFINED if self.guild_id is None else self.guild_id,
            name=name,
            description=description,
            options=options,
        )
        return command

    async def delete(self) -> None:
        """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.
        """
        await self.app.rest.delete_application_command(
            self.application_id, self.id, undefined.UNDEFINED if self.guild_id is None else self.guild_id
        )

    async def fetch_guild_permissions(
        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], /
    ) -> GuildCommandPermissions:
        """Fetch the permissions registered for this command in a specific guild.

        Parameters
        ----------
        guild : hikari.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.
        """
        return await self.app.rest.fetch_application_command_permissions(
            application=self.application_id, command=self.id, guild=guild
        )

    async def set_guild_permissions(
        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], permissions: typing.Sequence[CommandPermission]
    ) -> GuildCommandPermissions:
        """Set permissions for this command in a specific guild.

        !!! note
            This overwrites any previously set permissions.

        Parameters
        ----------
        guild : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]
            Object or ID of the guild to set the command permissions in.
        permissions : typing.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.
        """
        return await self.app.rest.set_application_command_permissions(
            application=self.application_id, command=self.id, guild=guild, permissions=permissions
        )


@attr_extensions.with_copy
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class SlashCommand(PartialCommand):
    """Represents a slash command on Discord."""

    description: str = attr.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.
    """

    options: typing.Optional[typing.Sequence[CommandOption]] = attr.field(eq=False, hash=False, repr=False)
    """Sequence of up to (and including) 25 of the options for this command."""


@attr_extensions.with_copy
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class ContextMenuCommand(PartialCommand):
    """Represents a context menu command on Discord."""


class CommandPermissionType(int, enums.Enum):
    """The type of entity a command permission targets."""

    ROLE = 1
    """A command permission which toggles access for a specific role."""

    USER = 2
    """A command permission which toggles access for a specific user."""

    CHANNEL = 3
    """A command permission which toggles access in a specific channel."""


@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class CommandPermission:
    """Representation of a permission which enables or disables a command for a user or role."""

    id: snowflakes.Snowflake = attr.field(converter=snowflakes.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: typing.Union[CommandPermissionType, int] = attr.field(converter=CommandPermissionType)
    """The entity this permission overrides the command's state for."""

    has_access: bool = attr.field()
    """Whether this permission marks the target entity as having access to the command."""


@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class GuildCommandPermissions:
    """Representation of the permissions set for a command within a guild."""

    id: snowflakes.Snowflake = attr.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.
    """

    application_id: snowflakes.Snowflake = attr.field()
    """ID of the application the relevant command belongs to."""

    command_id: snowflakes.Snowflake = attr.field()
    """ID of the command these permissions are for."""

    guild_id: snowflakes.Snowflake = attr.field()
    """ID of the guild these permissions are in."""

    permissions: typing.Sequence[CommandPermission] = attr.field()
    """Sequence of up to (and including) 100 of the command permissions set in this guild."""

Classes

dataclass CommandChoice

class CommandChoice (
    *,
    name: str,
    value: Union[strintfloat],
): ...

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

Method generated by attrs for class CommandChoice.

Expand source code
Browse git
class CommandChoice:
    """Represents the choices set for an application command's argument."""

    name: str = attr.field(repr=True)
    """The choice's name (inclusively between 1-100 characters)."""

    value: typing.Union[str, int, float] = attr.field(repr=True)
    """Value of the choice (up to 100 characters if a string)."""
Variables and properties
property namestr

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

property value : Union[strintfloat]

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

dataclass CommandOption

class CommandOption (
    *,
    type: Union[OptionTypeint],
    name: str,
    description: str,
    is_required: bool = False,
    choices: Optional[Sequence[CommandChoice]] = None,
    options: Optional[Sequence[CommandOption]] = None,
    channel_types: Optional[Sequence[Union[channels.ChannelTypeint]]] = None,
    autocomplete: bool = False,
    min_value: Union[intfloatNone] = None,
    max_value: Union[intfloatNone] = None,
    name_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
    description_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
    min_length: Optional[int] = None,
    max_length: Optional[int] = None,
): ...

Represents an application command's argument.

Method generated by attrs for class CommandOption.

Expand source code
Browse git
class CommandOption:
    """Represents an application command's argument."""

    type: typing.Union[OptionType, int] = attr.field(repr=True)
    """The type of command option this is."""

    name: str = attr.field(repr=True)
    r"""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 = attr.field(repr=False)
    """The command option's description.

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

    is_required: bool = attr.field(default=False, repr=False)
    """Whether this command option is required."""

    choices: typing.Optional[typing.Sequence[CommandChoice]] = attr.field(default=None, repr=False)
    """A sequence of up to (and including) 25 choices for this command.

    This will be `builtins.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: typing.Optional[typing.Sequence[CommandOption]] = attr.field(default=None, repr=False)
    """Sequence of up to (and including) 25 of the options for this command option."""

    channel_types: typing.Optional[typing.Sequence[typing.Union[channels.ChannelType, int]]] = attr.field(
        default=None, repr=False
    )
    """The channel types that this option will accept.

    If `builtins.None`, then all channel types will be accepted.
    """

    autocomplete: bool = attr.field(default=False, repr=False)
    """Whether this option has autocomplete."""

    min_value: typing.Union[int, float, None] = attr.field(default=None, repr=False)
    """The minimum value permitted (inclusive).

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

    max_value: typing.Union[int, float, None] = attr.field(default=None, repr=False)
    """The maximum value permitted (inclusive).

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

    name_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of name localizations for this option."""

    description_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of description localizations for this option"""

    min_length: typing.Optional[int] = attr.field(default=None, repr=False)
    """The minimum length permitted (inclusive).

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

    max_length: typing.Optional[int] = attr.field(default=None, repr=False)
    """The maximum length permitted (inclusive).

    This is only valid for `hikari.commands.OptionType.STRING`, otherwise it will be `builtins.None`.
    """
Variables and properties
property autocompletebool

Whether this option has autocomplete.

property channel_typesOptional[Sequence[Union[channels.ChannelType, int]]]

The channel types that this option will accept.

If None, then all channel types will be accepted.

property choicesOptional[Sequence[CommandChoice]]

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.

property descriptionstr

The command option's description.

Note

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

property description_localizationsMapping[Union[locales.Locale, str], str]

A set of description localizations for this option

property is_requiredbool

Whether this command option is required.

property max_lengthOptional[int]

The maximum length permitted (inclusive).

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

property max_valueUnion[int, float, None]

The maximum value permitted (inclusive).

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

property min_lengthOptional[int]

The minimum length permitted (inclusive).

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

property min_valueUnion[int, float, None]

The minimum value permitted (inclusive).

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

property namestr

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.

property name_localizationsMapping[Union[locales.Locale, str], str]

A set of name localizations for this option.

property optionsOptional[Sequence[CommandOption]]

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

property typeUnion[OptionType, int]

The type of command option this is.

dataclass CommandPermission

class CommandPermission (
    *,
    id,
    type: Any,
    has_access: bool,
): ...

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

Method generated by attrs for class CommandPermission.

Expand source code
Browse git
class CommandPermission:
    """Representation of a permission which enables or disables a command for a user or role."""

    id: snowflakes.Snowflake = attr.field(converter=snowflakes.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: typing.Union[CommandPermissionType, int] = attr.field(converter=CommandPermissionType)
    """The entity this permission overrides the command's state for."""

    has_access: bool = attr.field()
    """Whether this permission marks the target entity as having access to the command."""
Variables and properties
property has_accessbool

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

property idSnowflake

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.
property type : Union[CommandPermissionTypeint]

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

enum CommandPermissionType

class CommandPermissionType (
    value: Any,
): ...

The type of entity a command permission targets.

Expand source code
Browse git
class CommandPermissionType(int, enums.Enum):
    """The type of entity a command permission targets."""

    ROLE = 1
    """A command permission which toggles access for a specific role."""

    USER = 2
    """A command permission which toggles access for a specific user."""

    CHANNEL = 3
    """A command permission which toggles access in a specific channel."""
Method resolution order
enum CommandPermissionType
That's this class!
extern class int

int([x]) -> integer int(x, base=10) -> integer …

enum Enum

Clone of Python's enum.Enum implementation …

Variables and properties
property namestr

Return the name of the enum member as a str.

property value

Return the value of the enum member.

const CHANNEL = 3

A command permission which toggles access in a specific channel.

const ROLE = 1

A command permission which toggles access for a specific role.

const USER = 2

A command permission which toggles access for a specific user.

enum CommandType

class CommandType (
    value: Any,
): ...

The type of a command.

Expand source code
Browse git
class CommandType(int, enums.Enum):
    """The type of a command."""

    SLASH = 1
    """A text-based command."""

    USER = 2
    """A user-based command."""

    MESSAGE = 3
    """A message-based command."""
Method resolution order
enum CommandType
That's this class!
extern class int

int([x]) -> integer int(x, base=10) -> integer …

enum Enum

Clone of Python's enum.Enum implementation …

Variables and properties
property namestr

Return the name of the enum member as a str.

property value

Return the value of the enum member.

const MESSAGE = 3

A message-based command.

const SLASH = 1

A text-based command.

const USER = 2

A user-based command.

dataclass ContextMenuCommand

class ContextMenuCommand (
    *,
    app: traits.RESTAware,
    id: snowflakes.Snowflake,
    type: CommandType,
    application_id: snowflakes.Snowflake,
    name: str,
    default_member_permissions: permissions.Permissions,
    is_dm_enabled: bool,
    guild_id: Optional[snowflakes.Snowflake],
    version: snowflakes.Snowflake,
    name_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
    description_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
): ...

Represents a context menu command on Discord.

Method generated by attrs for class ContextMenuCommand.

Expand source code
Browse git
class ContextMenuCommand(PartialCommand):
    """Represents a context menu command on Discord."""
Method resolution order
dataclass ContextMenuCommand
That's this class!
dataclass PartialCommand

Represents any application command on Discord …

abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

Return an attribute of instance, which is of type owner.

property application_idsnowflakes.Snowflake

Return an attribute of instance, which is of type owner.

property created_atdatetime.datetime

When the object was created.

property default_member_permissionspermissions.Permissions

Return an attribute of instance, which is of type owner.

property description_localizationsMapping[Union[locales.Locale, str], str]

Return an attribute of instance, which is of type owner.

property guild_idOptional[snowflakes.Snowflake]

Return an attribute of instance, which is of type owner.

property idsnowflakes.Snowflake

Return the ID of this entity.

Returns

Snowflake
The snowflake ID of this object.
property is_dm_enabledbool

Return an attribute of instance, which is of type owner.

property namestr

Return an attribute of instance, which is of type owner.

property name_localizationsMapping[Union[locales.Locale, str], str]

Return an attribute of instance, which is of type owner.

property typeCommandType

Return an attribute of instance, which is of type owner.

property versionsnowflakes.Snowflake

Return an attribute of instance, which is of type owner.

Methods
async def delete() -> None: ...

Inherited from: PartialCommand.delete

Delete this command.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def edit(
    *,
    name: undefined.UndefinedOr[str] = UNDEFINED,
    description: undefined.UndefinedOr[str] = UNDEFINED,
    options: undefined.UndefinedOr[Sequence[CommandOption]] = UNDEFINED,
) -> PartialCommand: ...

Inherited from: PartialCommand.edit

Edit this command.

Other Parameters

guild : UndefinedOr[SnowflakeishOr[PartialGuild]]
Object or ID of the guild to edit a command for if this is a guild specific command. Leave this as UNDEFINED to delete a global command.
name : UndefinedOr[str]
The name to set for the command. Leave as UNDEFINED to not change.
description : UndefinedOr[str]
The description to set for the command. Leave as UNDEFINED to not change.
options : UndefinedOr[Sequence[CommandOption]]
A sequence of up to 10 options to set for this command. Leave this as UNDEFINED to not change.

Returns

PartialCommand
The edited command object.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_guild_permissions(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    /,
) -> GuildCommandPermissions: ...

Inherited from: PartialCommand.fetch_guild_permissions

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

Parameters

guild : UndefinedOr[SnowflakeishOr[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

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_self() -> PartialCommand: ...

Inherited from: PartialCommand.fetch_self

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

Returns

PartialCommand
Object of the fetched command.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def set_guild_permissions(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    permissions: Sequence[CommandPermission],
) -> GuildCommandPermissions: ...

Inherited from: PartialCommand.set_guild_permissions

Set permissions for this command in a specific guild.

Note

This overwrites any previously set permissions.

Parameters

guild : UndefinedOr[SnowflakeishOr[PartialGuild]]
Object or ID of the guild to set the command permissions in.
permissions : Sequence[CommandPermission]
Sequence of up to 10 of the permission objects to set.

Returns

GuildCommandPermissions
Object of the set permissions.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.

dataclass GuildCommandPermissions

class GuildCommandPermissions (
    *,
    id: snowflakes.Snowflake,
    application_id: snowflakes.Snowflake,
    command_id: snowflakes.Snowflake,
    guild_id: snowflakes.Snowflake,
    permissions: Sequence[CommandPermission],
): ...

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

Method generated by attrs for class GuildCommandPermissions.

Expand source code
Browse git
class GuildCommandPermissions:
    """Representation of the permissions set for a command within a guild."""

    id: snowflakes.Snowflake = attr.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.
    """

    application_id: snowflakes.Snowflake = attr.field()
    """ID of the application the relevant command belongs to."""

    command_id: snowflakes.Snowflake = attr.field()
    """ID of the command these permissions are for."""

    guild_id: snowflakes.Snowflake = attr.field()
    """ID of the guild these permissions are in."""

    permissions: typing.Sequence[CommandPermission] = attr.field()
    """Sequence of up to (and including) 100 of the command permissions set in this guild."""
Variables and properties
property application_idSnowflake

ID of the application the relevant command belongs to.

property command_idSnowflake

ID of the command these permissions are for.

property guild_idSnowflake

ID of the guild these permissions are in.

property idSnowflake

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.

property permissions : Sequence[CommandPermission]

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

enum OptionType

class OptionType (
    value: Any,
): ...

The type of a command option.

Expand source code
Browse git
class OptionType(int, enums.Enum):
    """The type of a command option."""

    SUB_COMMAND = 1
    """Denotes a command option where the value will be a sub command."""

    SUB_COMMAND_GROUP = 2
    """Denotes a command option where the value will be a sub command group."""

    STRING = 3
    """Denotes a command option where the value will be a string."""

    INTEGER = 4
    """Denotes a command option where the value will be a int.

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

    BOOLEAN = 5
    """Denotes a command option where the value will be a bool."""

    USER = 6
    """Denotes a command option where the value will be resolved to a user."""

    CHANNEL = 7
    """Denotes a command option where the value will be resolved to a channel."""

    ROLE = 8
    """Denotes a command option where the value will be resolved to a role."""

    MENTIONABLE = 9
    """Denotes a command option where the value will be a snowflake ID."""

    FLOAT = 10
    """Denotes a command option where the value will be a float.

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

    ATTACHMENT = 11
    """Denotes a command option where the value will be an attachment."""
Method resolution order
enum OptionType
That's this class!
extern class int

int([x]) -> integer int(x, base=10) -> integer …

enum Enum

Clone of Python's enum.Enum implementation …

Variables and properties
property namestr

Return the name of the enum member as a str.

property value

Return the value of the enum member.

const ATTACHMENT = 11

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

const BOOLEAN = 5

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

const CHANNEL = 7

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

const FLOAT = 10

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

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

const INTEGER = 4

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

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

const MENTIONABLE = 9

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

const ROLE = 8

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

const STRING = 3

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

const SUB_COMMAND = 1

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

const SUB_COMMAND_GROUP = 2

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

const USER = 6

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

dataclass PartialCommand

class PartialCommand (
    *,
    app: traits.RESTAware,
    id: snowflakes.Snowflake,
    type: CommandType,
    application_id: snowflakes.Snowflake,
    name: str,
    default_member_permissions: permissions.Permissions,
    is_dm_enabled: bool,
    guild_id: Optional[snowflakes.Snowflake],
    version: snowflakes.Snowflake,
    name_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
    description_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
): ...

Represents any application command on Discord.

Method generated by attrs for class PartialCommand.

Expand source code
Browse git
class PartialCommand(snowflakes.Unique):
    """Represents any application command on Discord."""

    app: traits.RESTAware = attr.field(eq=False, hash=False, repr=False)
    """The client application that models may use for procedures."""

    id: snowflakes.Snowflake = attr.field(hash=True, repr=True)
    # <<inherited docstring from Unique>>.

    type: CommandType = attr.field(hash=True, repr=True)
    """The type of a command."""

    application_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
    """ID of the application this command belongs to."""

    name: str = attr.field(eq=False, hash=False, repr=True)
    r"""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: permissions.Permissions = attr.field(eq=False, hash=False, repr=True)
    """Member permissions necessary to utilize this command by default.

    This excludes administrators of the guild and overwrites.
    """

    is_dm_enabled: bool = attr.field(eq=False, hash=False, repr=True)
    """Whether this command is enabled in DMs with the bot."""

    guild_id: typing.Optional[snowflakes.Snowflake] = attr.field(eq=False, hash=False, repr=False)
    """ID of the guild this command is in.

    This will be `builtins.None` if this is a global command.
    """

    version: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
    """Auto-incrementing version identifier updated during substantial record changes."""

    name_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of name localizations for this command"""

    description_localizations: typing.Mapping[typing.Union[locales.Locale, str], str] = attr.field(factory=dict)
    """A set of description localizations for this command"""

    async def fetch_self(self) -> PartialCommand:
        """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.
        """
        command = await self.app.rest.fetch_application_command(
            self.application_id, self.id, undefined.UNDEFINED if self.guild_id is None else self.guild_id
        )
        return command

    async def edit(
        self,
        *,
        name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
        description: undefined.UndefinedOr[str] = undefined.UNDEFINED,
        options: undefined.UndefinedOr[typing.Sequence[CommandOption]] = undefined.UNDEFINED,
    ) -> PartialCommand:
        """Edit this command.

        Other Parameters
        ----------------
        guild : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]
            Object or ID of the guild to edit a command for if this is a guild
            specific command. Leave this as `hikari.undefined.UNDEFINED` to delete
            a global command.
        name : hikari.undefined.UndefinedOr[builtins.str]
            The name to set for the command. Leave as `hikari.undefined.UNDEFINED`
            to not change.
        description : hikari.undefined.UndefinedOr[builtins.str]
            The description to set for the command. Leave as `hikari.undefined.UNDEFINED`
            to not change.
        options : hikari.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.
        """
        command = await self.app.rest.edit_application_command(
            self.application_id,
            self.id,
            undefined.UNDEFINED if self.guild_id is None else self.guild_id,
            name=name,
            description=description,
            options=options,
        )
        return command

    async def delete(self) -> None:
        """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.
        """
        await self.app.rest.delete_application_command(
            self.application_id, self.id, undefined.UNDEFINED if self.guild_id is None else self.guild_id
        )

    async def fetch_guild_permissions(
        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], /
    ) -> GuildCommandPermissions:
        """Fetch the permissions registered for this command in a specific guild.

        Parameters
        ----------
        guild : hikari.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.
        """
        return await self.app.rest.fetch_application_command_permissions(
            application=self.application_id, command=self.id, guild=guild
        )

    async def set_guild_permissions(
        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], permissions: typing.Sequence[CommandPermission]
    ) -> GuildCommandPermissions:
        """Set permissions for this command in a specific guild.

        !!! note
            This overwrites any previously set permissions.

        Parameters
        ----------
        guild : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]
            Object or ID of the guild to set the command permissions in.
        permissions : typing.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.
        """
        return await self.app.rest.set_application_command_permissions(
            application=self.application_id, command=self.id, guild=guild, permissions=permissions
        )
Subclasses
dataclass ContextMenuCommand

Represents a context menu command on Discord …

dataclass SlashCommand

Represents a slash command on Discord …

Method resolution order
dataclass PartialCommand
That's this class!
abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

The client application that models may use for procedures.

property application_idsnowflakes.Snowflake

ID of the application this command belongs to.

property created_atdatetime.datetime

When the object was created.

property default_member_permissionspermissions.Permissions

Member permissions necessary to utilize this command by default.

This excludes administrators of the guild and overwrites.

property description_localizationsMapping[Union[locales.Locale, str], str]

A set of description localizations for this command

property guild_idOptional[snowflakes.Snowflake]

ID of the guild this command is in.

This will be None if this is a global command.

property idsnowflakes.Snowflake

Return the ID of this entity.

Returns

Snowflake
The snowflake ID of this object.
property is_dm_enabledbool

Whether this command is enabled in DMs with the bot.

property namestr

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.

property name_localizationsMapping[Union[locales.Locale, str], str]

A set of name localizations for this command

property typeCommandType

The type of a command.

property versionsnowflakes.Snowflake

Auto-incrementing version identifier updated during substantial record changes.

Methods
async def delete() -> None: ...

Delete this command.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def delete(self) -> None:
    """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.
    """
    await self.app.rest.delete_application_command(
        self.application_id, self.id, undefined.UNDEFINED if self.guild_id is None else self.guild_id
    )
async def edit(
    *,
    name: undefined.UndefinedOr[str] = UNDEFINED,
    description: undefined.UndefinedOr[str] = UNDEFINED,
    options: undefined.UndefinedOr[Sequence[CommandOption]] = UNDEFINED,
) -> PartialCommand: ...

Edit this command.

Other Parameters

guild : UndefinedOr[SnowflakeishOr[PartialGuild]]
Object or ID of the guild to edit a command for if this is a guild specific command. Leave this as UNDEFINED to delete a global command.
name : UndefinedOr[str]
The name to set for the command. Leave as UNDEFINED to not change.
description : UndefinedOr[str]
The description to set for the command. Leave as UNDEFINED to not change.
options : UndefinedOr[Sequence[CommandOption]]
A sequence of up to 10 options to set for this command. Leave this as UNDEFINED to not change.

Returns

PartialCommand
The edited command object.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def edit(
    self,
    *,
    name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
    description: undefined.UndefinedOr[str] = undefined.UNDEFINED,
    options: undefined.UndefinedOr[typing.Sequence[CommandOption]] = undefined.UNDEFINED,
) -> PartialCommand:
    """Edit this command.

    Other Parameters
    ----------------
    guild : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]
        Object or ID of the guild to edit a command for if this is a guild
        specific command. Leave this as `hikari.undefined.UNDEFINED` to delete
        a global command.
    name : hikari.undefined.UndefinedOr[builtins.str]
        The name to set for the command. Leave as `hikari.undefined.UNDEFINED`
        to not change.
    description : hikari.undefined.UndefinedOr[builtins.str]
        The description to set for the command. Leave as `hikari.undefined.UNDEFINED`
        to not change.
    options : hikari.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.
    """
    command = await self.app.rest.edit_application_command(
        self.application_id,
        self.id,
        undefined.UNDEFINED if self.guild_id is None else self.guild_id,
        name=name,
        description=description,
        options=options,
    )
    return command
async def fetch_guild_permissions(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    /,
) -> GuildCommandPermissions: ...

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

Parameters

guild : UndefinedOr[SnowflakeishOr[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

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_guild_permissions(
    self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], /
) -> GuildCommandPermissions:
    """Fetch the permissions registered for this command in a specific guild.

    Parameters
    ----------
    guild : hikari.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.
    """
    return await self.app.rest.fetch_application_command_permissions(
        application=self.application_id, command=self.id, guild=guild
    )
async def fetch_self() -> PartialCommand: ...

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

Returns

PartialCommand
Object of the fetched command.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def fetch_self(self) -> PartialCommand:
    """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.
    """
    command = await self.app.rest.fetch_application_command(
        self.application_id, self.id, undefined.UNDEFINED if self.guild_id is None else self.guild_id
    )
    return command
async def set_guild_permissions(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    permissions: Sequence[CommandPermission],
) -> GuildCommandPermissions: ...

Set permissions for this command in a specific guild.

Note

This overwrites any previously set permissions.

Parameters

guild : UndefinedOr[SnowflakeishOr[PartialGuild]]
Object or ID of the guild to set the command permissions in.
permissions : Sequence[CommandPermission]
Sequence of up to 10 of the permission objects to set.

Returns

GuildCommandPermissions
Object of the set permissions.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
Expand source code
Browse git
async def set_guild_permissions(
    self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], permissions: typing.Sequence[CommandPermission]
) -> GuildCommandPermissions:
    """Set permissions for this command in a specific guild.

    !!! note
        This overwrites any previously set permissions.

    Parameters
    ----------
    guild : hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]]
        Object or ID of the guild to set the command permissions in.
    permissions : typing.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.
    """
    return await self.app.rest.set_application_command_permissions(
        application=self.application_id, command=self.id, guild=guild, permissions=permissions
    )

dataclass SlashCommand

class SlashCommand (
    *,
    app: traits.RESTAware,
    id: snowflakes.Snowflake,
    type: CommandType,
    application_id: snowflakes.Snowflake,
    name: str,
    default_member_permissions: permissions.Permissions,
    is_dm_enabled: bool,
    guild_id: Optional[snowflakes.Snowflake],
    version: snowflakes.Snowflake,
    name_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
    description_localizations: Mapping[Union[locales.Localestr], str] = NOTHING,
    description: str,
    options: Optional[Sequence[CommandOption]],
): ...

Represents a slash command on Discord.

Method generated by attrs for class SlashCommand.

Expand source code
Browse git
class SlashCommand(PartialCommand):
    """Represents a slash command on Discord."""

    description: str = attr.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.
    """

    options: typing.Optional[typing.Sequence[CommandOption]] = attr.field(eq=False, hash=False, repr=False)
    """Sequence of up to (and including) 25 of the options for this command."""
Method resolution order
dataclass SlashCommand
That's this class!
dataclass PartialCommand

Represents any application command on Discord …

abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

The client application that models may use for procedures.

property application_idsnowflakes.Snowflake

ID of the application this command belongs to.

property created_atdatetime.datetime

When the object was created.

property default_member_permissionspermissions.Permissions

Member permissions necessary to utilize this command by default.

This excludes administrators of the guild and overwrites.

property descriptionstr

The command's description.

None if this command is not a slash command.

Note

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

property description_localizationsMapping[Union[locales.Locale, str], str]

A set of description localizations for this command

property guild_idOptional[snowflakes.Snowflake]

ID of the guild this command is in.

This will be None if this is a global command.

property idsnowflakes.Snowflake

Return the ID of this entity.

Returns

Snowflake
The snowflake ID of this object.
property is_dm_enabledbool

Whether this command is enabled in DMs with the bot.

property namestr

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.

property name_localizationsMapping[Union[locales.Locale, str], str]

A set of name localizations for this command

property optionsOptional[Sequence[CommandOption]]

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

property typeCommandType

The type of a command.

property versionsnowflakes.Snowflake

Auto-incrementing version identifier updated during substantial record changes.

Methods
async def delete() -> None: ...

Inherited from: PartialCommand.delete

Delete this command.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def edit(
    *,
    name: undefined.UndefinedOr[str] = UNDEFINED,
    description: undefined.UndefinedOr[str] = UNDEFINED,
    options: undefined.UndefinedOr[Sequence[CommandOption]] = UNDEFINED,
) -> PartialCommand: ...

Inherited from: PartialCommand.edit

Edit this command.

Other Parameters

guild : UndefinedOr[SnowflakeishOr[PartialGuild]]
Object or ID of the guild to edit a command for if this is a guild specific command. Leave this as UNDEFINED to delete a global command.
name : UndefinedOr[str]
The name to set for the command. Leave as UNDEFINED to not change.
description : UndefinedOr[str]
The description to set for the command. Leave as UNDEFINED to not change.
options : UndefinedOr[Sequence[CommandOption]]
A sequence of up to 10 options to set for this command. Leave this as UNDEFINED to not change.

Returns

PartialCommand
The edited command object.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_guild_permissions(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    /,
) -> GuildCommandPermissions: ...

Inherited from: PartialCommand.fetch_guild_permissions

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

Parameters

guild : UndefinedOr[SnowflakeishOr[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

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_self() -> PartialCommand: ...

Inherited from: PartialCommand.fetch_self

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

Returns

PartialCommand
Object of the fetched command.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def set_guild_permissions(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    permissions: Sequence[CommandPermission],
) -> GuildCommandPermissions: ...

Inherited from: PartialCommand.set_guild_permissions

Set permissions for this command in a specific guild.

Note

This overwrites any previously set permissions.

Parameters

guild : UndefinedOr[SnowflakeishOr[PartialGuild]]
Object or ID of the guild to set the command permissions in.
permissions : Sequence[CommandPermission]
Sequence of up to 10 of the permission objects to set.

Returns

GuildCommandPermissions
Object of the set permissions.

Raises

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.
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.
InternalServerError
If an internal error occurs on Discord while handling the request.