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

arc/abc/command.py

@@ -10,8 +10,10 @@ import hikari
 
 from arc.abc.error_handler import HasErrorHandler
 from arc.abc.hookable import Hookable, HookResult
+from arc.abc.limiter import LimiterProto
 from arc.abc.option import OptionBase
 from arc.context import AutodeferMode
+from arc.errors import CommandPublishFailedError
 from arc.internal.types import (
     BuilderT,
     ClientT,
@@ -24,8 +26,10 @@ from arc.internal.types import (
 from arc.locale import CommandLocaleRequest
 
 if t.TYPE_CHECKING:
+    import typing_extensions as te
+
     from arc.abc.plugin import PluginBase
-    from arc.context import Context
+    from arc.context.base import Context
 
 
 class CommandProto(t.Protocol):
@@ -46,15 +50,29 @@ class CommandProto(t.Protocol):
     def qualified_name(self) -> t.Sequence[str]:
         """The fully qualified name of this command."""
 
+    @property
+    @abc.abstractmethod
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+
+
+class CallableCommandProto(CommandProto, t.Protocol[ClientT]):
+    """A protocol for any command-like object that can be called directly.
 
-class CallableCommandProto(t.Protocol[ClientT]):
-    """A protocol for any command-like object that can be called directly. This includes commands and subcommands."""
+    This includes commands and subcommands, but not groups or subgroups.
+    """
 
     name: str
     """The name of the command."""
     name_localizations: t.Mapping[hikari.Locale, str]
     """The name of the command in different locales."""
+
     callback: CommandCallbackT[ClientT]
+    """The callback to invoke when this command is called."""
 
     @property
     @abc.abstractmethod
@@ -66,6 +84,35 @@ class CallableCommandProto(t.Protocol[ClientT]):
     def qualified_name(self) -> t.Sequence[str]:
         """The fully qualified name of this command."""
 
+    @property
+    @abc.abstractmethod
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+
+    @property
+    @abc.abstractmethod
+    def hooks(self) -> t.MutableSequence[HookT[ClientT]]:
+        """The pre-execution hooks for this command."""
+
+    @property
+    @abc.abstractmethod
+    def post_hooks(self) -> t.MutableSequence[PostHookT[ClientT]]:
+        """The post-execution hooks for this command."""
+
+    @abc.abstractmethod
+    def reset_all_limiters(self, context: Context[ClientT]) -> None:
+        """Reset all limiters for this command.
+
+        Parameters
+        ----------
+        context : Context
+            The context to reset the limiters for.
+        """
+
     @abc.abstractmethod
     async def __call__(self, ctx: Context[ClientT], *args: t.Any, **kwargs: t.Any) -> None:
         """Call the callback of the command with the given context and arguments.
@@ -110,55 +157,92 @@ class CallableCommandProto(t.Protocol[ClientT]):
     async def _handle_exception(self, ctx: Context[ClientT], exc: Exception) -> None:
         ...
 
+    @abc.abstractmethod
     def _resolve_hooks(self) -> t.Sequence[HookT[ClientT]]:
         """Resolve all pre-execution hooks that apply to this object."""
         ...
 
+    @abc.abstractmethod
     def _resolve_post_hooks(self) -> t.Sequence[PostHookT[ClientT]]:
         """Resolve all post-execution hooks that apply to this object."""
         ...
 
 
+@t.final
+@attr.define(slots=True, kw_only=True, weakref_slot=False)
+class _CommandSettings:
+    """All the command settings that need to propagate and be inherited."""
+
+    autodefer: AutodeferMode | hikari.UndefinedType
+    default_permissions: hikari.Permissions | hikari.UndefinedType
+    is_nsfw: bool | hikari.UndefinedType
+    is_dm_enabled: bool | hikari.UndefinedType
+
+    def apply(self, other: te.Self) -> te.Self:
+        """Apply 'other' to this, copying all the non-undefined settings to it."""
+        return type(self)(
+            autodefer=other.autodefer if other.autodefer is not hikari.UNDEFINED else self.autodefer,
+            default_permissions=other.default_permissions
+            if other.default_permissions is not hikari.UNDEFINED
+            else self.default_permissions,
+            is_nsfw=other.is_nsfw if other.is_nsfw is not hikari.UNDEFINED else self.is_nsfw,
+            is_dm_enabled=other.is_dm_enabled if other.is_dm_enabled is not hikari.UNDEFINED else self.is_dm_enabled,
+        )
+
+    @classmethod
+    def default(cls) -> te.Self:
+        """Get the default command settings."""
+        return cls(autodefer=AutodeferMode.ON, default_permissions=hikari.UNDEFINED, is_nsfw=False, is_dm_enabled=True)
+
+
 @attr.define(slots=True, kw_only=True)
 class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT, BuilderT]):
-    """An abstract base class for all application commands."""
+    """An abstract base class for all application commands.
+
+    This notably does not include subcommands & subgroups as those are in reality options.
+    """
 
     name: str
     """The name of this command."""
 
-    _client: ClientT | None = attr.field(init=False, default=None)
-    """The client that is handling this command."""
-
-    _plugin: PluginBase[ClientT] | None = attr.field(init=False, default=None)
-    """The plugin that this command belongs to, if any."""
-
-    guilds: hikari.UndefinedOr[t.Sequence[hikari.Snowflake]] = hikari.UNDEFINED
+    guilds: t.Sequence[hikari.Snowflake] | hikari.UndefinedType = hikari.UNDEFINED
     """The guilds this command is available in."""
 
-    autodefer: AutodeferMode = AutodeferMode.ON
+    _autodefer: AutodeferMode | hikari.UndefinedType = attr.field(default=hikari.UNDEFINED, alias="autodefer")
     """If ON, this command will be automatically deferred if it takes longer than 2 seconds to respond."""
 
-    is_dm_enabled: bool = True
+    _is_dm_enabled: bool | hikari.UndefinedType = attr.field(default=hikari.UNDEFINED, alias="is_dm_enabled")
     """Whether this command is enabled in DMs."""
 
-    default_permissions: hikari.UndefinedOr[hikari.Permissions] = hikari.UNDEFINED
+    _default_permissions: hikari.Permissions | hikari.UndefinedType = attr.field(
+        default=hikari.UNDEFINED, alias="default_permissions"
+    )
     """The default permissions for this command.
     Keep in mind that guild administrators can change this, it should only be used to provide safe defaults."""
 
+    _is_nsfw: bool | hikari.UndefinedType = attr.field(default=hikari.UNDEFINED, alias="is_nsfw")
+    """Whether this command is NSFW. If true, the command will only be available in NSFW channels."""
+
     name_localizations: t.Mapping[hikari.Locale, str] = attr.field(factory=dict)
     """The localizations for this command's name."""
 
-    is_nsfw: bool = False
-    """Whether this command is NSFW. If true, the command will only be available in NSFW channels."""
-
     _instances: dict[hikari.Snowflake | None, hikari.PartialCommand] = attr.field(factory=dict)
     """A mapping of guild IDs to command instances. None corresponds to the global instance, if any."""
 
+    _client: ClientT | None = attr.field(init=False, default=None)
+    """The client that is handling this command."""
+
+    _plugin: PluginBase[ClientT] | None = attr.field(init=False, default=None)
+    """The plugin that this command belongs to, if any."""
+
     _error_handler: ErrorHandlerCallbackT[ClientT] | None = attr.field(init=False, default=None)
+    """The error handler for this command."""
 
     _hooks: list[HookT[ClientT]] = attr.field(init=False, factory=list)
+    """The pre-execution hooks for this command."""
 
     _post_hooks: list[PostHookT[ClientT]] = attr.field(init=False, factory=list)
+    """The post-execution hooks for this command."""
 
     @property
     def error_handler(self) -> ErrorHandlerCallbackT[ClientT] | None:
@@ -195,7 +279,7 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
         """The client that is handling this command."""
         if self._client is None:
             raise RuntimeError(
-                f"Command '{self.qualified_name}' was not included in a client, '{type(self).__name__}.client' cannot be accessed until it is included in a client."
+                f"Command '{self.display_name}' was not included in a client, '{type(self).__name__}.client' cannot be accessed until it is included in a client."
             )
         return self._client
 
@@ -204,6 +288,43 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
         """The plugin that this command belongs to, if any."""
         return self._plugin
 
+    @property
+    def autodefer(self) -> AutodeferMode:
+        """The resolved autodefer configuration for this command."""
+        settings = self._resolve_settings()
+        return settings.autodefer if settings.autodefer is not hikari.UNDEFINED else AutodeferMode.ON
+
+    @property
+    def is_dm_enabled(self) -> bool:
+        """Whether this command is enabled in DMs."""
+        settings = self._resolve_settings()
+        return settings.is_dm_enabled if settings.is_dm_enabled is not hikari.UNDEFINED else True
+
+    @property
+    def default_permissions(self) -> hikari.Permissions | hikari.UndefinedType:
+        """The resolved default permissions for this command."""
+        return self._resolve_settings().default_permissions
+
+    @property
+    def is_nsfw(self) -> bool:
+        """Whether this command is NSFW. If true, the command will only be available in NSFW channels."""
+        settings = self._resolve_settings()
+        return settings.is_nsfw if settings.is_nsfw is not hikari.UNDEFINED else False
+
+    @property
+    def instances(self) -> t.Mapping[hikari.Snowflake | None, hikari.PartialCommand]:
+        """A mapping of guild IDs to command instances. None corresponds to the global instance, if any."""
+        return self._instances
+
+    @property
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+        return self.name
+
     def _register_instance(
         self, instance: hikari.PartialCommand, guild: hikari.SnowflakeishOr[hikari.PartialGuild] | None = None
     ) -> None:
@@ -221,6 +342,24 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
             else:
                 await self.client._on_error(ctx, exc)
 
+    def _resolve_settings(self) -> _CommandSettings:
+        """Resolve all settings that apply to this command."""
+        if self._plugin:
+            settings = self._plugin._resolve_settings()
+        elif self._client:
+            settings = self._client._cmd_settings
+        else:
+            settings = _CommandSettings.default()
+
+        return settings.apply(
+            _CommandSettings(
+                autodefer=self._autodefer,
+                default_permissions=self._default_permissions,
+                is_nsfw=self._is_nsfw,
+                is_dm_enabled=self._is_dm_enabled,
+            )
+        )
+
     def _resolve_hooks(self) -> list[HookT[ClientT]]:
         plugin_hooks = self.plugin._resolve_hooks() if self.plugin else []
         return self.client._hooks + plugin_hooks + self._hooks
@@ -246,13 +385,15 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
             raise RuntimeError("Cannot publish command without a client.")
 
         kwargs = self._to_dict()
-
-        if self.command_type is hikari.CommandType.SLASH:
-            created = await self.client.app.rest.create_slash_command(self.client.application, **kwargs)
-        else:
-            created = await self.client.app.rest.create_context_menu_command(
-                self.client.application, type=self.command_type, **kwargs
-            )
+        try:
+            if self.command_type is hikari.CommandType.SLASH:
+                created = await self.client.app.rest.create_slash_command(self.client.application, **kwargs)
+            else:
+                created = await self.client.app.rest.create_context_menu_command(
+                    self.client.application, type=self.command_type, **kwargs
+                )
+        except Exception as e:
+            raise CommandPublishFailedError(self, f"Failed to publish command '{self.display_name}'") from e
 
         self._instances[hikari.Snowflake(guild) if guild else None] = created
 
@@ -321,8 +462,8 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
 
     def _client_remove_hook(self, client: ClientT) -> None:
         """Called when the client requests the command be removed from it."""
-        self._client = None
         self.client._remove_command(self)
+        self._client = None
 
     def _plugin_include_hook(self, plugin: PluginBase[ClientT]) -> None:
         """Called when the plugin requests the command be added to it."""
@@ -360,10 +501,10 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
         try:
             hooks = command._resolve_hooks()
             for hook in hooks:
-                if inspect.iscoroutinefunction(hook):
-                    res = await hook(ctx)
-                else:
-                    res = hook(ctx)
+                res = hook(ctx)
+
+                if inspect.isawaitable(res):
+                    res = await res
 
                 res = t.cast(HookResult | None, res)
 
@@ -405,13 +546,27 @@ class CommandBase(HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT
 
 
 @attr.define(slots=True, kw_only=True)
-class CallableCommandBase(CommandBase[ClientT, BuilderT]):
-    """A command that can be called directly. Note that this does not include subcommands, as those are options."""
+class CallableCommandBase(CommandBase[ClientT, BuilderT], CallableCommandProto[ClientT]):
+    """A top-level command that can be called directly. Note that this does not include subcommands, as those are options."""
 
     callback: CommandCallbackT[ClientT]
     """The callback to invoke when this command is called."""
 
-    _invoke_task: asyncio.Task[t.Any] | None = attr.field(init=False, default=None)
+    _invoke_task: asyncio.Task[t.Any] | None = attr.field(init=False, default=None, repr=False)
+
+    def reset_all_limiters(self, context: Context[ClientT]) -> None:
+        """Reset all limiters for this command.
+
+        Parameters
+        ----------
+        context : Context
+            The context to reset the limiters for.
+        """
+        limiters: t.Generator[LimiterProto[ClientT], None, None] = (
+            lim for lim in self._resolve_hooks() if isinstance(lim, LimiterProto)
+        )
+        for limiter in limiters:
+            limiter.reset(context)
 
     async def __call__(self, ctx: Context[ClientT], *args: t.Any, **kwargs: t.Any) -> None:
         await self.callback(ctx, *args, **kwargs)
@@ -430,6 +585,7 @@ class CallableCommandBase(CommandBase[ClientT, BuilderT]):
 ParentT = t.TypeVar("ParentT")
 
 
+@attr.define(slots=True, kw_only=True)
 class SubCommandBase(OptionBase[ClientT], HasErrorHandler[ClientT], Hookable[ClientT], t.Generic[ClientT, ParentT]):
     """An abstract base class for all slash subcommands and subgroups."""
 
@@ -439,9 +595,18 @@ class SubCommandBase(OptionBase[ClientT], HasErrorHandler[ClientT], Hookable[Cli
 
     _post_hooks: list[PostHookT[ClientT]] = attr.field(factory=list, init=False)
 
-    parent: ParentT | None = attr.field(default=None, init=False)
+    _parent: ParentT | None = attr.field(default=None, init=False, alias="parent")
     """The parent of this subcommand or subgroup."""
 
+    @property
+    @abc.abstractmethod
+    def display_name(self) -> str:
+        """The display name of this command. This is what is shown in the Discord client.
+
+        !!! note
+            Slash commands can also be mentioned, see [SlashCommand.make_mention][arc.command.SlashCommand.make_mention].
+        """
+
     @property
     def error_handler(self) -> ErrorHandlerCallbackT[ClientT] | None:
         """The error handler for this object."""
@@ -461,3 +626,49 @@ class SubCommandBase(OptionBase[ClientT], HasErrorHandler[ClientT], Hookable[Cli
     def post_hooks(self) -> t.MutableSequence[PostHookT[ClientT]]:
         """The post-execution hooks for this object."""
         return self._post_hooks
+
+    @property
+    def parent(self) -> ParentT:
+        """The parent of this subcommand or subgroup."""
+        if self._parent is None:
+            raise RuntimeError(
+                f"Subcommand '{self.name}' was not included in a parent, '{type(self).__name__}.parent' cannot be accessed until it is included in a parent."
+            )
+        return self._parent
+
+    def reset_all_limiters(self, context: Context[ClientT]) -> None:
+        """Reset all limiters for this command.
+
+        Parameters
+        ----------
+        context : Context
+            The context to reset the limiters for.
+        """
+        limiters: t.Generator[LimiterProto[ClientT], None, None] = (
+            lim for lim in self._resolve_hooks() if isinstance(lim, LimiterProto)
+        )
+        for limiter in limiters:
+            limiter.reset(context)
+
+
+# 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/error_handler.py

@@ -45,12 +45,20 @@ class HasErrorHandler(abc.ABC, t.Generic[ClientT]):
         @client.include
         @arc.slash_command("foo", "Foo command description")
         async def foo(ctx: arc.GatewayContext) -> None:
-            raise Exception("foo")
+            raise RuntimeError("foo")
 
         @foo.set_error_handler
         async def foo_error_handler(ctx: arc.GatewayContext, exc: Exception) -> None:
-            await ctx.respond("foo failed")
+            if isinstance(exc, RuntimeError):
+                await ctx.respond("foo failed")
+                return
+
+            raise exc
         ```
+
+        !!! warning
+            Errors that cannot be handled by the error handler should be re-raised.
+            Otherwise they will not propagate to the next error handler.
         """
 
         def decorator(func: ErrorHandlerCallbackT[ClientT]) -> ErrorHandlerCallbackT[ClientT]:
@@ -65,3 +73,26 @@ class HasErrorHandler(abc.ABC, t.Generic[ClientT]):
     @abc.abstractmethod
     async def _handle_exception(self, ctx: Context[ClientT], exc: Exception) -> None:
         """Handle an exception or propagate it to the next error handler if it cannot be handled."""
+
+
+# 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/hookable.py

@@ -9,6 +9,7 @@ if t.TYPE_CHECKING:
     import typing_extensions as te
 
 
+@t.final
 class HookResult:
     """The result of a hook.
 
@@ -138,3 +139,26 @@ def with_post_hook(hook: PostHookT[ClientT]) -> t.Callable[[HookableT], Hookable
         return hookable
 
     return decorator
+
+
+# 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/limiter.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import abc
+import typing as t
+
+from arc.internal.types import ClientT
+
+if t.TYPE_CHECKING:
+    from arc.abc.hookable import HookResult
+    from arc.context.base import Context
+
+
+@t.runtime_checkable
+class LimiterProto(t.Protocol, t.Generic[ClientT]):
+    """A protocol that all limiter hooks should implement.
+    A limiter is simply a special type of hook with added methods.
+
+    If you're looking to integrate your own ratelimiter implementation,
+    you should make sure to implement all methods defined here.
+
+    !!! tip
+        An easy (but not necessary) way to ensure you've implemented all methods
+        is to inherit from this protocol.
+    """
+
+    @abc.abstractmethod
+    async def __call__(self, ctx: Context[ClientT]) -> HookResult:
+        """Call the limiter with the given context.
+        Implementations should raise an exception if the limiter is ratelimited
+        or abort via [`HookResult`][arc.abc.hookable.HookResult].
+
+        Parameters
+        ----------
+        ctx : Context
+            The context to evaluate the ratelimit under.
+        """
+
+    @abc.abstractmethod
+    def reset(self, ctx: Context[ClientT]) -> None:
+        """Reset the limiter for the given context.
+
+        Parameters
+        ----------
+        ctx : Context
+            The context to reset the ratelimit for.
+        """
+
+    @abc.abstractmethod
+    def is_rate_limited(self, ctx: Context[ClientT]) -> bool:
+        """Check if the limiter is rate limited for the given context.
+
+        Parameters
+        ----------
+        ctx : Context
+            The context to evaluate the ratelimit under.
+
+        Returns
+        -------
+        bool
+            Whether or not the limiter is ratelimited.
+        """