hikari-arc 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

arc/__init__.py

@@ -9,6 +9,7 @@ https://arc.hypergonial.com
 """
 
 from alluka import Client as Injector
+from alluka import OverridingContext as InjectorOverridingContext
 from alluka import inject
 
 from arc import abc, command, ext, utils
@@ -28,8 +29,11 @@ from .command import (
     AttachmentParams,
     BoolParams,
     ChannelParams,
+    ColorParams,
+    ColourParams,
     FloatParams,
     IntParams,
+    MemberParams,
     MentionableParams,
     MessageCommand,
     RoleParams,
@@ -49,6 +53,7 @@ from .context import AutocompleteData, AutodeferMode, Context, InteractionRespon
 from .errors import (
     ArcError,
     AutocompleteError,
+    BotMissingPermissionsError,
     CommandInvokeError,
     CommandPublishFailedError,
     DMOnlyError,
@@ -64,6 +69,7 @@ from .errors import (
     MaxConcurrencyReachedError,
     NoResponseIssuedError,
     NotOwnerError,
+    OptionConverterFailureError,
     ResponseAlreadyIssuedError,
     UnderCooldownError,
 )
@@ -112,7 +118,7 @@ __all__ = (
     "AutocompleteData",
     "Option",
     "Context",
-    "Context",
+    "InjectorOverridingContext",
     "BoolParams",
     "IntParams",
     "StrParams",
@@ -122,6 +128,9 @@ __all__ = (
     "RoleParams",
     "MentionableParams",
     "AttachmentParams",
+    "MemberParams",
+    "ColorParams",
+    "ColourParams",
     "SlashCommand",
     "SlashGroup",
     "SlashSubCommand",
@@ -148,6 +157,7 @@ __all__ = (
     "CommandPublishFailedError",
     "GuildCommandPublishFailedError",
     "GlobalCommandPublishFailedError",
+    "BotMissingPermissionsError",
     "MaxConcurrencyReachedError",
     "NoResponseIssuedError",
     "ResponseAlreadyIssuedError",
@@ -156,6 +166,7 @@ __all__ = (
     "ExtensionUnloadError",
     "HookAbortError",
     "InteractionResponseError",
+    "OptionConverterFailureError",
     "PluginBase",
     "RESTPluginBase",
     "GatewayPluginBase",

arc/__main__.py

@@ -1,4 +1,5 @@
 """CLI entry point for arc."""
+
 import os
 import platform
 import sys

arc/abc/__init__.py

@@ -8,6 +8,7 @@ from .hookable import Hookable, HookResult, with_hook, with_post_hook
 from .limiter import LimiterProto
 from .option import (
     CommandOptionBase,
+    ConverterOption,
     Option,
     OptionBase,
     OptionParams,
@@ -29,6 +30,7 @@ __all__ = (
     "OptionBase",
     "OptionType",
     "CommandOptionBase",
+    "ConverterOption",
     "OptionParams",
     "OptionWithChoices",
     "OptionWithChoicesParams",

arc/abc/client.py

@@ -15,13 +15,14 @@ from contextlib import suppress
 import alluka
 import hikari
 
-from arc.abc.command import _CommandSettings
+from arc.abc.command import CallableCommandBase, _CommandSettings
 from arc.abc.plugin import PluginBase
 from arc.command.message import MessageCommand
 from arc.command.slash import SlashCommand, SlashGroup, SlashSubCommand, SlashSubGroup
 from arc.command.user import UserCommand
 from arc.context import AutodeferMode, Context
 from arc.errors import ExtensionLoadError, ExtensionUnloadError
+from arc.internal.deprecation import warn_deprecate
 from arc.internal.sync import _sync_commands
 from arc.internal.types import (
     AppT,
@@ -30,11 +31,13 @@ from arc.internal.types import (
     CustomLocaleRequestT,
     ErrorHandlerCallbackT,
     HookT,
+    InjectionHookT,
     LifeCycleHookT,
     OptionLocaleRequestT,
     PostHookT,
     ResponseBuilderT,
 )
+from arc.internal.version import Version
 from arc.locale import CommandLocaleRequest, LocaleResponse, OptionLocaleRequest
 
 if t.TYPE_CHECKING:
@@ -98,10 +101,11 @@ class Client(t.Generic[AppT], abc.ABC):
         "_loaded_extensions",
         "_hooks",
         "_post_hooks",
+        "_injection_hooks",
         "_owner_ids",
         "_error_handler",
-        "_startup_hook",
-        "_shutdown_hook",
+        "_startup_hooks",
+        "_shutdown_hooks",
         "_provided_locales",
         "_command_locale_provider",
         "_option_locale_provider",
@@ -149,14 +153,15 @@ class Client(t.Generic[AppT], abc.ABC):
         self._loaded_extensions: list[str] = []
         self._hooks: list[HookT[te.Self]] = []
         self._post_hooks: list[PostHookT[te.Self]] = []
+        self._injection_hooks: list[InjectionHookT[te.Self]] = []
         self._owner_ids: list[hikari.Snowflake] = []
         self._tasks: set[asyncio.Task[t.Any]] = set()
         self._started: asyncio.Event = asyncio.Event()
         self._application: hikari.Application | None = None
         self._error_handler: ErrorHandlerCallbackT[te.Self] | None = None
         self._concurrency_limiter: ConcurrencyLimiterProto[te.Self] | None = None
-        self._startup_hook: LifeCycleHookT[te.Self] | None = None
-        self._shutdown_hook: LifeCycleHookT[te.Self] | None = None
+        self._startup_hooks: list[LifeCycleHookT[te.Self] | None] = [None]
+        self._shutdown_hooks: list[LifeCycleHookT[te.Self] | None] = [None]
         self._command_locale_provider: CommandLocaleRequestT | None = None
         self._option_locale_provider: OptionLocaleRequestT | None = None
         self._custom_locale_provider: CustomLocaleRequestT | None = None
@@ -285,8 +290,13 @@ class Client(t.Generic[AppT], abc.ABC):
             await _sync_commands(self)
 
         try:
-            if self._startup_hook:
-                await self._startup_hook(self)
+            for hook in self._startup_hooks:
+                if hook:
+                    try:
+                        await hook(self)
+                    except Exception as e:
+                        logger.error(f"Error in startup hook '{hook.__name__}': {e}")
+                        traceback.print_exc()
         finally:
             self._started.set()
 
@@ -294,8 +304,16 @@ class Client(t.Generic[AppT], abc.ABC):
         """Called when the client is shutting down.
         Reserved for internal shutdown logic.
         """
-        if self._shutdown_hook:
-            await self._shutdown_hook(self)
+        for hook in self._shutdown_hooks:
+            if hook:
+                try:
+                    await hook(self)
+                except Exception as e:
+                    logger.error(f"Error in shutdown hook '{hook.__name__}': {e}")
+                    traceback.print_exc()
+
+        for task in self._tasks:
+            task.cancel()
 
     async def _on_error(self, ctx: Context[te.Self], exception: Exception) -> None:
         if self._error_handler is not None:
@@ -311,6 +329,16 @@ class Client(t.Generic[AppT], abc.ABC):
             if ctx.is_valid:
                 await ctx.respond("❌ Something went wrong. Please contact the bot developer.")
 
+    async def _create_overriding_ctx_for_command(self, ctx: Context[te.Self]) -> alluka.OverridingContext:
+        inj_ctx = alluka.OverridingContext.from_client(self.injector)
+
+        for hook in self._injection_hooks:
+            if inspect.iscoroutinefunction(hook):
+                await hook(ctx, inj_ctx)
+            else:
+                hook(ctx, inj_ctx)
+        return inj_ctx
+
     def _provide_command_locale(self, request: CommandLocaleRequest) -> LocaleResponse:
         """Provide a locale for a command."""
         if self._command_locale_provider is None:
@@ -417,26 +445,24 @@ class Client(t.Generic[AppT], abc.ABC):
     @t.overload
     def walk_commands(
         self, command_type: t.Literal[hikari.CommandType.USER], *, callable_only: bool = False
-    ) -> t.Iterator[UserCommand[te.Self]]:
-        ...
+    ) -> 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.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.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]]:
-        ...
+    ) -> t.Iterator[SlashCommand[te.Self] | SlashSubCommand[te.Self]]: ...
 
     def walk_commands(  # noqa: C901
         self, command_type: hikari.CommandType, *, callable_only: bool = False
@@ -507,16 +533,19 @@ class Client(t.Generic[AppT], abc.ABC):
                 yield command
 
     @t.overload
-    def include(self) -> t.Callable[[CommandBase[te.Self, BuilderT]], CommandBase[te.Self, BuilderT]]:
-        ...
+    def include(
+        self,
+    ) -> t.Callable[[CallableCommandBase[te.Self, BuilderT]], CallableCommandBase[te.Self, BuilderT]]: ...
 
     @t.overload
-    def include(self, command: CommandBase[te.Self, BuilderT]) -> CommandBase[te.Self, BuilderT]:
-        ...
+    def include(self, command: CallableCommandBase[te.Self, BuilderT]) -> CallableCommandBase[te.Self, BuilderT]: ...
 
     def include(
-        self, command: CommandBase[te.Self, BuilderT] | None = None
-    ) -> CommandBase[te.Self, BuilderT] | t.Callable[[CommandBase[te.Self, BuilderT]], CommandBase[te.Self, BuilderT]]:
+        self, command: CallableCommandBase[te.Self, BuilderT] | None = None
+    ) -> (
+        CallableCommandBase[te.Self, BuilderT]
+        | t.Callable[[CallableCommandBase[te.Self, BuilderT]], CallableCommandBase[te.Self, BuilderT]]
+    ):
         """Decorator to add a command to this client.
 
         !!! note
