Merge branch 'unstable' into rate_limit_per_user

Signed-off-by: LordOfPolls <dev@lordofpolls.com>

Author: LordOfPolls

docs/src/Guides/01 Getting Started.md

@@ -9,102 +9,73 @@ Ready to get your Python on and create a Discord bot? This guide's got you cover
 - [x] [A bot account](02 Creating Your Bot.md)
 - [ ] An aversion to puns
 
-## Installation Methods
+## Installing and Setting up a Bot
 
-There are two different ways to install this library and create your bot.
+### Virtual Environments
 
-=== "Using a Template"
+We strongly recommend that you make use of Virtual Environments when working on any project.
+This means that each project will have its own libraries of any version and does not affect anything else on your system.
+Don't worry, this isn't setting up a full-fledged virtual machine, just small python environment.
 
-    We created a [cookiecutter template](https://github.com/Discord-Snake-Pit/Bot-Template) which you can use to set up your own bot faster.
-    With the template, your code will already have a well-defined structure which will make development easier for you.
-
-    We recommend newer devs to make use of this template.
-
-    ### Template Feature
-    - Basic, ready to go bot
-    - Implementation of best practises
-    - General extensibility
-    - Example command, context menu, component, and event
-    - Logging to both console and file
-    - Pip and poetry config
-    - Pre-commit config
-    - Dockerfile and pre-made docker-compose
-
-    ### Template Installation
-    1. Install cookiecutter - `pip install cookiecutter`
-    2. Set up the template - `cookiecutter https://github.com/Discord-Snake-Pit/Bot-Template`
-
-    And that's it!
-
-    More information can be found [here](https://github.com/Discord-Snake-Pit/Bot-Template).
-
-
-=== "Manual Installation"
-
-    ### Virtual-Environments
-
-    We strongly recommend that you make use of Virtual Environments when working on any project.
-    This means that each project will have its own libraries of any version and does not affect anything else on your system.
-    Don't worry, this isn't setting up a full-fledged virtual machine, just small python environment.
-
-    === ":material-linux: Linux"
-        ```shell
-        cd "[your bots directory]"
-        python3 -m venv venv
-        source venv/bin/activate
-        ```
+=== ":material-linux: Linux"
+    ```shell
+    cd "[your bots directory]"
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
 
-    === ":material-microsoft-windows: Windows"
-        ```shell
-        cd "[your bots directory]"
-        py -3 -m venv venv
-        venv/Scripts/activate
-        ```
+=== ":material-microsoft-windows: Windows"
+    ```shell
+    cd "[your bots directory]"
+    py -3 -m venv venv
+    venv/Scripts/activate
+    ```
 
-    It's that simple, now you're using a virtual environment. If you want to leave the environment just type `deactivate`.
-    If you want to learn more about the virtual environments, check out [this page](https://docs.python.org/3/tutorial/venv.html)
+It's that simple, now you're using a virtual environment. If you want to leave the environment just type `deactivate`.
+If you want to learn more about the virtual environments, check out [this page](https://docs.python.org/3/tutorial/venv.html)
 
-    ### Pip install
+### Pip install
 
-    Now let's get the library installed.
+Now let's get the library installed.
 
-    === ":material-linux: Linux"
-        ```shell
-        python3 -m pip install discord-py-interactions --upgrade
-        ```
+=== ":material-linux: Linux"
+    ```shell
+    python3 -m pip install discord-py-interactions --upgrade
+    ```
 
-    === ":material-microsoft-windows: Windows"
-        ```shell
-        py -3 -m pip install discord-py-interactions --upgrade
-        ```
+=== ":material-microsoft-windows: Windows"
+    ```shell
+    py -3 -m pip install discord-py-interactions --upgrade
+    ```
 
-    ### Basic bot
+### Basic bot
 
-    Now let's get a basic bot going, for your code, you'll want something like this:
+!!! note
+    This is a very basic bot. For a more detailed example/template bot that demonstrates many parts of interactions.py, see [the boilerplate repository.](https://github.com/interactions-py/boilerplate)
 
-    ```python
-    from interactions import Client, Intents, listen
+Now let's get a basic bot going, for your code, you'll want something like this:
 
-    bot = Client(intents=Intents.DEFAULT)
-    # intents are what events we want to receive from discord, `DEFAULT` is usually fine
+```python
+from interactions import Client, Intents, listen
 
-    @listen()  # this decorator tells snek that it needs to listen for the corresponding event, and run this coroutine
-    async def on_ready():
-        # This event is called when the bot is ready to respond to commands
-        print("Ready")
-        print(f"This bot is owned by {bot.owner}")
+bot = Client(intents=Intents.DEFAULT)
+# intents are what events we want to receive from discord, `DEFAULT` is usually fine
 
+@listen()  # this decorator tells snek that it needs to listen for the corresponding event, and run this coroutine
+async def on_ready():
+    # This event is called when the bot is ready to respond to commands
+    print("Ready")
+    print(f"This bot is owned by {bot.owner}")
 
-    @listen()
-    async def on_message_create(event):
-        # This event is called when a message is sent in a channel the bot can see
-        print(f"message received: {event.message.content}")
 
+@listen()
+async def on_message_create(event):
+    # This event is called when a message is sent in a channel the bot can see
+    print(f"message received: {event.message.content}")
 
-    bot.start("Put your token here")
-    ```
 
----
+bot.start("Put your token here")
+```
 
 Congratulations! You now have a basic understanding of this library.
 If you have any questions check out our other guides, or join the

docs/src/Guides/26 Prefixed Commands.md

@@ -100,45 +100,65 @@ async def test(ctx: PrefixedContext, arg1, arg2):
 
 ![Two Parameters](../images/PrefixedCommands/TwoParams.png "The above running with the arguments: one two")
 
-### Variable and Keyword-Only Arguments
+### Variable and Consume Rest Arguments
 
 There may be times where you wish for an argument to be able to have multiple words without wrapping them in quotes. There are two ways of approaching this.
 
 #### Variable
 
 If you wish to get a list (or more specifically, a tuple) of words for one argument, or simply want an undetermined amount of arguments for a command, then you should use a *variable* argument:
-```python
-@prefixed_command()
-async def test(ctx: PrefixedContext, *args):
-    await ctx.reply(f"{len(args)} arguments: {', '.join(args)}")
-```
+
+=== ":one: Tuple Argument"
+    ```python
+    @prefixed_command()
+    async def test(ctx: PrefixedContext, args: tuple[str, ...]):
+        await ctx.reply(f"{len(args)} arguments: {', '.join(args)}")
+    ```
+
+=== ":two: Variable Positional Argument"
+    ```python
+    @prefixed_command()
+    async def test(ctx: PrefixedContext, *args):
+        await ctx.reply(f"{len(args)} arguments: {', '.join(args)}")
+    ```
 
 The result looks something like this:
 
 ![Variable Parameter](../images/PrefixedCommands/VariableParam.png "The above running with the arguments: hello there world "how are you?"")
 
 Notice how the quoted words are still parsed as one argument in the tuple.
 
-#### Keyword-Only
+#### Consume Rest
 
-If you simply wish to take in the rest of the user's input as an argument, you can use a keyword-only argument, like so:
-```python
-@prefixed_command()
-async def test(ctx: PrefixedContext, *, arg):
-    await ctx.reply(arg)
-```
+If you simply wish to take in the rest of the user's input as an argument, you can use a consume rest argument, like so:
+
+=== ":one: ConsumeRest Alias"
+    ```python
+    from interactions import ConsumeRest
+
+    @prefixed_command()
+    async def test(ctx: PrefixedContext, arg: ConsumeRest[str]):
+        await ctx.reply(arg)
+    ```
+
+=== ":two: Keyword-only Argument"
+    ```python
+    @prefixed_command()
+    async def test(ctx: PrefixedContext, *, arg):
+        await ctx.reply(arg)
+    ```
 
 The result looks like this:
 
-![Keyword-Only Parameter](../images/PrefixedCommands/KeywordParam.png "The above running with the arguments: hello world!")
+![Consume Rest Parameter](../images/PrefixedCommands/ConsumeRestParam.png "The above running with the arguments: hello world!")
 
 ???+ note "Quotes"
-    If a user passes quotes into a keyword-only argument, then the resulting argument will have said quotes.
+    If a user passes quotes into consume rest argument, then the resulting argument will have said quotes.
 
-    ![Keyword-Only Quotes](../images/PrefixedCommands/KeywordParamWithQuotes.png "The above running with the arguments: "hello world!"")
+    ![Consume Rest Quotes](../images/PrefixedCommands/ConsumeRestWithQuotes.png "The above running with the arguments: "hello world!"")
 
 !!! warning "Parser ambiguities"
-    Due to parser ambiguities, you can *only* have either a single variable or keyword-only/consume rest argument.
+    Due to parser ambiguities, you can *only* have either a single variable or consume rest argument.
 
 ## Typehinting and Converters
 

docs/src/images/PrefixedCommands/KeywordParam.png renamed to docs/src/images/PrefixedCommands/ConsumeRestParam.png

@@ -103,6 +103,7 @@
     ComponentCommand,
     ComponentContext,
     ComponentType,
+    ConsumeRest,
     context_menu,
     ContextMenu,
     ContextMenuContext,
@@ -338,6 +339,7 @@
     ExponentialBackoffSystem,
     LeakyBucketSystem,
     TokenBucketSystem,
+    ForumSortOrder,
 )
 from .api import events
 from . import ext
@@ -413,6 +415,7 @@
     "ComponentCommand",
     "ComponentContext",
     "ComponentType",
+    "ConsumeRest",
     "const",
     "context_menu",
     "CONTEXT_MENU_NAME_LENGTH",
@@ -458,6 +461,7 @@
     "File",
     "FlatUIColors",
     "FlatUIColours",
+    "ForumSortOrder",
     "ForumLayoutType",
     "get_components_ids",
     "get_logger",

docs/src/images/PrefixedCommands/KeywordParamWithQuotes.png renamed to docs/src/images/PrefixedCommands/ConsumeRestWithQuotes.png

@@ -142,6 +142,7 @@ class AutoModDeleted(AutoModCreated):
 
 @attrs.define(eq=False, order=False, hash=False, kw_only=False)
 class ApplicationCommandPermissionsUpdate(BaseEvent):
+    id: "Snowflake_Type" = attrs.field(repr=False, metadata=docs("The ID of the command permissions were updated for"))
     guild_id: "Snowflake_Type" = attrs.field(
         repr=False, metadata=docs("The guild the command permissions were updated in")
     )

interactions/__init__.py

@@ -1,11 +1,12 @@
 import asyncio
 import inspect
-from typing import Any, Callable, List, Optional, Union, TYPE_CHECKING, Awaitable
+from typing import Any, Callable, List, Optional, Union, TYPE_CHECKING, Awaitable, Annotated, get_origin, get_args
 
 import attrs
 from interactions import (
     BaseContext,
     Converter,
+    ConsumeRest,
     NoArgumentConverter,
     Attachment,
     SlashCommandChoice,
@@ -31,7 +32,7 @@
 from interactions.client.utils.misc_utils import maybe_coroutine, get_object_name
 from interactions.client.errors import BadArgument
 from interactions.ext.prefixed_commands import PrefixedCommand, PrefixedContext
-from interactions.models.internal.converters import _LiteralConverter
+from interactions.models.internal.converters import _LiteralConverter, CONSUME_REST_MARKER
 from interactions.models.internal.checks import guild_only
 
 if TYPE_CHECKING:
@@ -355,12 +356,24 @@ def slash_to_prefixed(cmd: HybridSlashCommand) -> _HybridToPrefixedCommand:  # n
         default = inspect.Parameter.empty
         kind = inspect.Parameter.POSITIONAL_ONLY if cmd._uses_arg else inspect.Parameter.POSITIONAL_OR_KEYWORD
 
+        consume_rest: bool = False
+
         if slash_param := cmd.parameters.get(name):
             kind = slash_param.kind
 
             if kind == inspect.Parameter.KEYWORD_ONLY:  # work around prefixed cmd parsing
                 kind = inspect.Parameter.POSITIONAL_OR_KEYWORD
 
+            # here come the hacks - these allow ConsumeRest (the class) to be passed through
+            if get_origin(slash_param.type) == Annotated:
+                args = get_args(slash_param.type)
+                # ComsumeRest[str] or Annotated[ConsumeRest[str], Converter] support
+                # by all means, the second isn't allowed in prefixed commands, but we'll ignore that for converter support for slash cmds
+                if args[1] is CONSUME_REST_MARKER or (
+                    args[0] == Annotated and get_args(args[0])[1] is CONSUME_REST_MARKER
+                ):
+                    consume_rest = True
+
             if slash_param.converter:
                 annotation = slash_param.converter
             if slash_param.default is not MISSING:
@@ -387,6 +400,9 @@ def slash_to_prefixed(cmd: HybridSlashCommand) -> _HybridToPrefixedCommand:  # n
         if not option.required and default == inspect.Parameter.empty:
             default = None
 
+        if consume_rest:
+            annotation = ConsumeRest[annotation]
+
         actual_param = inspect.Parameter(
             name=name,
             kind=kind,