hikari-arc 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

arc/__init__.py

@@ -11,10 +11,20 @@ https://arc.hypergonial.com
 from alluka import Client as Injector
 from alluka import inject
 
-from arc import abc, command
+from arc import abc, command, utils
 
-from .abc import HookResult, Option, with_hook, with_post_hook
-from .client import Client, GatewayClient, GatewayContext, GatewayPlugin, RESTClient, RESTContext, RESTPlugin
+from .abc import HookResult, Option, OptionType, with_hook, with_post_hook
+from .client import (
+    Client,
+    GatewayClient,
+    GatewayClientBase,
+    GatewayContext,
+    GatewayPlugin,
+    RESTClient,
+    RESTClientBase,
+    RESTContext,
+    RESTPlugin,
+)
 from .command import (
     AttachmentParams,
     BoolParams,
@@ -37,7 +47,18 @@ from .command import (
     user_command,
 )
 from .context import AutocompleteData, AutodeferMode, Context, InteractionResponse
-from .errors import ArcError, AutocompleteError, CommandInvokeError
+from .errors import (
+    ArcError,
+    AutocompleteError,
+    CommandInvokeError,
+    CommandPublishFailedError,
+    DMOnlyError,
+    GuildCommandPublishFailedError,
+    GuildOnlyError,
+    InvokerMissingPermissionsError,
+    NotOwnerError,
+    UnderCooldownError,
+)
 from .events import ArcEvent, CommandErrorEvent
 from .extension import loader, unloader
 from .internal.about import __author__, __author_email__, __license__, __maintainer__, __url__, __version__
@@ -50,7 +71,19 @@ from .locale import (
     OptionLocaleRequest,
 )
 from .plugin import GatewayPluginBase, PluginBase, RESTPluginBase
-from .utils import bot_has_permissions, dm_only, guild_only, has_permissions, owner_only
+from .utils import (
+    bot_has_permissions,
+    channel_limiter,
+    custom_limiter,
+    dm_only,
+    global_limiter,
+    guild_limiter,
+    guild_only,
+    has_permissions,
+    member_limiter,
+    owner_only,
+    user_limiter,
+)
 
 __all__ = (
     "__version__",
@@ -86,11 +119,21 @@ __all__ = (
     "slash_command",
     "slash_subcommand",
     "Client",
+    "GatewayClientBase",
+    "RESTClientBase",
     "GatewayClient",
     "RESTClient",
+    "OptionType",
     "ArcError",
     "AutocompleteError",
+    "UnderCooldownError",
+    "InvokerMissingPermissionsError",
+    "GuildOnlyError",
+    "NotOwnerError",
+    "DMOnlyError",
     "CommandInvokeError",
+    "GuildCommandPublishFailedError",
+    "CommandPublishFailedError",
     "PluginBase",
     "RESTPluginBase",
     "GatewayPluginBase",
@@ -111,6 +154,7 @@ __all__ = (
     "CommandLocaleRequest",
     "OptionLocaleRequest",
     "abc",
+    "utils",
     "command",
     "with_hook",
     "with_post_hook",
@@ -119,6 +163,12 @@ __all__ = (
     "guild_only",
     "has_permissions",
     "owner_only",
+    "global_limiter",
+    "guild_limiter",
+    "channel_limiter",
+    "user_limiter",
+    "member_limiter",
+    "custom_limiter",
 )
 
 # MIT License

arc/abc/__init__.py

@@ -2,7 +2,15 @@ from .client import Client
 from .command import CallableCommandBase, CallableCommandProto, CommandBase, CommandProto
 from .error_handler import HasErrorHandler
 from .hookable import Hookable, HookResult, with_hook, with_post_hook
-from .option import CommandOptionBase, Option, OptionBase, OptionParams, OptionWithChoices, OptionWithChoicesParams
+from .option import (
+    CommandOptionBase,
+    Option,
+    OptionBase,
+    OptionParams,
+    OptionType,
+    OptionWithChoices,
+    OptionWithChoicesParams,
+)
 from .plugin import PluginBase
 
 __all__ = (
@@ -13,6 +21,7 @@ __all__ = (
     "CallableCommandBase",
     "Option",
     "OptionBase",
+    "OptionType",
     "CommandOptionBase",
     "OptionParams",
     "OptionWithChoices",
@@ -24,3 +33,25 @@ __all__ = (
     "with_hook",
     "with_post_hook",
 )
+
+# MIT License
+#
+# Copyright (c) 2023-present hypergonial
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

arc/abc/client.py

@@ -15,6 +15,7 @@ from contextlib import suppress
 import alluka
 import hikari
 
+from arc.abc.command import _CommandSettings
 from arc.abc.plugin import PluginBase
 from arc.command.message import MessageCommand
 from arc.command.slash import SlashCommand, SlashGroup, SlashSubCommand, SlashSubGroup
@@ -53,16 +54,28 @@ logger = logging.getLogger(__name__)
 
 class Client(t.Generic[AppT], abc.ABC):
     """The abstract base class for an `arc` client.
-    See [`GatewayClient`][arc.client.GatewayClient] and [`RESTClient`][arc.client.RESTClient] for implementations.
+    See [`GatewayClientBase`][arc.client.GatewayClientBase] and [`RESTClientBase`][arc.client.RESTClientBase] for implementations.
 
     Parameters
     ----------
     app : AppT
         The application this client is for.
-    default_enabled_guilds : t.Sequence[hikari.Snowflake] | None, optional
-        The guilds that slash commands will be registered in by default, by default None
-    autosync : bool, optional
-        Whether to automatically sync commands on startup, by default True
+    default_enabled_guilds : t.Sequence[hikari.Snowflake] | None
+        The guilds that slash commands will be registered in by default
+    autosync : bool
+        Whether to automatically sync commands on startup
+    autodefer : bool | AutodeferMode
+        Whether to automatically defer commands that take longer than 2 seconds to respond
+        This applies to all commands, and can be overridden on a per-command basis.
+    default_permissions : hikari.Permissions | hikari.UndefinedType
+        The default permissions for commands
+        This applies to all commands, and can be overridden on a per-command basis.
+    is_nsfw : bool
+        Whether to mark commands as NSFW
+        This applies to all commands, and can be overridden on a per-command basis.
+    is_dm_enabled : bool
+        Whether to enable commands in DMs
+        This applies to all commands, and can be overridden on a per-command basis.
     """
 
     __slots__: t.Sequence[str] = (
@@ -86,20 +99,36 @@ class Client(t.Generic[AppT], abc.ABC):
         "_command_locale_provider",
         "_option_locale_provider",
         "_custom_locale_provider",
+        "_cmd_settings",
     )
 
     def __init__(
         self,
         app: AppT,
         *,
-        default_enabled_guilds: t.Sequence[hikari.Snowflake] | None = None,
+        default_enabled_guilds: t.Sequence[hikari.Snowflakeish | hikari.PartialGuild]
+        | hikari.UndefinedType = hikari.UNDEFINED,
         autosync: bool = True,
+        autodefer: bool | AutodeferMode = True,
+        default_permissions: hikari.Permissions | hikari.UndefinedType = hikari.UNDEFINED,
+        is_nsfw: bool = False,
+        is_dm_enabled: bool = True,
         provided_locales: t.Sequence[hikari.Locale] | None = None,
     ) -> None:
         self._app = app
-        self._default_enabled_guilds = default_enabled_guilds
+        self._default_enabled_guilds = (
+            tuple(hikari.Snowflake(i) for i in default_enabled_guilds)
+            if default_enabled_guilds is not hikari.UNDEFINED
+            else hikari.UNDEFINED
+        )
         self._autosync = autosync
         self._provided_locales: t.Sequence[hikari.Locale] | None = provided_locales
+        self._cmd_settings = _CommandSettings(
+            autodefer=AutodeferMode(autodefer),
+            default_permissions=default_permissions,
+            is_nsfw=is_nsfw,
+            is_dm_enabled=is_dm_enabled,
+        )
 
         self._application: hikari.Application | None = None
         self._slash_commands: dict[str, SlashCommandLike[te.Self]] = {}
@@ -127,6 +156,20 @@ class Client(t.Generic[AppT], abc.ABC):
         will return interaction response builders to be sent back to Discord, otherwise they will return None.
         """
 
+    @property
+    def _commands(self) -> t.Mapping[hikari.CommandType, t.Mapping[str, CommandBase[te.Self, t.Any]]]:
+        """All top-level commands added to this client, categorized by command type.
+
+        !!! note
+            This does not include subcommands & subgroups due to implementation details, therefore
+            you should use [`Client.walk_commands()`][arc.abc.client.Client.walk_commands] instead.
+        """
+        return {
+            hikari.CommandType.SLASH: self._slash_commands,
+            hikari.CommandType.MESSAGE: self._message_commands,
+            hikari.CommandType.USER: self._user_commands,
+        }
+
     @property
     def app(self) -> AppT:
         """The application this client is for."""
@@ -148,34 +191,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return self._injector
 
     @property
-    def default_enabled_guilds(self) -> t.Sequence[hikari.Snowflake] | None:
+    def default_enabled_guilds(self) -> t.Sequence[hikari.Snowflake] | hikari.UndefinedType:
         """The guilds that slash commands will be registered in by default."""
         return self._default_enabled_guilds
 
-    @property
-    def commands(self) -> t.Mapping[hikari.CommandType, t.Mapping[str, CommandBase[te.Self, t.Any]]]:
-        """All commands added to this client, categorized by command type."""
-        return {
-            hikari.CommandType.SLASH: self.slash_commands,
-            hikari.CommandType.MESSAGE: self._message_commands,
-            hikari.CommandType.USER: self._user_commands,
-        }
-
-    @property
-    def slash_commands(self) -> t.Mapping[str, SlashCommandLike[te.Self]]:
-        """The slash commands added to this client. This only includes top-level commands and groups."""
-        return self._slash_commands
-
-    @property
-    def message_commands(self) -> t.Mapping[str, MessageCommand[te.Self]]:
-        """The message commands added to this client."""
-        return self._message_commands
-
-    @property
-    def user_commands(self) -> t.Mapping[str, UserCommand[te.Self]]:
-        """The user commands added to this client."""
-        return self._user_commands
-
     @property
     def plugins(self) -> t.Mapping[str, PluginBase[te.Self]]:
         """The plugins added to this client."""
@@ -289,11 +308,11 @@ class Client(t.Generic[AppT], abc.ABC):
 
         match interaction.command_type:
             case hikari.CommandType.SLASH:
-                command = self.slash_commands.get(interaction.command_name)
+                command = self._slash_commands.get(interaction.command_name)
             case hikari.CommandType.MESSAGE:
-                command = self.message_commands.get(interaction.command_name)
+                command = self._message_commands.get(interaction.command_name)
             case hikari.CommandType.USER:
-                command = self.user_commands.get(interaction.command_name)
+                command = self._user_commands.get(interaction.command_name)
             case _:
                 pass
 
@@ -343,7 +362,7 @@ class Client(t.Generic[AppT], abc.ABC):
         hikari.api.InteractionAutocompleteBuilder | None
             The autocomplete builder to send back to Discord, if using a REST client.
         """
-        command = self.slash_commands.get(interaction.command_name)
+        command = self._slash_commands.get(interaction.command_name)
 
         if command is None:
             logger.warning(f"Received autocomplete interaction for unknown command '{interaction.command_name}'.")
@@ -351,6 +370,98 @@ class Client(t.Generic[AppT], abc.ABC):
 
         return await command._on_autocomplete(interaction)
 
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.USER], *, callable_only: bool = False
+    ) -> t.Iterator[UserCommand[te.Self]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.MESSAGE], *, callable_only: bool = False
+    ) -> t.Iterator[MessageCommand[te.Self]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.SLASH], *, callable_only: t.Literal[False] = False
+    ) -> t.Iterator[SlashCommand[te.Self] | SlashSubCommand[te.Self] | SlashGroup[te.Self] | SlashSubGroup[te.Self]]:
+        ...
+
+    @t.overload
+    def walk_commands(
+        self, command_type: t.Literal[hikari.CommandType.SLASH], *, callable_only: t.Literal[True] = True
+    ) -> t.Iterator[SlashCommand[te.Self] | SlashSubCommand[te.Self]]:
+        ...
+
+    def walk_commands(  # noqa: C901
+        self, command_type: hikari.CommandType, *, callable_only: bool = False
+    ) -> t.Iterator[t.Any]:
+        """Iterate over all commands of a certain type added to this plugin.
+
+        Parameters
+        ----------
+        command_type : hikari.CommandType
+            The type of commands to return.
+        callable_only : bool
+            Whether to only return commands that are directly callable.
+            If True, command groups and subgroups will be skipped.
+            This is only applicable to slash commands.
+
+        Yields
+        ------
+        CommandT[te.Self]
+            The next command that matches the given criteria.
+
+        Usage
+        -----
+        ```py
+        for cmd in plugin.walk_commands(hikari.CommandType.SLASH):
+            print(cmd.name)
+        ```
+
+        !!! tip
+            To iterate over all types of commands, you may use [`itertools.chain()`][itertools.chain]:
+
+            ```py
+            import itertools
+
+            for cmd in itertools.chain(
+                plugin.walk_commands(hikari.CommandType.SLASH),
+                plugin.walk_commands(hikari.CommandType.MESSAGE),
+                plugin.walk_commands(hikari.CommandType.USER),
+            ):
+                print(cmd.name)
+            ```
+        """
+        if hikari.CommandType.SLASH is command_type:
+            for command in self._slash_commands.values():
+                if isinstance(command, SlashCommand):
+                    yield command
+                    continue
+
+                if not callable_only:
+                    yield command
+
+                for sub in command.children.values():
+                    if isinstance(sub, SlashSubCommand):
+                        yield sub
+                        continue
+
+                    if not callable_only:
+                        yield sub
+
+                    for subsub in sub.children.values():
+                        yield subsub
+
+        elif hikari.CommandType.MESSAGE is command_type:
+            for command in self._message_commands.values():
+                yield command
+
+        elif hikari.CommandType.USER is command_type:
+            for command in self._user_commands.values():
+                yield command
+
     @t.overload
     def include(self) -> t.Callable[[CommandBase[te.Self, BuilderT]], CommandBase[te.Self, BuilderT]]:
         ...
@@ -394,7 +505,7 @@ class Client(t.Generic[AppT], abc.ABC):
                     f"\nYou should use '{type(self).__name__}.add_plugin()' to add the entire plugin to the client."
                 )
 
-            if existing := self.commands[command.command_type].get(command.name):
+            if existing := self._commands[command.command_type].get(command.name):
                 logger.warning(
                     f"Shadowing already registered command '{command.name}'. Did you define multiple commands with the same name?"
                 )
@@ -413,12 +524,12 @@ class Client(t.Generic[AppT], abc.ABC):
         name: str,
         description: str = "No description provided.",
         *,
-        guilds: hikari.UndefinedOr[t.Sequence[hikari.Snowflake]] = hikari.UNDEFINED,
-        autodefer: bool | AutodeferMode = True,
-        is_dm_enabled: bool = True,
-        default_permissions: hikari.UndefinedOr[hikari.Permissions] = hikari.UNDEFINED,
-        name_localizations: dict[hikari.Locale, str] | None = None,
-        description_localizations: dict[hikari.Locale, str] | None = None,
+        guilds: t.Sequence[hikari.Snowflakeish | hikari.PartialGuild] | hikari.UndefinedType = hikari.UNDEFINED,
+        autodefer: bool | AutodeferMode | hikari.UndefinedType = hikari.UNDEFINED,
+        is_dm_enabled: bool | hikari.UndefinedType = hikari.UNDEFINED,
+        default_permissions: hikari.Permissions | hikari.UndefinedType = hikari.UNDEFINED,
+        name_localizations: t.Mapping[hikari.Locale, str] | None = None,
+        description_localizations: t.Mapping[hikari.Locale, str] | None = None,
         is_nsfw: bool = False,
     ) -> SlashGroup[te.Self]:
         """Add a new slash command group to this client.
@@ -429,27 +540,30 @@ class Client(t.Generic[AppT], abc.ABC):
             The name of the slash command group.
         description : str
             The description of the slash command group.
-        guilds : hikari.UndefinedOr[t.Sequence[hikari.Snowflake]], optional
-            The guilds to register the slash command group in, by default hikari.UNDEFINED
-        autodefer : bool | AutodeferMode, optional
+        guilds : t.Sequence[hikari.Snowflake] | hikari.UndefinedType
+            The guilds to register the slash command group in
+        autodefer : bool | AutodeferMode
             If True, all commands in this group will automatically defer if it is taking longer than 2 seconds to respond.
             This can be overridden on a per-subcommand basis.
-        is_dm_enabled : bool, optional
-            Whether the slash command group is enabled in DMs, by default True
-        default_permissions : hikari.UndefinedOr[hikari.Permissions], optional
-            The default permissions for the slash command group, by default hikari.UNDEFINED
-        name_localizations : dict[hikari.Locale, str], optional
-            The name of the slash command group in different locales, by default None
-        description_localizations : dict[hikari.Locale, str], optional
-            The description of the slash command group in different locales, by default None
-        is_nsfw : bool, optional
-            Whether the slash command group is only usable in NSFW channels, by default False
+        is_dm_enabled : bool
+            Whether the slash command group is enabled in DMs
+        default_permissions : hikari.Permissions | hikari.UndefinedType
+            The default permissions for the slash command group
+        name_localizations : dict[hikari.Locale, str]
+            The name of the slash command group in different locales
+        description_localizations : dict[hikari.Locale, str]
+            The description of the slash command group in different locales
+        is_nsfw : bool
+            Whether the slash command group is only usable in NSFW channels
 
         Returns
         -------
         SlashGroup[te.Self]
             The slash command group that was created.
 
+        !!! note
+            Parameters left as `hikari.UNDEFINED` will be inherited from the parent client.
+
         Usage
         -----
         ```py
@@ -461,14 +575,13 @@ class Client(t.Generic[AppT], abc.ABC):
             await ctx.respond("Hello!")
         ```
         """