@@ -542,7 +571,7 @@ class Client(t.Generic[AppT], abc.ABC):
         ```
         """
 
-        def decorator(command: CommandBase[te.Self, BuilderT]) -> CommandBase[te.Self, BuilderT]:
+        def decorator(command: CallableCommandBase[te.Self, BuilderT]) -> CallableCommandBase[te.Self, BuilderT]:
             if command.plugin is not None:
                 raise RuntimeError(
                     f"Command '{command.name}' is already registered with plugin '{command.plugin.name}'."
@@ -700,12 +729,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return self
 
     @t.overload
-    def add_hook(self, hook: HookT[te.Self]) -> te.Self:
-        ...
+    def add_hook(self, hook: HookT[te.Self]) -> te.Self: ...
 
     @t.overload
-    def add_hook(self) -> t.Callable[[HookT[te.Self]], HookT[te.Self]]:
-        ...
+    def add_hook(self) -> t.Callable[[HookT[te.Self]], HookT[te.Self]]: ...
 
     def add_hook(self, hook: HookT[te.Self] | None = None) -> te.Self | t.Callable[[HookT[te.Self]], HookT[te.Self]]:
         """Add a pre-execution hook to this client.
@@ -736,12 +763,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def add_post_hook(self, hook: PostHookT[te.Self]) -> te.Self:
-        ...
+    def add_post_hook(self, hook: PostHookT[te.Self]) -> te.Self: ...
 
     @t.overload
-    def add_post_hook(self) -> t.Callable[[PostHookT[te.Self]], PostHookT[te.Self]]:
-        ...
+    def add_post_hook(self) -> t.Callable[[PostHookT[te.Self]], PostHookT[te.Self]]: ...
 
     def add_post_hook(
         self, hook: PostHookT[te.Self] | None = None
@@ -777,12 +802,76 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def set_error_handler(self, handler: ErrorHandlerCallbackT[te.Self]) -> te.Self:
-        ...
+    def add_injection_hook(self, hook: InjectionHookT[te.Self]) -> te.Self: ...
 
     @t.overload
-    def set_error_handler(self) -> t.Callable[[ErrorHandlerCallbackT[te.Self]], te.Self]:
-        ...
+    def add_injection_hook(self) -> t.Callable[[InjectionHookT[te.Self]], InjectionHookT[te.Self]]: ...
+
+    def add_injection_hook(
+        self, hook: InjectionHookT[te.Self] | None = None
+    ) -> te.Self | t.Callable[[InjectionHookT[te.Self]], InjectionHookT[te.Self]]:
+        """Add an injection hook to this client.
+        This hook will be called when a command is called, and an OverridingContext is passed, allowing you to inject dependencies for the command call.
+
+        Parameters
+        ----------
+        hook : InjectionHookT[te.Self]
+            The hook to add.
+
+        Returns
+        -------
+        te.Self
+            The client for chaining calls.
+
+        Example
+        -------
+        ```py
+        @client.add_injection_hook
+        async def inject(ctx: arc.GatewayContext, inj_ctx: arc.InjectorOverridingContext) -> None:
+            foo: MyType = example_data[ctx.guild_id]
+            inj_ctx.set_type_dependency(MyType, foo)
+        ```
+
+        See Also
+        --------
+        - [`Client.set_type_dependency`][arc.client.Client.set_type_dependency]
+        """
+        if hook is not None:
+            self._injection_hooks.append(hook)
+            return self
+
+        def decorator(hook: InjectionHookT[te.Self]) -> InjectionHookT[te.Self]:
+            self._injection_hooks.append(hook)
+            return hook
+
+        return decorator
+
+    def remove_injection_hook(self, hook: InjectionHookT[te.Self]) -> te.Self:
+        """Remove an injection hook from this client.
+
+        Parameters
+        ----------
+        hook : InjectionHookT[te.Self]
+            The hook to remove.
+
+        Returns
+        -------
+        te.Self
+            The client for chaining calls.
+
+        Raises
+        ------
+        ValueError
+            If the hook is not registered with this client.
+        """
+        self._injection_hooks.remove(hook)
+        return self
+
+    @t.overload
+    def set_error_handler(self, handler: ErrorHandlerCallbackT[te.Self]) -> te.Self: ...
+
+    @t.overload
+    def set_error_handler(self) -> t.Callable[[ErrorHandlerCallbackT[te.Self]], te.Self]: ...
 
     def set_error_handler(
         self, handler: ErrorHandlerCallbackT[te.Self] | None = None
@@ -831,12 +920,104 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def set_startup_hook(self, hook: LifeCycleHookT[te.Self]) -> te.Self:
-        ...
+    def add_startup_hook(self, hook: LifeCycleHookT[te.Self]) -> te.Self: ...
+
+    @t.overload
+    def add_startup_hook(self) -> t.Callable[[LifeCycleHookT[te.Self]], te.Self]: ...
+
+    def add_startup_hook(
+        self, hook: LifeCycleHookT[te.Self] | None = None
+    ) -> te.Self | t.Callable[[LifeCycleHookT[te.Self]], te.Self]:
+        """Decorator to add a startup hook for this client.
+
+        This will be called when the client starts up.
+
+        Parameters
+        ----------
+        hook : LifeCycleHookT[te.Self]
+            The startup hook to add.
+
+        Returns
+        -------
+        te.Self
+            The client for chaining calls.
+
+        Examples
+        --------
+        ```py
+        @client.add_startup_hook
+        async def startup_hook(client: arc.GatewayClient) -> None:
+            print("Client started up!")
+        ```
+
+        Or, as a function:
+
+        ```py
+        client.add_startup_hook(startup_hook)
+        ```
+        """
+
+        def decorator(handler: LifeCycleHookT[te.Self]) -> te.Self:
+            self._startup_hooks.append(handler)
+            return self
+
+        if hook is not None:
+            return decorator(hook)
+
+        return decorator
+
+    @t.overload
+    def add_shutdown_hook(self, hook: LifeCycleHookT[te.Self]) -> te.Self: ...
 
     @t.overload
-    def set_startup_hook(self) -> t.Callable[[LifeCycleHookT[te.Self]], te.Self]:
-        ...
+    def add_shutdown_hook(self) -> t.Callable[[LifeCycleHookT[te.Self]], te.Self]: ...
+
+    def add_shutdown_hook(
+        self, hook: LifeCycleHookT[te.Self] | None = None
+    ) -> te.Self | t.Callable[[LifeCycleHookT[te.Self]], te.Self]:
+        """Decorator to add a shutdown hook for this client.
+
+        This will be called when the client shuts down.
+
+        Parameters
+        ----------
+        hook : LifeCycleHookT[te.Self]
+            The shutdown hook to add.
+
+        Returns
+        -------
+        te.Self
+            The client for chaining calls.
+
+        Examples
+        --------
+        ```py
+        @client.add_shutdown_hook
+        async def shutdown_hook(client: arc.GatewayClient) -> None:
+            print("Client shut down!")
+        ```
+
+        Or, as a function:
+
+        ```py
+        client.add_shutdown_hook(shutdown_hook)
+        ```
+        """
+
+        def decorator(handler: LifeCycleHookT[te.Self]) -> te.Self:
+            self._shutdown_hooks.append(handler)
+            return self
+
+        if hook is not None:
+            return decorator(hook)
+
+        return decorator
+
+    @t.overload
+    def set_startup_hook(self, hook: LifeCycleHookT[te.Self]) -> te.Self: ...
+
+    @t.overload
+    def set_startup_hook(self) -> t.Callable[[LifeCycleHookT[te.Self]], te.Self]: ...
 
     def set_startup_hook(
         self, hook: LifeCycleHookT[te.Self] | None = None
@@ -845,6 +1026,10 @@ class Client(t.Generic[AppT], abc.ABC):
 
         This will be called when the client starts up.
 
+        !!! warning "Deprecation Notice"
+            This method is deprecated and will be removed in version `2.0.0`.
+            Use [`Client.add_startup_hook`][arc.client.Client.add_startup_hook] instead.
+
         Parameters
         ----------
         hook : LifeCycleHookT[te.Self]
@@ -869,9 +1054,10 @@ class Client(t.Generic[AppT], abc.ABC):
         client.set_startup_hook(startup_hook)
         ```
         """
+        warn_deprecate(what="set_startup_hook", when=Version(2, 0, 0), use_instead="add_startup_hook")
 
         def decorator(handler: LifeCycleHookT[te.Self]) -> te.Self:
-            self._startup_hook = handler
+            self._startup_hooks[0] = handler
             return self
 
         if hook is not None:
@@ -880,12 +1066,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def set_shutdown_hook(self, hook: LifeCycleHookT[te.Self]) -> te.Self:
-        ...
+    def set_shutdown_hook(self, hook: LifeCycleHookT[te.Self]) -> te.Self: ...
 
     @t.overload
-    def set_shutdown_hook(self) -> t.Callable[[LifeCycleHookT[te.Self]], te.Self]:
-        ...
+    def set_shutdown_hook(self) -> t.Callable[[LifeCycleHookT[te.Self]], te.Self]: ...
 
     def set_shutdown_hook(
         self, hook: LifeCycleHookT[te.Self] | None = None
@@ -894,6 +1078,10 @@ class Client(t.Generic[AppT], abc.ABC):
 
         This will be called when the client shuts down.
 
+        !!! warning "Deprecation Notice"
+            This method is deprecated and will be removed in version `2.0.0`.
+            Use [`Client.add_shutdown_hook`][arc.client.Client.add_shutdown_hook] instead.
+
         Parameters
         ----------
         hook : LifeCycleHookT[te.Self]
@@ -918,9 +1106,10 @@ class Client(t.Generic[AppT], abc.ABC):
         client.set_shutdown_hook(shutdown_hook)
         ```
         """
