diff --git a/.gitignore b/.gitignore index b13a0aa4bb..220c0a5b3f 100644 --- a/.gitignore +++ b/.gitignore @@ -15,9 +15,9 @@ docs/crowdin.py *.flac *.mo .idea/ +env/ +.vs/ .DS_Store .python-version __pycache__ -.vs/slnx.sqlite -env/ build/ diff --git a/README.rst b/README.rst index 0d815dd67b..7ec730062a 100644 --- a/README.rst +++ b/README.rst @@ -123,7 +123,7 @@ Note: Make sure you do not reveal your bot token to anyone, it can grant access Links ----- -- `Documentation `_ +- `Documentation `_ - `Our Official Discord Server `_ - `Official Discord Developers Server `_ - `Unofficial Discord API Server `_ diff --git a/discord/commands/commands.py b/discord/commands/commands.py index 1b1b80359d..bb415d440f 100644 --- a/discord/commands/commands.py +++ b/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 ` + 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 ` + 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: diff --git a/docs/api.rst b/docs/api.rst index 812d35f64a..430d2a2771 100644 --- a/docs/api.rst +++ b/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 diff --git a/docs/application_commands.rst b/docs/application_commands.rst new file mode 100644 index 0000000000..5a1723602d --- /dev/null +++ b/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 +---------- \ No newline at end of file diff --git a/docs/discord.rst b/docs/discord.rst index 63f13cccf8..4784806bec 100644 --- a/docs/discord.rst +++ b/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. diff --git a/setup.py b/setup.py index a52f7dca51..992dd6e317 100644 --- a/setup.py +++ b/setup.py @@ -70,9 +70,9 @@ setup( name="py-cord", author="Pycord Development", - url="https://github.com/Pycord-Development/pycord", + url="https://pycord.dev/github", project_urls={ - "Documentation": "https://pycord.readthedocs.io/en/latest/", + "Documentation": "https://docs.pycord.dev/en/latest/", "Issue tracker": "https://github.com/Pycord-Development/pycord/issues", }, version=version,