feat: merge enhanced (#895)

* feat: new Command object
There are still countless TODOs, this is a progress commit

* fix: import error

* feat: option decorator
btw i havent tested any of these

* fix: attempt to fix circular import

* fix: circular import

* refactor: replace errors with LibraryException

* refactor: few small refactors

* refactor: test

* feat: implement Command obj in decorators
I still haven't tested these btw

* feat: working subcommand system
Have not made it work in extensions yet

* feat: more customizable subcommand system

* feat: working Command system in Extensions

* refactor: add a TODO

* refactor: tidy up the code, improve coro calling

* refactor: rename Command.base to Command.name

* feat: better group behavior

* refactor: replace a few more base= with name=, tidy up code

* refactor: remove client field from Command and properly teardown commands

* refactor: different method of looping

* feat: implement default_scope functionality

* refactor: remove options param from Command.group()

* refactor: make autocomplete work, change typehints, make user and message command rely on command, properly sync Command objects inside Extensions

* feat: implement autodefer and spread_to_rows
These are put in a new utils.py file

* fix: commands and autocomplete with self not passed when inside Extensions

* style: add typehints

* refactor: tweak default scope setting

* docs: some docstrings filled in

* docs: more docstrings, organization of code

* refactor: move resolving commands outside of __sync

* refactor: change __all__ from list to tuple

* fix: subcommands error with variables

* fix: incorrect error

* docs: utils.py docstrings

* feat: new way of creating an ActionRow (pun intended)

* refactor: make option decorator better

* refactor: change Command.self to Command.extension

* docs: fix incorrect typehint

* docs: modify docstring

* docs: new docs page

* docs: add doc file

* docs: move line

* docs: modify docstring of spread_to_rows

* refactor: rename variables

* feat: implement Command.error decorator

* fix: typehint

* docs: attempt to fix parameters of Client docstring

* ci: correct from checks.

* docs: fix docstring

* style: delete a blank line

* docs: update quickstart

* ci: correct from checks.

* docs: modify quickstart

* docs: document new features

* docs: testing

* docs: testing

* docs: make it look good

* docs: fix formatting

* docs: add migration docs

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Toricane

docs/migration.rst

@@ -62,3 +62,116 @@ portal and add the intent to your current intents when connecting:
     from interactions import Client, Intents
 
     bot = Client("TOKEN", intents=Intents.DEFAULT | Intents.GUILD_MESSAGE_CONTENT)
+
+4.1.0 → 4.3.0
+~~~~~~~~~~~~~~~
+
+``4.3.0`` introduces a new method of creating commands, subcommands, and options.
+There are also numerous new features, such as a default scope and utilities.
+
+The following example shows and explains how to create commands effortlessly and use new features mentioned above:
+
+.. code-block:: python
+
+    import interactions
+
+    bot = interactions.Client("TOKEN", default_scope=1234567890)
+    # the default scope will be applied to all commands except for those
+    # that disable the feature in the command decorator via: `default_scope=False`
+
+    @bot.command()
+    async def command_name(ctx):
+        """Command description"""
+        ...  # do something here.
+        # the name of the command is the coroutine name.
+        # the description is the first line of the docstring or "No description set".
+
+    @bot.command(default_scope=False)
+    @interactions.option(str, name="opt1")  # description is optional.
+    @interactions.option(4, name="opt2", description="This is an option.")
+    @interactions.option(interactions.Channel, name="opt3", required=True)
+    async def command_with_options(
+        ctx, opt1: str, opt2, int, opt3: interactions.Channel = None
+    ):
+        ...  # do something here.
+        # the default scope is disabled for this command, so this is a global command.
+        # the option type is positional only, and can be a python type, an integer,
+        # or supported interactions.py objects.
+        # all other options are keyword only arguments.
+        # the type amd name of the option are required, the rest are optional.
+
+    # Subcommand system:
+    @bot.command()
+    async def base_command(ctx):
+        ...  # do something here.
+        # this is the base command of the subcommand system.
+
+    @base_command.subcommand()
+    async def subcommand1(ctx, base_res: interactions.BaseResult):
+        ...  # do something here.
+        # this is a subcommand of the base command.
+        # the base result is the result of the base command, it is optional to have.
+        # /base_command subcommand1
+
+    # create subcommands *before* creating groups!
+
+    @base_command.group()
+    async def group1(ctx, base_res: interactions.BaseResult):
+        ...  # do something here.
+        # this symbolizes a group for subcommands.
+
+    @group.subcommand()
+    async def subcommand2(ctx, group_res: interactions.GroupResult):
+        raise Exception("pretend an error happened here")
+        # this is a subcommand of the group.
+        # the group result is the result of the group, it is optional to have.
+        # /base_command group1 subcommand2
+
+    @base_command.group()
+    async def group2(ctx):
+        # this symbolizes a group for subcommands.
+        # here, we will intentionally return StopCommand:
+        return interactions.StopCommand
+        # if this is returned, any callbacks afterwards in the same
+        # command will not be executed.
+        # for example, subcommand3 will not be executed.
+
+    @group2.subcommand()
+    async def subcommand3(ctx):
+        ...  # do something here.
+        # this is a subcommand of the group.
+        # this will NOT be executed.
+        # /base_command group2 subcommand3
+
+    @base_command.error
+    async def base_command_error(ctx, error):
+        ...  # do something here.
+        # remember the exception in subcommand2?
+        # here, you can handle any errors that occur in the base command.
+        # this is the error handler for the base command.
+        # the error is the exception raised by the command.
+        # you can have optional res, *args, and **kwargs
+        # if your command is a subcommand or
+        # there are options that you want to access.
+
+    # utilities
+    @bot.command()
+    @interactions.autodefer()  # configurable
+    async def autodefer_command(ctx):
+        # it will automatically defer the command if the command is not
+        # executed within the configured `delay` in the autodefer decorator.
+
+        # ActionRow.new() utility:
+        b1 = Button(style=1, custom_id="b1", label="b1")
+        b2 = Button(style=1, custom_id="b2", label="b2")
+        b3 = Button(style=1, custom_id="b3", label="b3")
+        b4 = Button(style=1, custom_id="b4", label="b4")
+
+        await ctx.send("Components:", components=interactions.ActionRow.new(b1, b2, b3, b4))
+        # instead of the cumbersome ActionRow(components=[b1, b2, b3, b4])
+
+        # spread_to_rows utility:
+        await ctx.send("Components:", components=interactions.spread_to_rows(b1, b2, b3, b4, max_in_row=2))
+        # configurable
+
+    bot.start()

docs/models.rst

@@ -9,3 +9,4 @@ Interaction Models
     models.command.rst
     models.component.rst
     models.misc.rst
+    models.utils.rst

docs/models.utils.rst

@@ -0,0 +1,8 @@
+.. currentmodule:: interactions
+
+Utilities
+==========================
+
+.. automodule:: interactions.client.models.utils
+    :members:
+    :noindex: