Reorganise documentation for interactions

This commit is contained in:
Rapptz
2022-03-04 21:07:05 -05:00
parent 41f2792ed9
commit aa74238053
14 changed files with 628 additions and 410 deletions

View File

@ -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
------------

View File

@ -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

View File

@ -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 <ext/commands/api.rst>
discord.ext.tasks API Reference <ext/tasks/index.rst>

533
docs/interactions/api.rst Normal file
View File

@ -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`

View File

@ -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.