feat!: Implement barebones v2 permissions. (#765)

FayeDel · web-flow · commit fe970fab7fbd · 2022-05-05T13:39:11.000-04:00
* feat!: Implement barebones v2 permissions.

* docs: Fix command decor typos.

* fix: Add _client slot to ApplicationCommandPermissions object.

* fix: Remove API-removed attribute to the ApplicationCommand model.

* docs: Document how to use v2 permissions in quickstart.rst

* docs: Fix sentence clarification.

* docs: Fix RST note display.

* fix(http): Adjust endpoints for v2 permissions.

* refactor: Remove associated endpoint header from last commit.

* docs: Fix param/type in documentation.
diff --git a/docs/locale/de/LC_MESSAGES/api.http.po b/docs/locale/de/LC_MESSAGES/api.http.po
@@ -447,7 +447,7 @@ msgstr ""
 #: interactions.api.http.HTTPClient.create_guild_from_guild_template:4
 #: interactions.api.http.HTTPClient.get_channel_messages:4
 #: interactions.api.http.HTTPClient.modify_guild:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.modify_guild:4 of
@@ -514,7 +514,7 @@ msgid "Guild Widget contents as a dict: {\"enabled\":bool, \"channel_id\": str}"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:1 of
-msgid "Get a url representing a png image widget for the guild. ..note::"
+msgid "Get a url representing a png image widget for the guild. .. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:6 of
diff --git a/docs/locale/de/LC_MESSAGES/api.models.channel.po b/docs/locale/de/LC_MESSAGES/api.models.channel.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the type of channels."
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:4 of
diff --git a/docs/locale/de/LC_MESSAGES/api.models.guild.po b/docs/locale/de/LC_MESSAGES/api.models.guild.po
@@ -318,7 +318,7 @@ msgid "A model representing the preview of a guild."
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
diff --git a/docs/locale/de/LC_MESSAGES/api.models.message.po b/docs/locale/de/LC_MESSAGES/api.models.message.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the types of messages."
 msgstr ""
 
 #: interactions.api.models.message.MessageType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.message.MessageType:4 of
diff --git a/docs/locale/fr/LC_MESSAGES/api.http.po b/docs/locale/fr/LC_MESSAGES/api.http.po
@@ -447,7 +447,7 @@ msgstr ""
 #: interactions.api.http.HTTPClient.create_guild_from_guild_template:4
 #: interactions.api.http.HTTPClient.get_channel_messages:4
 #: interactions.api.http.HTTPClient.modify_guild:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.modify_guild:4 of
@@ -514,7 +514,7 @@ msgid "Guild Widget contents as a dict: {\"enabled\":bool, \"channel_id\": str}"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:1 of
-msgid "Get a url representing a png image widget for the guild. ..note::"
+msgid "Get a url representing a png image widget for the guild. .. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:6 of
diff --git a/docs/locale/fr/LC_MESSAGES/api.models.channel.po b/docs/locale/fr/LC_MESSAGES/api.models.channel.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the type of channels."
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:4 of
diff --git a/docs/locale/fr/LC_MESSAGES/api.models.guild.po b/docs/locale/fr/LC_MESSAGES/api.models.guild.po
@@ -318,7 +318,7 @@ msgid "A model representing the preview of a guild."
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
diff --git a/docs/locale/fr/LC_MESSAGES/api.models.message.po b/docs/locale/fr/LC_MESSAGES/api.models.message.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the types of messages."
 msgstr ""
 
 #: interactions.api.models.message.MessageType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.message.MessageType:4 of
diff --git a/docs/locale/hi/LC_MESSAGES/api.http.po b/docs/locale/hi/LC_MESSAGES/api.http.po
@@ -447,7 +447,7 @@ msgstr ""
 #: interactions.api.http.HTTPClient.create_guild_from_guild_template:4
 #: interactions.api.http.HTTPClient.get_channel_messages:4
 #: interactions.api.http.HTTPClient.modify_guild:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.modify_guild:4 of
@@ -514,7 +514,7 @@ msgid "Guild Widget contents as a dict: {\"enabled\":bool, \"channel_id\": str}"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:1 of
-msgid "Get a url representing a png image widget for the guild. ..note::"
+msgid "Get a url representing a png image widget for the guild. .. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:6 of
diff --git a/docs/locale/hi/LC_MESSAGES/api.models.channel.po b/docs/locale/hi/LC_MESSAGES/api.models.channel.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the type of channels."
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:4 of
diff --git a/docs/locale/hi/LC_MESSAGES/api.models.guild.po b/docs/locale/hi/LC_MESSAGES/api.models.guild.po
@@ -318,7 +318,7 @@ msgid "A model representing the preview of a guild."
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
diff --git a/docs/locale/hi/LC_MESSAGES/api.models.message.po b/docs/locale/hi/LC_MESSAGES/api.models.message.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the types of messages."
 msgstr ""
 
 #: interactions.api.models.message.MessageType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.message.MessageType:4 of
diff --git a/docs/locale/it/LC_MESSAGES/api.http.po b/docs/locale/it/LC_MESSAGES/api.http.po
@@ -447,7 +447,7 @@ msgstr ""
 #: interactions.api.http.HTTPClient.create_guild_from_guild_template:4
 #: interactions.api.http.HTTPClient.get_channel_messages:4
 #: interactions.api.http.HTTPClient.modify_guild:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.modify_guild:4 of
@@ -514,7 +514,7 @@ msgid "Guild Widget contents as a dict: {\"enabled\":bool, \"channel_id\": str}"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:1 of
-msgid "Get a url representing a png image widget for the guild. ..note::"
+msgid "Get a url representing a png image widget for the guild. .. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:6 of
diff --git a/docs/locale/it/LC_MESSAGES/api.models.channel.po b/docs/locale/it/LC_MESSAGES/api.models.channel.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the type of channels."
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:4 of
diff --git a/docs/locale/it/LC_MESSAGES/api.models.guild.po b/docs/locale/it/LC_MESSAGES/api.models.guild.po
@@ -318,7 +318,7 @@ msgid "A model representing the preview of a guild."
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
diff --git a/docs/locale/it/LC_MESSAGES/api.models.message.po b/docs/locale/it/LC_MESSAGES/api.models.message.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the types of messages."
 msgstr ""
 
 #: interactions.api.models.message.MessageType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.message.MessageType:4 of
diff --git a/docs/locale/pl/LC_MESSAGES/api.http.po b/docs/locale/pl/LC_MESSAGES/api.http.po
@@ -447,7 +447,7 @@ msgstr ""
 #: interactions.api.http.HTTPClient.create_guild_from_guild_template:4
 #: interactions.api.http.HTTPClient.get_channel_messages:4
 #: interactions.api.http.HTTPClient.modify_guild:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.modify_guild:4 of
@@ -514,7 +514,7 @@ msgid "Guild Widget contents as a dict: {\"enabled\":bool, \"channel_id\": str}"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:1 of
-msgid "Get a url representing a png image widget for the guild. ..note::"
+msgid "Get a url representing a png image widget for the guild. .. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:6 of
diff --git a/docs/locale/pl/LC_MESSAGES/api.models.channel.po b/docs/locale/pl/LC_MESSAGES/api.models.channel.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the type of channels."
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:4 of
diff --git a/docs/locale/pl/LC_MESSAGES/api.models.guild.po b/docs/locale/pl/LC_MESSAGES/api.models.guild.po
@@ -318,7 +318,7 @@ msgid "A model representing the preview of a guild."
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
diff --git a/docs/locale/pl/LC_MESSAGES/api.models.message.po b/docs/locale/pl/LC_MESSAGES/api.models.message.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the types of messages."
 msgstr ""
 
 #: interactions.api.models.message.MessageType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.message.MessageType:4 of
diff --git a/docs/locale/ru/LC_MESSAGES/api.http.po b/docs/locale/ru/LC_MESSAGES/api.http.po
@@ -447,7 +447,7 @@ msgstr ""
 #: interactions.api.http.HTTPClient.create_guild_from_guild_template:4
 #: interactions.api.http.HTTPClient.get_channel_messages:4
 #: interactions.api.http.HTTPClient.modify_guild:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.modify_guild:4 of
@@ -514,7 +514,7 @@ msgid "Guild Widget contents as a dict: {\"enabled\":bool, \"channel_id\": str}"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:1 of
-msgid "Get a url representing a png image widget for the guild. ..note::"
+msgid "Get a url representing a png image widget for the guild. .. note::"
 msgstr ""
 
 #: interactions.api.http.HTTPClient.get_guild_widget_image:6 of
diff --git a/docs/locale/ru/LC_MESSAGES/api.models.channel.po b/docs/locale/ru/LC_MESSAGES/api.models.channel.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the type of channels."
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.channel.ChannelType:4 of
diff --git a/docs/locale/ru/LC_MESSAGES/api.models.guild.po b/docs/locale/ru/LC_MESSAGES/api.models.guild.po
@@ -318,7 +318,7 @@ msgid "A model representing the preview of a guild."
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.guild.GuildPreview:4 of
diff --git a/docs/locale/ru/LC_MESSAGES/api.models.message.po b/docs/locale/ru/LC_MESSAGES/api.models.message.po
@@ -27,7 +27,7 @@ msgid "An enumerable object representing the types of messages."
 msgstr ""
 
 #: interactions.api.models.message.MessageType:3 of
-msgid "..note::"
+msgid ".. note::"
 msgstr ""
 
 #: interactions.api.models.message.MessageType:4 of
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -384,6 +384,69 @@ Responding to a Modal interaction
 
 You can respond to a modal the same way as you would respond to a normal ``chat-input`` command, except your function has an extra argument for the text what was put into the modal.
 
+Adding v2 Permissions
+^^^^^^^^^^^^^^^^^^^^^
+
+v2 permissions consist of the ``default_member_permissions`` and ``dm_permission`` keyword arguments.
+Similar to adding privileged intents, you add permissions (like admin-only, ``BAN_MEMBERS``-only, etc.) as follows:
+
+.. code-block:: python
+
+    @bot.command(
+        name="sudo",
+        description="Fake a command as if its done by someone else.",
+        default_member_permissions=interactions.Permissions.ADMINISTRATOR,  # admin-only
+        options=[interactions.Option(
+                        name="response",
+                        description="What command you want to execute",
+                        type=interactions.OptionType.STRING,
+                        required=True,
+                    )]
+    )
+    async def sudo(ctx, response: str):
+        await ctx.send(f"You wrote: {response}", ephemeral=True)
+
+    # This is the same command however, the below example covers more than 1 permission.
+
+    @bot.command(
+        name="sudo",
+        description="Fake a command as if its done by someone else.",
+        default_member_permissions=interactions.Permissions.ADMINISTRATOR | interactions.Permissions.MOVE_MEMBERS,
+        options=[interactions.Option(
+                        name="response",
+                        description="What command you want to execute",
+                        type=interactions.OptionType.STRING,
+                        required=True,
+                    )]
+    )
+    async def sudo(ctx, response: str):
+        await ctx.send(f"You wrote: {response}", ephemeral=True)
+
+    # Just a disclaimer, these examples are not meant to be used line by line because
+    # you can't have more than 1 global command with the same name
+
+
+Adding guild-only commands is easier as the only thing it takes is a boolean.
+Here's an example of a guild-only command:
+
+.. code-block:: python
+
+    @bot.command(
+        name="sudo",
+        description="Fake a command as if its done by someone else.",
+        dm_permission=False,  # Guild-only
+        options=[interactions.Option(
+                        name="response",
+                        description="What command you want to execute",
+                        type=interactions.OptionType.STRING,
+                        required=True,
+                    )]
+    )
+    async def sudo(ctx, response: str):
+        await ctx.send(f"You wrote: {response}", ephemeral=True)
+
+Likewise, setting ``dm_permission`` to ``True`` makes it usable in DMs. Just to note that this argument's mainly used for
+global commands. Guild commands with this argument will have no effect.
 
 .. _Client: https://discord-interactions.rtfd.io/en/stable/client.html
 .. _find these component types: https://discord-interactions.readthedocs.io/en/stable/models.component.html
diff --git a/interactions/api/http/channel.py b/interactions/api/http/channel.py
@@ -48,7 +48,7 @@ async def get_channel_messages(
         """
         Get messages from a channel.
 
-        ..note::
+        .. note::
             around, before, and after arguments are mutually exclusive.
 
         :param channel_id: Channel ID snowflake.
@@ -94,7 +94,7 @@ async def create_channel(
         """
         Creates a channel within a guild.
 
-        ..note::
+        .. note::
             This does not handle payload in this method. Tread carefully.
 
         :param guild_id: Guild ID snowflake.
@@ -168,7 +168,7 @@ async def create_channel_invite(
         """
         Creates an invite for the given channel.
 
-        ..note::
+        .. note::
             This method does not handle payload. It just sends it.
 
         :param channel_id: Channel ID snowflake.
@@ -233,7 +233,7 @@ async def trigger_typing(self, channel_id: int) -> None:
         """
         Posts "... is typing" in a given channel.
 
-        ..note:
+        .. note::
             By default, this lib doesn't use this endpoint, however, this is listed for third-party implementation.
 
         :param channel_id: Channel ID snowflake.
diff --git a/interactions/api/http/guild.py b/interactions/api/http/guild.py
@@ -111,7 +111,7 @@ async def get_guild_widget_image(self, guild_id: int, style: Optional[str] = Non
         """
         Get an url representing a png image widget for the guild.
 
-        ..note::
+        .. note::
             See _<https://discord.com/developers/docs/resources/guild#get-guild-widget-image> for list of styles.
 
         :param guild_id: Guild ID snowflake.
@@ -259,7 +259,7 @@ async def create_guild_from_guild_template(
         """
         Create a new guild based on a template.
 
-        ..note::
+        .. note::
             This endpoint can only be used by bots in less than 10 guilds.
 
         :param template_code: The code of the template to use.
diff --git a/interactions/api/http/interaction.py b/interactions/api/http/interaction.py
diff --git a/interactions/api/http/interaction.pyi b/interactions/api/http/interaction.pyi
diff --git a/interactions/api/models/gw.py b/interactions/api/models/gw.py
diff --git a/interactions/api/models/gw.pyi b/interactions/api/models/gw.pyi
diff --git a/interactions/client/bot.py b/interactions/client/bot.py
diff --git a/interactions/client/bot.pyi b/interactions/client/bot.pyi
diff --git a/interactions/client/decor.py b/interactions/client/decor.py
diff --git a/interactions/client/decor.pyi b/interactions/client/decor.pyi
diff --git a/interactions/client/models/command.py b/interactions/client/models/command.py
