diff --git a/discord/app_commands/__init__.py b/discord/app_commands/__init__.py index c5a988dcb..3e88e4d4a 100644 --- a/discord/app_commands/__init__.py +++ b/discord/app_commands/__init__.py @@ -10,7 +10,6 @@ Application commands support for the Discord API """ from .commands import * -from .enums import * from .errors import * from .models import * from .tree import * diff --git a/discord/app_commands/commands.py b/discord/app_commands/commands.py index cef77b8fe..e30e8b001 100644 --- a/discord/app_commands/commands.py +++ b/discord/app_commands/commands.py @@ -44,7 +44,7 @@ from textwrap import TextWrapper import re -from .enums import AppCommandOptionType, AppCommandType +from ..enums import AppCommandOptionType, AppCommandType from ..interactions import Interaction from .models import Choice from .transformers import annotation_to_parameter, CommandParameter, NoneType @@ -63,6 +63,7 @@ __all__ = ( 'Command', 'ContextMenu', 'Group', + 'context_menu', 'command', 'describe', 'choices', @@ -307,7 +308,7 @@ class Command(Generic[GroupT, P, T]): description: :class:`str` The description of the application command. This shows up in the UI to describe the application command. - parent: Optional[:class:`CommandGroup`] + parent: Optional[:class:`Group`] The parent application command. ``None`` if there isn't one. """ @@ -497,7 +498,7 @@ class Command(Generic[GroupT, P, T]): Parameters ----------- - name: :clas:`str` + name: :class:`str` The parameter name to register as autocomplete. Raises @@ -605,7 +606,7 @@ class Group: The description of the group. This shows up in the UI to describe the group. If not given, it defaults to the docstring of the class shortened to 100 characters. - parent: Optional[:class:`CommandGroup`] + parent: Optional[:class:`Group`] The parent group. ``None`` if there isn't one. """ @@ -705,7 +706,7 @@ class Group: ----------- interaction: :class:`~discord.Interaction` The interaction that is being handled. - command: :class`~discord.app_commands.Command` + command: :class:`~discord.app_commands.Command` The command that failed. error: :exc:`AppCommandError` The exception that was raised. diff --git a/discord/app_commands/enums.py b/discord/app_commands/enums.py deleted file mode 100644 index 39e4f4613..000000000 --- a/discord/app_commands/enums.py +++ /dev/null @@ -1,53 +0,0 @@ -""" -The MIT License (MIT) - -Copyright (c) 2015-present Rapptz - -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. -""" - -from ..enums import Enum - -__all__ = ( - 'AppCommandOptionType', - 'AppCommandType', -) - - -class AppCommandOptionType(Enum): - subcommand = 1 - subcommand_group = 2 - string = 3 - integer = 4 - boolean = 5 - user = 6 - channel = 7 - role = 8 - mentionable = 9 - number = 10 - attachment = 11 - - def is_argument(self) -> bool: - return 11 >= self.value >= 3 - - -class AppCommandType(Enum): - chat_input = 1 - user = 2 - message = 3 diff --git a/discord/app_commands/errors.py b/discord/app_commands/errors.py index e175d7084..e4a379e09 100644 --- a/discord/app_commands/errors.py +++ b/discord/app_commands/errors.py @@ -27,7 +27,7 @@ from __future__ import annotations from typing import Any, TYPE_CHECKING, List, Optional, Type, Union -from .enums import AppCommandOptionType, AppCommandType +from ..enums import AppCommandOptionType, AppCommandType from ..errors import DiscordException __all__ = ( @@ -102,7 +102,7 @@ class TransformerError(AppCommandError): ----------- value: Any The value that failed to convert. - type: :class:`AppCommandOptionType` + type: :class:`~discord.AppCommandOptionType` The type of argument that failed to convert. transformer: Type[:class:`Transformer`] The transformer that failed the conversion. @@ -164,7 +164,7 @@ class CommandNotFound(AppCommandError): parents: List[:class:`str`] A list of parent command names that were previously found prior to the application command not being found. - type: :class:`AppCommandType` + type: :class:`~discord.AppCommandType` The type of command that was not found. """ diff --git a/discord/app_commands/models.py b/discord/app_commands/models.py index 3368837ac..b4654988a 100644 --- a/discord/app_commands/models.py +++ b/discord/app_commands/models.py @@ -27,10 +27,9 @@ from datetime import datetime from ..permissions import Permissions -from ..enums import ChannelType, try_enum +from ..enums import AppCommandOptionType, AppCommandType, ChannelType, try_enum from ..mixins import Hashable from ..utils import _get_as_snowflake, parse_time, snowflake_time -from .enums import AppCommandOptionType, AppCommandType from typing import Generic, List, TYPE_CHECKING, Optional, TypeVar, Union __all__ = ( @@ -100,7 +99,7 @@ class AppCommand(Hashable): The application command's ID. application_id: :class:`int` The application command's application's ID. - type: :class:`ApplicationCommandType` + type: :class:`~discord.AppCommandType` The application command's type. name: :class:`str` The application command's name. @@ -424,7 +423,7 @@ class AppCommandThread(Hashable): @property def parent(self) -> Optional[TextChannel]: - """Optional[:class:`TextChannel`]: The parent channel this thread belongs to.""" + """Optional[:class:`~discord.TextChannel`]: The parent channel this thread belongs to.""" return self.guild.get_channel(self.parent_id) # type: ignore @property @@ -486,7 +485,7 @@ class Argument: Attributes ------------ - type: :class:`AppCommandOptionType` + type: :class:`~discord.AppCommandOptionType` The type of argument. name: :class:`str` The name of the argument. @@ -543,7 +542,7 @@ class AppCommandGroup: Attributes ------------ - type: :class:`ApplicationCommandOptionType` + type: :class:`~discord.AppCommandOptionType` The type of subcommand. name: :class:`str` The name of the subcommand. diff --git a/discord/app_commands/namespace.py b/discord/app_commands/namespace.py index 9c6b1c5d0..7f5d797fa 100644 --- a/discord/app_commands/namespace.py +++ b/discord/app_commands/namespace.py @@ -31,8 +31,8 @@ from ..object import Object from ..role import Role from ..message import Message, Attachment from ..channel import PartialMessageable +from ..enums import AppCommandOptionType from .models import AppCommandChannel, AppCommandThread -from .enums import AppCommandOptionType if TYPE_CHECKING: from ..types.interactions import ResolvedData, ApplicationCommandInteractionDataOption @@ -84,27 +84,27 @@ class Namespace: This namespace object converts resolved objects into their appropriate form depending on their type. Consult the table below for conversion information. - +------------------------------------------+-------------------------------------------------------------------------------+ - | Option Type | Resolved Type | - +==========================================+===============================================================================+ - | :attr:`AppCommandOptionType.string` | :class:`str` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.integer` | :class:`int` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.boolean` | :class:`bool` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.number` | :class:`float` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.user` | :class:`~discord.User` or :class:`~discord.Member` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.channel` | :class:`.AppCommandChannel` or :class:`.AppCommandThread` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.role` | :class:`~discord.Role` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.mentionable` | :class:`~discord.User` or :class:`~discord.Member`, or :class:`~discord.Role` | - +------------------------------------------+-------------------------------------------------------------------------------+ - | :attr:`AppCommandOptionType.attachment` | :class:`~discord.Attachment` | - +------------------------------------------+-------------------------------------------------------------------------------+ + +-------------------------------------------+-------------------------------------------------------------------------------+ + | Option Type | Resolved Type | + +===========================================+===============================================================================+ + | :attr:`.AppCommandOptionType.string` | :class:`str` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.integer` | :class:`int` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.boolean` | :class:`bool` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.number` | :class:`float` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.user` | :class:`~discord.User` or :class:`~discord.Member` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.channel` | :class:`.AppCommandChannel` or :class:`.AppCommandThread` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.role` | :class:`~discord.Role` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.mentionable` | :class:`~discord.User` or :class:`~discord.Member`, or :class:`~discord.Role` | + +-------------------------------------------+-------------------------------------------------------------------------------+ + | :attr:`.AppCommandOptionType.attachment` | :class:`~discord.Attachment` | + +-------------------------------------------+-------------------------------------------------------------------------------+ """ def __init__( diff --git a/discord/app_commands/transformers.py b/discord/app_commands/transformers.py index 454d66de6..0456a2005 100644 --- a/discord/app_commands/transformers.py +++ b/discord/app_commands/transformers.py @@ -44,11 +44,10 @@ from typing import ( Union, ) -from .enums import AppCommandOptionType from .errors import TransformerError from .models import AppCommandChannel, AppCommandThread, Choice from ..channel import StageChannel, StoreChannel, VoiceChannel, TextChannel, CategoryChannel -from ..enums import ChannelType +from ..enums import AppCommandOptionType, ChannelType from ..utils import MISSING from ..user import User from ..role import Role @@ -82,7 +81,7 @@ class CommandParameter: Whether the parameter is required choices: List[:class:`~discord.app_commands.Choice`] A list of choices this parameter takes - type: :class:`~discord.app_commands.AppCommandOptionType` + type: :class:`~discord.AppCommandOptionType` The underlying type of this parameter. channel_types: List[:class:`~discord.ChannelType`] The channel types that are allowed for this parameter. @@ -140,10 +139,10 @@ class CommandParameter: class Transformer: """The base class that allows a type annotation in an application command parameter - to map into a :class:`AppCommandOptionType` and transform the raw value into one from - this type. + to map into a :class:`~discord.AppCommandOptionType` and transform the raw value into one + from this type. - This class is customisable through the overriding of :obj:`classmethod`s in the class + This class is customisable through the overriding of :func:`classmethod` in the class and by using it as the second type parameter of the :class:`~discord.app_commands.Transform` class. For example, to convert a string into a custom pair type: @@ -174,11 +173,11 @@ class Transformer: @classmethod def type(cls) -> AppCommandOptionType: - """:class:`AppCommandOptionType`: The option type associated with this transformer. + """:class:`~discord.AppCommandOptionType`: The option type associated with this transformer. This must be a :obj:`classmethod`. - Defaults to :attr:`AppCommandOptionType.string`. + Defaults to :attr:`~discord.AppCommandOptionType.string`. """ return AppCommandOptionType.string @@ -186,7 +185,7 @@ class Transformer: def channel_types(cls) -> List[ChannelType]: """List[:class:`~discord.ChannelType`]: A list of channel types that are allowed to this parameter. - Only valid if the :meth:`type` returns :attr:`AppCommandOptionType.channel`. + Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.channel`. Defaults to an empty list. """ @@ -196,8 +195,8 @@ class Transformer: def min_value(cls) -> Optional[Union[int, float]]: """Optional[:class:`int`]: The minimum supported value for this parameter. - Only valid if the :meth:`type` returns :attr:`AppCommandOptionType.number` or - :attr:`AppCommandOptionType.integer`. + Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.number` or + :attr:`~discord.AppCommandOptionType.integer`. Defaults to ``None``. """ @@ -207,8 +206,8 @@ class Transformer: def max_value(cls) -> Optional[Union[int, float]]: """Optional[:class:`int`]: The maximum supported value for this parameter. - Only valid if the :meth:`type` returns :attr:`AppCommandOptionType.number` or - :attr:`AppCommandOptionType.integer`. + Only valid if the :meth:`type` returns :attr:`~discord.AppCommandOptionType.number` or + :attr:`~discord.AppCommandOptionType.integer`. Defaults to ``None``. """ @@ -341,7 +340,7 @@ else: the usage of two generic parameters, the first one is the type you're converting to and the second one is the type of the :class:`Transformer` actually doing the transformation. - During type checking time this is equivalent to :obj:`py:Annotated` so type checkers understand + During type checking time this is equivalent to :obj:`typing.Annotated` so type checkers understand the intent of the code. For example usage, check :class:`Transformer`. @@ -368,7 +367,7 @@ else: """A type annotation that can be applied to a parameter to require a numeric type to fit within the range provided. - During type checking time this is equivalent to :obj:`py:Annotated` so type checkers understand + During type checking time this is equivalent to :obj:`typing.Annotated` so type checkers understand the intent of the code. Some example ranges: diff --git a/discord/app_commands/tree.py b/discord/app_commands/tree.py index 7f96af9fd..d1314987c 100644 --- a/discord/app_commands/tree.py +++ b/discord/app_commands/tree.py @@ -32,7 +32,6 @@ from typing import Callable, Dict, Generic, List, Literal, Optional, TYPE_CHECKI from .namespace import Namespace, ResolveKey from .models import AppCommand from .commands import Command, ContextMenu, Group, _shorten -from .enums import AppCommandType from .errors import ( AppCommandError, CommandAlreadyRegistered, @@ -40,7 +39,7 @@ from .errors import ( CommandSignatureMismatch, ) from ..errors import ClientException -from ..enums import InteractionType +from ..enums import AppCommandType, InteractionType from ..utils import MISSING if TYPE_CHECKING: @@ -60,7 +59,7 @@ class CommandTree(Generic[ClientT]): Parameters ----------- - client: :class:`Client` + client: :class:`~discord.Client` The client instance to get application command information from. """ @@ -91,7 +90,7 @@ class CommandTree(Generic[ClientT]): Parameters ----------- - guild: Optional[:class:`abc.Snowflake`] + guild: Optional[:class:`~discord.abc.Snowflake`] The guild to fetch the commands from. If not passed then global commands are fetched instead. @@ -136,7 +135,7 @@ class CommandTree(Generic[ClientT]): ----------- command: Union[:class:`Command`, :class:`Group`] The application command or group to add. - guild: Optional[:class:`abc.Snowflake`] + guild: Optional[:class:`~discord.abc.Snowflake`] The guild to add the command to. If not given then it becomes a global command instead. override: :class:`bool` @@ -145,7 +144,7 @@ class CommandTree(Generic[ClientT]): Raises -------- - ~discord.CommandAlreadyRegistered + ~discord.app_commands.CommandAlreadyRegistered The command was already registered and no override was specified. TypeError The application command passed is not a valid application command. @@ -240,11 +239,11 @@ class CommandTree(Generic[ClientT]): ----------- command: :class:`str` The name of the root command to remove. - guild: Optional[:class:`abc.Snowflake`] + guild: Optional[:class:`~discord.abc.Snowflake`] The guild to remove the command from. If not given then it removes a global command instead. - type: :class:`AppCommandType` - The type of command to remove. Defaults to :attr:`AppCommandType.chat_input`, + type: :class:`~discord.AppCommandType` + The type of command to remove. Defaults to :attr:`~discord.AppCommandType.chat_input`, i.e. slash commands. Returns @@ -316,11 +315,11 @@ class CommandTree(Generic[ClientT]): ----------- command: :class:`str` The name of the root command to get. - guild: Optional[:class:`abc.Snowflake`] + guild: Optional[:class:`~discord.abc.Snowflake`] The guild to get the command from. If not given then it gets a global command instead. - type: :class:`AppCommandType` - The type of command to get. Defaults to :attr:`AppCommandType.chat_input`, + type: :class:`~discord.AppCommandType` + The type of command to get. Defaults to :attr:`~discord.AppCommandType.chat_input`, i.e. slash commands. Returns @@ -385,8 +384,8 @@ class CommandTree(Generic[ClientT]): guild: Optional[:class:`~discord.abc.Snowflake`] The guild to get the commands from. If not given then it gets all global commands instead. - type: :class:`AppCommandType` - The type of commands to get. Defaults to :attr:`AppCommandType.chat_input`, + type: :class:`~discord.AppCommandType` + The type of commands to get. Defaults to :attr:`~discord.AppCommandType.chat_input`, i.e. slash commands. Returns @@ -473,7 +472,7 @@ class CommandTree(Generic[ClientT]): The description of the application command. This shows up in the UI to describe the application command. If not given, it defaults to the first line of the docstring of the callback shortened to 100 characters. - guild: Optional[:class:`.abc.Snowflake`] + guild: Optional[:class:`~discord.abc.Snowflake`] The guild to add the command to. If not given then it becomes a global command instead. """ @@ -529,7 +528,7 @@ class CommandTree(Generic[ClientT]): The name of the context menu command. If not given, it defaults to a title-case version of the callback name. Note that unlike regular slash commands this can have spaces and upper case characters in the name. - guild: Optional[:class:`.abc.Snowflake`] + guild: Optional[:class:`~discord.abc.Snowflake`] The guild to add the command to. If not given then it becomes a global command instead. """ @@ -569,7 +568,7 @@ class CommandTree(Generic[ClientT]): Returns -------- - List[:class:`~discord.AppCommand`] + List[:class:`AppCommand`] The application's commands that got synced. """ diff --git a/discord/enums.py b/discord/enums.py index 57d343199..f4a2a85cd 100644 --- a/discord/enums.py +++ b/discord/enums.py @@ -60,6 +60,8 @@ __all__ = ( 'Locale', 'EntityType', 'EventStatus', + 'AppCommandType', + 'AppCommandOptionType', ) if TYPE_CHECKING: @@ -655,6 +657,26 @@ class EventStatus(Enum): cancelled = 4 +class AppCommandOptionType(Enum): + subcommand = 1 + subcommand_group = 2 + string = 3 + integer = 4 + boolean = 5 + user = 6 + channel = 7 + role = 8 + mentionable = 9 + number = 10 + attachment = 11 + + +class AppCommandType(Enum): + chat_input = 1 + user = 2 + message = 3 + + def create_unknown_value(cls: Type[E], val: Any) -> E: value_cls = cls._enum_value_cls_ # type: ignore - This is narrowed below name = f'unknown_{val}' diff --git a/docs/api.rst b/docs/api.rst index a3223ce9b..1f342a847 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1463,149 +1463,6 @@ of :class:`enum.Enum`. .. versionadded:: 1.5 -.. class:: InteractionType - - Specifies the type of :class:`Interaction`. - - .. versionadded:: 2.0 - - .. attribute:: ping - - Represents Discord pinging to see if the interaction response server is alive. - .. attribute:: application_command - - Represents a slash command interaction. - .. attribute:: component - - Represents a component based interaction, i.e. using the Discord Bot UI Kit. - .. attribute:: autocomplete - - Represents an auto complete interaction. - .. attribute:: modal_submit - - Represents submission of a modal interaction. - -.. class:: InteractionResponseType - - Specifies the response type for the interaction. - - .. versionadded:: 2.0 - - .. attribute:: pong - - Pongs the interaction when given a ping. - - See also :meth:`InteractionResponse.pong` - .. attribute:: channel_message - - Respond to the interaction with a message. - - See also :meth:`InteractionResponse.send_message` - .. attribute:: deferred_channel_message - - Responds to the interaction with a message at a later time. - - See also :meth:`InteractionResponse.defer` - .. attribute:: deferred_message_update - - Acknowledges the component interaction with a promise that - the message will update later (though there is no need to actually update the message). - - See also :meth:`InteractionResponse.defer` - .. attribute:: message_update - - Responds to the interaction by editing the message. - - See also :meth:`InteractionResponse.edit_message` - .. attribute:: autocomplete_result - - Responds to the autocomplete interaction with suggested choices. - - See also :meth:`InteractionResponse.autocomplete` - .. attribute:: modal - - Responds to the interaction with a modal. - - See also :meth:`InteractionResponse.send_modal` - -.. class:: ComponentType - - Represents the component type of a component. - - .. versionadded:: 2.0 - - .. attribute:: action_row - - Represents the group component which holds different components in a row. - .. attribute:: button - - Represents a button component. - .. attribute:: select - - Represents a select component. - - .. attribute:: text_input - - Represents a text box component. - - -.. class:: ButtonStyle - - Represents the style of the button component. - - .. versionadded:: 2.0 - - .. attribute:: primary - - Represents a blurple button for the primary action. - .. attribute:: secondary - - Represents a grey button for the secondary action. - .. attribute:: success - - Represents a green button for a successful action. - .. attribute:: danger - - Represents a red button for a dangerous action. - .. attribute:: link - - Represents a link button. - - .. attribute:: blurple - - An alias for :attr:`primary`. - .. attribute:: grey - - An alias for :attr:`secondary`. - .. attribute:: gray - - An alias for :attr:`secondary`. - .. attribute:: green - - An alias for :attr:`success`. - .. attribute:: red - - An alias for :attr:`danger`. - .. attribute:: url - - An alias for :attr:`link`. - -.. class:: TextStyle - - Represents the style of the text box component. - - .. versionadded:: 2.0 - - .. attribute:: short - - Represents a short text box. - .. attribute:: paragraph - - Represents a long form text box. - .. attribute:: long - - An alias for :attr:`paragraph`. - .. class:: VerificationLevel Specifies a :class:`Guild`\'s verification level, which is the criteria in @@ -2582,7 +2439,7 @@ of :class:`enum.Enum`. .. attribute:: guild_only - Alias for :attr:`.closed` + The stage instance or scheduled event is only accessible within the guild. .. class:: NSFWLevel @@ -3585,51 +3442,6 @@ Message .. autoclass:: Message() :members: -Component -~~~~~~~~~~ - -.. attributetable:: Component - -.. autoclass:: Component() - :members: - -ActionRow -~~~~~~~~~~ - -.. attributetable:: ActionRow - -.. autoclass:: ActionRow() - :members: - -Button -~~~~~~~ - -.. attributetable:: Button - -.. autoclass:: Button() - :members: - :inherited-members: - -SelectMenu -~~~~~~~~~~~ - -.. attributetable:: SelectMenu - -.. autoclass:: SelectMenu() - :members: - :inherited-members: - - -TextInput -~~~~~~~~~~ - -.. attributetable:: TextInput - -.. autoclass:: TextInput() - :members: - :inherited-members: - - DeletedReferencedMessage ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3698,30 +3510,6 @@ Integration .. autoclass:: StreamIntegration() :members: -Interaction -~~~~~~~~~~~~ - -.. attributetable:: Interaction - -.. autoclass:: Interaction() - :members: - -InteractionResponse -~~~~~~~~~~~~~~~~~~~~ - -.. attributetable:: InteractionResponse - -.. autoclass:: InteractionResponse() - :members: - -InteractionMessage -~~~~~~~~~~~~~~~~~~~ - -.. attributetable:: InteractionMessage - -.. autoclass:: InteractionMessage() - :members: - Member ~~~~~~ @@ -4125,14 +3913,6 @@ PartialMessage .. autoclass:: PartialMessage :members: -SelectOption -~~~~~~~~~~~~~ - -.. attributetable:: SelectOption - -.. autoclass:: SelectOption - :members: - Intents ~~~~~~~~~~ @@ -4261,68 +4041,6 @@ PublicUserFlags .. autoclass:: PublicUserFlags() :members: -.. _discord_ui_kit: - -Bot UI Kit -------------- - -The library has helpers to help create component-based UIs. - -View -~~~~~~~ - -.. attributetable:: discord.ui.View - -.. autoclass:: discord.ui.View - :members: - -Modal -~~~~~~ - -.. attributetable:: discord.ui.Modal - -.. autoclass:: discord.ui.Modal - :members: - -Item -~~~~~~~ - -.. attributetable:: discord.ui.Item - -.. autoclass:: discord.ui.Item - :members: - -Button -~~~~~~~ - -.. attributetable:: discord.ui.Button - -.. autoclass:: discord.ui.Button - :members: - :inherited-members: - -.. autofunction:: discord.ui.button - -Select -~~~~~~~ - -.. attributetable:: discord.ui.Select - -.. autoclass:: discord.ui.Select - :members: - :inherited-members: - -.. autofunction:: discord.ui.select - -TextInput -~~~~~~~~~~ - -.. attributetable:: discord.ui.TextInput - -.. autoclass:: discord.ui.TextInput - :members: - :inherited-members: - Exceptions ------------ diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst index f205be2a3..22e997fa0 100644 --- a/docs/ext/commands/commands.rst +++ b/docs/ext/commands/commands.rst @@ -52,7 +52,7 @@ Essentially, these two are equivalent: :: Since the :meth:`.Bot.command` decorator is shorter and easier to comprehend, it will be the one used throughout the documentation here. -Any parameter that is accepted by the :class:`.Command` constructor can be passed into the decorator. For example, to change +Any parameter that is accepted by the :class:`~discord.ext.commands.Command` constructor can be passed into the decorator. For example, to change the name to something other than the function would be as simple as doing this: .. code-block:: python3 @@ -771,7 +771,7 @@ In order to handle our errors, we must use something called an error handler. Th called for every error reached. Most of the time however, we want to handle an error local to the command itself. Luckily, commands come with local error -handlers that allow us to do just that. First we decorate an error handler function with :meth:`.Command.error`: +handlers that allow us to do just that. First we decorate an error handler function with :meth:`~discord.ext.commands.Command.error`: .. code-block:: python3 diff --git a/docs/index.rst b/docs/index.rst index e1af5163f..28950c836 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -60,6 +60,7 @@ These pages go into great detail about everything the API can do. :maxdepth: 1 api + interactions/api discord.ext.commands API Reference discord.ext.tasks API Reference diff --git a/docs/interactions/api.rst b/docs/interactions/api.rst new file mode 100644 index 000000000..d81ee52dc --- /dev/null +++ b/docs/interactions/api.rst @@ -0,0 +1,533 @@ +.. currentmodule:: discord + +Interactions API Reference +============================ + +The following section outlines the API of interactions, as implemented by the library. + +For documentation about the rest of the library, check :doc:`api`. + +Models +-------- + +Similar to :ref:`discord_api_models`, these are not meant to be constructed by the user. + +Interaction +~~~~~~~~~~~~ + +.. attributetable:: Interaction + +.. autoclass:: Interaction() + :members: + +InteractionResponse +~~~~~~~~~~~~~~~~~~~~ + +.. attributetable:: InteractionResponse + +.. autoclass:: InteractionResponse() + :members: + +InteractionMessage +~~~~~~~~~~~~~~~~~~~ + +.. attributetable:: InteractionMessage + +.. autoclass:: InteractionMessage() + :members: + +Component +~~~~~~~~~~ + +.. attributetable:: Component + +.. autoclass:: Component() + :members: + +ActionRow +~~~~~~~~~~ + +.. attributetable:: ActionRow + +.. autoclass:: ActionRow() + :members: + +Button +~~~~~~~ + +.. attributetable:: Button + +.. autoclass:: Button() + :members: + :inherited-members: + +SelectMenu +~~~~~~~~~~~ + +.. attributetable:: SelectMenu + +.. autoclass:: SelectMenu() + :members: + :inherited-members: + + +TextInput +~~~~~~~~~~ + +.. attributetable:: TextInput + +.. autoclass:: TextInput() + :members: + :inherited-members: + +AppCommand +~~~~~~~~~~~ + +.. attributetable:: discord.app_commands.AppCommand + +.. autoclass:: discord.app_commands.AppCommand() + :members: + +AppCommandGroup +~~~~~~~~~~~~~~~~ + +.. attributetable:: discord.app_commands.AppCommandGroup + +.. autoclass:: discord.app_commands.AppCommandGroup() + :members: + +AppCommandChannel +~~~~~~~~~~~~~~~~~~ + +.. attributetable:: discord.app_commands.AppCommandChannel + +.. autoclass:: discord.app_commands.AppCommandChannel() + :members: + +AppCommandThread +~~~~~~~~~~~~~~~~~ + +.. attributetable:: discord.app_commands.AppCommandThread + +.. autoclass:: discord.app_commands.AppCommandThread() + :members: + +Argument +~~~~~~~~~~ + +.. attributetable:: discord.app_commands.Argument + +.. autoclass:: discord.app_commands.Argument() + :members: + +Data Classes +-------------- + +Similar to :ref:`discord_api_data`, these can be received and constructed by users. + +SelectOption +~~~~~~~~~~~~~ + +.. attributetable:: SelectOption + +.. autoclass:: SelectOption + :members: + +Choice +~~~~~~~ + +.. attributetable:: discord.app_commands.Choice + +.. autoclass:: discord.app_commands.Choice + :members: + + +Enumerations +------------- + +.. class:: InteractionType + + Specifies the type of :class:`Interaction`. + + .. versionadded:: 2.0 + + .. attribute:: ping + + Represents Discord pinging to see if the interaction response server is alive. + .. attribute:: application_command + + Represents a slash command interaction. + .. attribute:: component + + Represents a component based interaction, i.e. using the Discord Bot UI Kit. + .. attribute:: autocomplete + + Represents an auto complete interaction. + .. attribute:: modal_submit + + Represents submission of a modal interaction. + +.. class:: InteractionResponseType + + Specifies the response type for the interaction. + + .. versionadded:: 2.0 + + .. attribute:: pong + + Pongs the interaction when given a ping. + + See also :meth:`InteractionResponse.pong` + .. attribute:: channel_message + + Respond to the interaction with a message. + + See also :meth:`InteractionResponse.send_message` + .. attribute:: deferred_channel_message + + Responds to the interaction with a message at a later time. + + See also :meth:`InteractionResponse.defer` + .. attribute:: deferred_message_update + + Acknowledges the component interaction with a promise that + the message will update later (though there is no need to actually update the message). + + See also :meth:`InteractionResponse.defer` + .. attribute:: message_update + + Responds to the interaction by editing the message. + + See also :meth:`InteractionResponse.edit_message` + .. attribute:: autocomplete_result + + Responds to the autocomplete interaction with suggested choices. + + See also :meth:`InteractionResponse.autocomplete` + .. attribute:: modal + + Responds to the interaction with a modal. + + See also :meth:`InteractionResponse.send_modal` + +.. class:: ComponentType + + Represents the component type of a component. + + .. versionadded:: 2.0 + + .. attribute:: action_row + + Represents the group component which holds different components in a row. + .. attribute:: button + + Represents a button component. + .. attribute:: select + + Represents a select component. + + .. attribute:: text_input + + Represents a text box component. + +.. class:: ButtonStyle + + Represents the style of the button component. + + .. versionadded:: 2.0 + + .. attribute:: primary + + Represents a blurple button for the primary action. + .. attribute:: secondary + + Represents a grey button for the secondary action. + .. attribute:: success + + Represents a green button for a successful action. + .. attribute:: danger + + Represents a red button for a dangerous action. + .. attribute:: link + + Represents a link button. + + .. attribute:: blurple + + An alias for :attr:`primary`. + .. attribute:: grey + + An alias for :attr:`secondary`. + .. attribute:: gray + + An alias for :attr:`secondary`. + .. attribute:: green + + An alias for :attr:`success`. + .. attribute:: red + + An alias for :attr:`danger`. + .. attribute:: url + + An alias for :attr:`link`. + +.. class:: TextStyle + + Represents the style of the text box component. + + .. versionadded:: 2.0 + + .. attribute:: short + + Represents a short text box. + .. attribute:: paragraph + + Represents a long form text box. + .. attribute:: long + + An alias for :attr:`paragraph`. + +.. class:: AppCommandOptionType + + The application command's option type. This is usually the type of parameter an application command takes. + + .. versionadded:: 2.0 + + .. attribute:: subcommand + + A subcommand. + .. attribute:: subcommand_group + + A subcommand group. + .. attribute:: string + + A string parameter. + .. attribute:: integer + + A integer parameter. + .. attribute:: boolean + + A boolean parameter. + .. attribute:: user + + A user parameter. + .. attribute:: channel + + A channel parameter. + .. attribute:: role + + A role parameter. + .. attribute:: mentionable + + A mentionable parameter. + .. attribute:: number + + A number parameter. + .. attribute:: attachment + + An attachment parameter. + +.. class:: AppCommandType + + The type of application command. + + .. versionadded:: 2.0 + + .. attribute:: chat_input + + A slash command. + .. attribute:: user + + A user context menu command. + .. attribute:: message + + A message context menu command. + +.. _discord_ui_kit: + +Bot UI Kit +------------- + +The library has helpers to aid create component-based UIs. These are all in the ``discord.ui`` package. + + +View +~~~~~~~ + +.. attributetable:: discord.ui.View + +.. autoclass:: discord.ui.View + :members: + +Modal +~~~~~~ + +.. attributetable:: discord.ui.Modal + +.. autoclass:: discord.ui.Modal + :members: + +Item +~~~~~~~ + +.. attributetable:: discord.ui.Item + +.. autoclass:: discord.ui.Item + :members: + +Button +~~~~~~~ + +.. attributetable:: discord.ui.Button + +.. autoclass:: discord.ui.Button + :members: + :inherited-members: + +.. autofunction:: discord.ui.button + +Select +~~~~~~~ + +.. attributetable:: discord.ui.Select + +.. autoclass:: discord.ui.Select + :members: + :inherited-members: + +.. autofunction:: discord.ui.select + +TextInput +~~~~~~~~~~ + +.. attributetable:: discord.ui.TextInput + +.. autoclass:: discord.ui.TextInput + :members: + :inherited-members: + +.. _discord_app_commands: + +Application Commands +---------------------- + +The library has helpers to aid in creation of application commands. These are all in the ``discord.app_commands`` package. + +CommandTree +~~~~~~~~~~~~ + +.. attributetable:: discord.app_commands.CommandTree + +.. autoclass:: discord.app_commands.CommandTree + :members: + +Commands +~~~~~~~~~ + +Command +++++++++ + +.. attributetable:: discord.app_commands.Command + +.. autoclass:: discord.app_commands.Command + :members: + +ContextMenu +++++++++++++ + +.. attributetable:: discord.app_commands.ContextMenu + +.. autoclass:: discord.app_commands.ContextMenu + :members: + +Group +++++++ + +.. attributetable:: discord.app_commands.Group + +.. autoclass:: discord.app_commands.Group + :members: + +Decorators ++++++++++++ + +.. autofunction:: discord.app_commands.command + :decorator: + +.. autofunction:: discord.app_commands.context_menu + :decorator: + +.. autofunction:: discord.app_commands.describe + :decorator: + +.. autofunction:: discord.app_commands.choices + :decorator: + +Namespace +~~~~~~~~~~ + +.. attributetable:: discord.app_commands.Namespace + +.. autoclass:: discord.app_commands.Namespace() + :members: + +Transformers +~~~~~~~~~~~~~ + +Transformer +++++++++++++ + +.. attributetable:: discord.app_commands.Transformer + +.. autoclass:: discord.app_commands.Transformer + :members: + +Transform +++++++++++ + +.. attributetable:: discord.app_commands.Transform + +.. autoclass:: discord.app_commands.Transform + :members: + +Range +++++++ + +.. attributetable:: discord.app_commands.Range + +.. autoclass:: discord.app_commands.Range + :members: + +Exceptions +~~~~~~~~~~~ + +.. autoexception:: discord.app_commands.AppCommandError + :members: + +.. autoexception:: discord.app_commands.CommandInvokeError + :members: + +.. autoexception:: discord.app_commands.TransformerError + :members: + +.. autoexception:: discord.app_commands.CommandAlreadyRegistered + :members: + +.. autoexception:: discord.app_commands.CommandSignatureMismatch + :members: + +.. autoexception:: discord.app_commands.CommandNotFound + :members: + +Exception Hierarchy +~~~~~~~~~~~~~~~~~~~~ + +.. exception_hierarchy:: + + - :exc:`~discord.DiscordException` + - :exc:`~discord.app_commands.AppCommandError` + - :exc:`~discord.app_commands.CommandInvokeError` + - :exc:`~discord.app_commands.TransformerError` + - :exc:`~discord.app_commands.CommandAlreadyRegistered` + - :exc:`~discord.app_commands.CommandSignatureMismatch` + - :exc:`~discord.app_commands.CommandNotFound` diff --git a/docs/migrating.rst b/docs/migrating.rst index baf97160f..a6df471a0 100644 --- a/docs/migrating.rst +++ b/docs/migrating.rst @@ -894,8 +894,8 @@ dictionary to a set that does not have aliases. To retrieve the previous diction Command instances have gained new attributes and properties: 1. :attr:`~ext.commands.Command.signature` to get the signature of the command. -2. :attr:`~.Command.usage`, an attribute to override the default signature. -3. :attr:`~.Command.root_parent` to get the root parent group of a subcommand. +2. :attr:`~ext.commands.Command.usage`, an attribute to override the default signature. +3. :attr:`~ext.commands.Command.root_parent` to get the root parent group of a subcommand. For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed: @@ -942,7 +942,7 @@ have been removed. The :class:`~ext.commands.Command` instance was not kept up-t the up to date :class:`~ext.commands.Command` instance, use the :attr:`.Context.command` attribute. -The error handlers, either :meth:`.Command.error` or :func:`.on_command_error`, +The error handlers, either :meth:`~ext.commands.Command.error` or :func:`.on_command_error`, have been re-ordered to use the :class:`~ext.commands.Context` as its first parameter to be consistent with other events and commands.