Document application commands

.gitignore

@@ -15,9 +15,9 @@ docs/crowdin.py
 *.flac
 *.mo
 .idea/
+env/
+.vs/
 .DS_Store
 .python-version
 __pycache__
-.vs/slnx.sqlite
-env/
 build/

README.rst

@@ -123,7 +123,7 @@ Note: Make sure you do not reveal your bot token to anyone, it can grant access
 Links
 -----
 
-- `Documentation <https://docs.pycord.dev/en/master/index.html>`_
+- `Documentation <https://docs.pycord.dev/en/latest/index.html>`_
 - `Our Official Discord Server <https://pycord.dev/discord>`_
 - `Official Discord Developers Server <https://discord.gg/discord-developers>`_
 - `Unofficial Discord API Server <https://discord.gg/discord-api>`_

discord/commands/commands.py

@@ -694,6 +694,15 @@ def __repr__(self):
 
 
 class OptionChoice:
+    r"""Represents an option choice.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The name of the option choice.
+    value: Optional[Union[:class:`str`, :class:`int`, :class:`float`]]
+        The value of the option choice. If ``None`` is passed, this will be set to the name of the option choice.
+    """
     def __init__(self, name: str, value: Optional[Union[str, int, float]] = None):
         self.name = name
         self.value = value or name
@@ -1027,6 +1036,29 @@ def to_dict(self) -> Dict[str, Union[str, int]]:
 
 
 class UserCommand(ContextMenuCommand):
+    r"""A class that implements the protocol for user context menu commands.
+
+    These are not created manually, instead they are created via the
+    decorator or functional interface.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The name of the command.
+    callback: :ref:`coroutine <coroutine>`
+        The coroutine that is executed when the command is called.
+    guild_ids: Optional[List[:class:`int`]]
+        The ids of the guilds where this command will be registered.
+    cog: Optional[:class:`Cog`]
+        The cog that this command belongs to. ``None`` if there isn't one.
+    checks: List[Callable[[:class:`.ApplicationContext`], :class:`bool`]]
+        A list of predicates that verifies if the command could be executed
+        with the given :class:`.ApplicationContext` as the sole parameter. If an exception
+        is necessary to be thrown to signal failure, then one inherited from
+        :exc:`.CommandError` should be used. Note that if the checks fail then
+        :exc:`.CheckFailure` exception is raised to the :func:`.on_application_command_error`
+        event.
+    """
     type = 2
 
     def __new__(cls, *args, **kwargs) -> UserCommand:
@@ -1102,6 +1134,29 @@ def _update_copy(self, kwargs: Dict[str, Any]):
 
 
 class MessageCommand(ContextMenuCommand):
+    r"""A class that implements the protocol for message context menu commands.
+
+    These are not created manually, instead they are created via the
+    decorator or functional interface.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The name of the command.
+    callback: :ref:`coroutine <coroutine>`
+        The coroutine that is executed when the command is called.
+    guild_ids: Optional[List[:class:`int`]]
+        The ids of the guilds where this command will be registered.
+    cog: Optional[:class:`Cog`]
+        The cog that this command belongs to. ``None`` if there isn't one.
+    checks: List[Callable[[:class:`.ApplicationContext`], :class:`bool`]]
+        A list of predicates that verifies if the command could be executed
+        with the given :class:`.ApplicationContext` as the sole parameter. If an exception
+        is necessary to be thrown to signal failure, then one inherited from
+        :exc:`.CommandError` should be used. Note that if the checks fail then
+        :exc:`.CheckFailure` exception is raised to the :func:`.on_application_command_error`
+        event.
+    """
     type = 3
 
     def __new__(cls, *args, **kwargs) -> MessageCommand:

docs/api.rst

@@ -95,9 +95,69 @@ AutoShardedBot
 
 Application Commands
 ---------------------
-.. attributetable:: ApplicationCommandMixin
 
-.. autoclass:: ApplicationCommandMixin
+ApplicationCommand
+~~~~~~~~~~~~~~~~~~~
+
+.. attributetable:: ApplicationCommand
+
+.. autoclass:: ApplicationCommand
+    :members:
+
+SlashCommand
+~~~~~~~~~~~~~
+
+.. attributetable:: SlashCommand
+
+.. autoclass:: SlashCommand
+    :members:
+
+SlashCommandGroup
+~~~~~~~~~~~~~~~~~~
+
+.. attributetable:: SlashCommandGroup
+
+.. autoclass:: SlashCommandGroup
+    :members:
+
+Option
+~~~~~~~
+
+.. attributetable:: Option
+
+.. autoclass:: Option
+    :members:
+
+OptionChoice
+~~~~~~~~~~~~~
+
+.. attributetable:: OptionChoice
+
+.. autoclass:: OptionChoice
+    :members:
+
+UserCommand
+~~~~~~~~~~~~
+
+.. attributetable:: UserCommand
+
+.. autoclass:: UserCommand
+    :members:
+
+MessageCommand
+~~~~~~~~~~~~~~~
+
+.. attributetable:: MessageCommand
+
+.. autoclass:: MessageCommand
+    :members:
+
+ApplicationContext
+~~~~~~~~~~~~~~~~~~~
+
+.. attributetable:: ApplicationContext
+
+.. autoclass:: ApplicationContext
     :members:
 
 Application Info
@@ -1207,6 +1267,43 @@ from being stringly typed in case the strings change in the future.
 All enumerations are subclasses of an internal class which mimics the behaviour
 of :class:`enum.Enum`.
 