+        warn_deprecate(what="set_shutdown_hook", when=Version(2, 0, 0), use_instead="add_shutdown_hook")
 
         def decorator(handler: LifeCycleHookT[te.Self]) -> te.Self:
-            self._shutdown_hook = handler
+            self._shutdown_hooks[0] = handler
             return self
 
         if hook is not None:
@@ -929,12 +1118,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def set_command_locale_provider(self, provider: CommandLocaleRequestT) -> te.Self:
-        ...
+    def set_command_locale_provider(self, provider: CommandLocaleRequestT) -> te.Self: ...
 
     @t.overload
-    def set_command_locale_provider(self) -> t.Callable[[CommandLocaleRequestT], te.Self]:
-        ...
+    def set_command_locale_provider(self) -> t.Callable[[CommandLocaleRequestT], te.Self]: ...
 
     def set_command_locale_provider(
         self, provider: CommandLocaleRequestT | None = None
@@ -978,12 +1165,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def set_option_locale_provider(self, provider: OptionLocaleRequestT) -> te.Self:
-        ...
+    def set_option_locale_provider(self, provider: OptionLocaleRequestT) -> te.Self: ...
 
     @t.overload
-    def set_option_locale_provider(self) -> t.Callable[[OptionLocaleRequestT], te.Self]:
-        ...
+    def set_option_locale_provider(self) -> t.Callable[[OptionLocaleRequestT], te.Self]: ...
 
     def set_option_locale_provider(
         self, provider: OptionLocaleRequestT | None = None
@@ -1027,12 +1212,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return decorator
 
     @t.overload
-    def set_custom_locale_provider(self, provider: CustomLocaleRequestT) -> te.Self:
-        ...
+    def set_custom_locale_provider(self, provider: CustomLocaleRequestT) -> te.Self: ...
 
     @t.overload
-    def set_custom_locale_provider(self) -> t.Callable[[CustomLocaleRequestT], te.Self]:
-        ...
+    def set_custom_locale_provider(self) -> t.Callable[[CustomLocaleRequestT], te.Self]: ...
 
     def set_custom_locale_provider(
         self, provider: CustomLocaleRequestT | None = None
@@ -1282,12 +1465,10 @@ class Client(t.Generic[AppT], abc.ABC):
         return self
 
     @t.overload
-    def get_type_dependency(self, type_: type[T]) -> T:
-        ...
+    def get_type_dependency(self, type_: type[T]) -> T: ...
 
     @t.overload
-    def get_type_dependency(self, type_: type[T], *, default: DefaultT) -> T | DefaultT:
-        ...
+    def get_type_dependency(self, type_: type[T], *, default: DefaultT) -> T | DefaultT: ...
 
     def get_type_dependency(
         self, type_: type[T], *, default: DefaultT | hikari.UndefinedType = hikari.UNDEFINED
@@ -1313,20 +1494,15 @@ class Client(t.Generic[AppT], abc.ABC):
             If the dependency does not exist and `default` was not provided.
         """
         if default is hikari.UNDEFINED:
-            value = self._injector.get_type_dependency(type_)
-            if isinstance(value, alluka.abc.Undefined):
-                raise KeyError(f"Could not resolve dependency of type {type_}.")
-            return value
+            return self._injector.get_type_dependency(type_)
         else:
             return self._injector.get_type_dependency(type_, default=default)
 
     @t.overload
-    def inject_dependencies(self, func: t.Callable[P, T]) -> t.Callable[P, T]:
-        ...
+    def inject_dependencies(self, func: t.Callable[P, T]) -> t.Callable[P, T]: ...
 
     @t.overload
-    def inject_dependencies(self) -> t.Callable[[t.Callable[P, T]], t.Callable[P, T]]:
-        ...
+    def inject_dependencies(self) -> t.Callable[[t.Callable[P, T]], t.Callable[P, T]]: ...
 
     def inject_dependencies(
         self, func: t.Callable[P, T] | None = None