-        children: dict[str, SlashSubCommand[te.Self] | SlashSubGroup[te.Self]] = {}
+        guild_ids = tuple(hikari.Snowflake(i) for i in guilds) if guilds is not hikari.UNDEFINED else hikari.UNDEFINED
 
-        group = SlashGroup(
+        group: SlashGroup[te.Self] = SlashGroup(
             name=name,
             description=description,
-            children=children,
-            guilds=guilds,
-            autodefer=AutodeferMode(autodefer),
+            guilds=guild_ids,
+            autodefer=AutodeferMode(autodefer) if isinstance(autodefer, bool) else autodefer,
             is_dm_enabled=is_dm_enabled,
             default_permissions=default_permissions,
             name_localizations=name_localizations or {},
@@ -632,6 +745,10 @@ class Client(t.Generic[AppT], abc.ABC):
             await ctx.respond(f"❌ Something went wrong: {exception}")
         ```
 
+        !!! warning
+            Errors that cannot be handled by the error handler should be re-raised.
+            Otherwise tracebacks will not be printed to stderr.
+
         Or, as a function:
 
         ```py
@@ -931,8 +1048,8 @@ class Client(t.Generic[AppT], abc.ABC):
         ----------
         dir_path : str
             The path to the directory to load extensions from.
-        recursive : bool, optional
-            Whether to load extensions from subdirectories, by default False
+        recursive : bool
+            Whether to load extensions from subdirectories
 
         Returns
         -------
@@ -1074,7 +1191,7 @@ class Client(t.Generic[AppT], abc.ABC):
         self._injector.set_type_dependency(type_, instance)
         return self
 
-    def get_type_dependency(self, type_: t.Type[T]) -> hikari.UndefinedOr[T]:
+    def get_type_dependency(self, type_: t.Type[T]) -> T | hikari.UndefinedType:
         """Get a type dependency for this client.
 
         Parameters
@@ -1084,7 +1201,7 @@ class Client(t.Generic[AppT], abc.ABC):
 
         Returns
         -------
-        hikari.UndefinedOr[T]
+        T | hikari.UndefinedType
             The instance of the dependency, if it exists.
         """
         return self._injector.get_type_dependency(type_, default=hikari.UNDEFINED)
@@ -1170,8 +1287,8 @@ class Client(t.Generic[AppT], abc.ABC):
 
         Parameters
         ----------
-        guild : hikari.SnowflakeishOr[hikari.PartialGuild] | None, optional
-            The guild to purge commands from, by default None
+        guild : hikari.SnowflakeishOr[hikari.PartialGuild] | None
+            The guild to purge commands from
             If a `guild` is not provided, this will purge global commands.
 
         !!! warning
@@ -1191,3 +1308,26 @@ class Client(t.Generic[AppT], abc.ABC):
             await self.rest.set_application_commands(self.application, [], guild_id)
         else:
             await self.rest.set_application_commands(self.application, [])
+
+
+# MIT License
+#
+# Copyright (c) 2023-present hypergonial
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.