+.. class:: SlashCommandOptionType
+
+    Specifies the input type of an option.
+
+    .. versionadded:: 2.0
+
+    .. attribute:: sub_command
+
+        A slash subcommand.
+    .. attribute:: sub_command_group
+
+        A slash command group.
+    .. attribute:: string
+
+        A string.
+    .. attribute:: integer
+
+        An integer.
+    .. attribute:: boolean
+
+        A boolean.
+    .. attribute:: user
+
+        A user from the current channel. This will be converted to an instance of :class:`.User` in private channels, else :class:`.Member`
+    .. attribute:: channel
+
+        A channel from the current guild.
+    .. attribute:: role
+
+        A role from the current guild.
+    .. attribute:: mentionable
+
+        A mentionable (user or role).
+    .. attribute:: number
+
+        A floating number.
+
 .. class:: ChannelType
 
     Specifies the type of channel.
@@ -2650,7 +2747,9 @@ of :class:`enum.Enum`.
 
     .. attribute:: embedded_application
 
-        A stream invite that targets an embedded application.
+        A invite that targets an embedded application.
+
+        Note that your bot won't be verified if you provide users access to this
 
 .. class:: VideoQualityMode
 

docs/application_commands.rst

@@ -0,0 +1,155 @@
+:orphan:
+
+.. currentmodule:: discord
+.. versionadded:: 2.0
+.. _application_commands:
+
+Application Commands
+====================
+
+Application commands are commands that an application can register to Discord. They provide users a way of interacting
+directly with your application that feels deeply integrated into Discord.
+
+Application commands can be used with either :class:`.Bot` or :class:`.ext.commands.Bot`.
+
+.. code-block:: python3
+
+    import discord
+    bot = discord.Bot()
+
+    @bot.command() # creates slash command by default
+    async def foo(ctx, arg):
+        await ctx.respond(arg)
+
+    # or
+
+    from discord.ext import commands
+    bot = commands.Bot()
+
+    @bot.slash_command()
+    async def foo(ctx, arg):
+        await ctx.respond(arg)
+
+Application Command Types
+-------------------------
+
+There are currently three types of application commands: slash, user and message commands.
+
+These have their corresponding decorators.
+
+.. code-block:: python3
+
+    @bot.slash_command()
+    async def foo(ctx):
+        await ctx.respond("Hello world!")
+
+    @bot.user_command()
+    async def bar(ctx, user):
+        await ctx.respond(user.id)
+
+    @bot.message_command()
+    async def foobar(ctx, message):
+        await ctx.respond(message.id)
+
+You can also use the :attr:`.Bot.command` decorator by supplying an application command class.
+
+.. code-block:: python3
+
+    from discord import UserCommand
+
+    @bot.command(..., cls=UserCommand)
+    # is the same as
+    @bot.user_command(...)
+
+Options
+-------
+
+Options are arguments passed into slash commands.
+
+These can be defined as normal function arguments:
+
+.. code-block:: python3
+
+    @bot.slash_command()
+    async def say_hello(ctx, name):
+        await ctx.respond(f"Hello {name}!")
+
+Typehints can be used to set option types. All option types are listed under :class:`.SlashCommandOptionType`.
+
+.. code-block:: python3
+
+    @bot.slash_command()
+    async def foo(ctx, number: int, member: discord.Member):
+        # command code
+
+Option fields can be set using :class:`.Option` as the type of the argument.
+
+.. code-block:: python3
+
+    from discord import Option
+
+    @bot.slash_command()
+    async def show_color(
+        ctx,
+        color: Option(str, "Your color choice", choices=["red", "green"]),
+    ):
+        # command code
+
+Options can also be used with custom converters.
+
+.. code-block:: python3
+
+    from discord.ext.commands import Converter
+
+    class ColorConverter(Converter):
+        async def convert(self, ctx, arg):
+            if arg == "0":
+                return "Black"
+            return arg
+
+    @bot.slash_command()
+    async def show_color(
+        ctx,
+        color: Option(ColorConverter, "Your color choice"),
+    ):
+        # command code
+
+Slash Command Groups
+--------------------
+
+Slash command groups allows grouping multiple subcommands under the same parent.
+
+.. code-block:: python3
+
+    my_group = bot.create_group("name", "description")
+
+To create a subcommand, use the :meth:`.SlashCommandGroup.command` decorator.
+
+.. code-block:: python3
+
+    @foo.command()
+    async def bar(ctx):  # this will show up as "/foo bar"
+
+Slash command groups can also be created by subclassing :class:`.SlashCommandGroup`.
+
+.. code-block:: python3
+
+    from discord import SlashCommandGroup, slash_command
+
+    class Foo(SlashCommandGroup):
+        @slash_command()
+        async def bar(self, ctx):
+            ...
+
+    bot.add_application_command(Foo())
+
+    # or
+
+    @bot.slash_group()
+    class foo(SlashCommandGroup):
+        @slash_command()
+        async def bar(self, ctx):
+            ...
+
+Using Cogs
+----------

docs/discord.rst

@@ -3,7 +3,7 @@
 .. _discord-intro:
 
 Creating a Bot Account
-========================
+======================
 
 In order to work with the library and the Discord API in general, we must first create a Discord Bot account.
 
@@ -57,7 +57,7 @@ And that's it. You now have a bot account and you can login with that token.
 .. _discord_invite_bot:
 
 Inviting Your Bot
--------------------
+-----------------
 
 So you've made a Bot User but it's not actually in any server.