Improve typing around callbacks with dynamic keyword-arguments (#176)

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

Author: 3 people

CHANGELOG.md

@@ -5,6 +5,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- [tanjun.MenuHooks][] is now exported top-level.
+
+### Changed
+- Improved the typing of callbacks which support DI to enforce the type of any positionally
+  passed arguments with a static type.
+  MyPy doesn't support this and will just behave as before.
+
+### Fixed
+- [tanjun.annotations.Converted][] now properly overrides the actual type annotation for
+  slash commands.
+- The `add_{}_option` and `with_{}_option` methods for the standard slash command impl
+  will no-longer mishandle iterable but non-sequence types like [enum.Enum][] as if
+  they were a sequence of converters when they are passed as the value for `converters`.
+
 ### [2.11.2] - 2023-01-23
 ### Changed
 - [tanjun.clients.Client.from_gateway_bot][] can now also take cache-less `ShardAware` bots.

tanjun/__init__.py

@@ -115,6 +115,7 @@ async def hello(ctx: tanjun.abc.Context, user: hikari.User | None) -> None:
     "InteractionAcceptsEnum",
     "LazyConstant",
     "MenuCommand",
+    "MenuHooks",
     "MessageAcceptsEnum",
     "MessageCommand",
     "MessageCommandGroup",
@@ -296,6 +297,7 @@ async def hello(ctx: tanjun.abc.Context, user: hikari.User | None) -> None:
 from .errors import TooManyArgumentsError
 from .hooks import AnyHooks
 from .hooks import Hooks
+from .hooks import MenuHooks
 from .hooks import MessageHooks
 from .hooks import SlashHooks
 from .injecting import as_self_injecting

tanjun/_internal/__init__.py

@@ -55,18 +55,19 @@
 
     from .. import abc as tanjun
 
+    _T = typing.TypeVar("_T")
     _P = typing_extensions.ParamSpec("_P")
 
+    _ContextT = typing.TypeVar("_ContextT", bound=tanjun.Context)
+    _CoroT = collections.Coroutine[typing.Any, typing.Any, _T]
     _TreeT = dict[
         typing.Union[str, "_IndexKeys"],
         typing.Union["_TreeT", list[tuple[list[str], tanjun.MessageCommand[typing.Any]]]],
     ]
 
 
-_T = typing.TypeVar("_T")
 _KeyT = typing.TypeVar("_KeyT")
 _OtherT = typing.TypeVar("_OtherT")
-_CoroT = collections.Coroutine[typing.Any, typing.Any, _T]
 
 _LOGGER = logging.getLogger("hikari.tanjun")
 
@@ -88,21 +89,21 @@ class _NoDefaultEnum(enum.Enum):
 """The type of `NO_DEFAULT`."""
 
 
-async def _execute_check(ctx: tanjun.Context, callback: tanjun.CheckSig, /) -> bool:
+async def _execute_check(ctx: _ContextT, callback: tanjun.CheckSig[_ContextT], /) -> bool:
     if result := await ctx.call_with_async_di(callback, ctx):
         return result
 
     raise errors.FailedCheck
 
 
-async def gather_checks(ctx: tanjun.Context, checks: collections.Iterable[tanjun.CheckSig], /) -> bool:
+async def gather_checks(ctx: _ContextT, checks: collections.Iterable[tanjun.CheckSig[_ContextT]], /) -> bool:
     """Gather a collection of checks.
 
     Parameters
     ----------
-    ctx
+    ctx : tanjun.abc.Context
         The context to check.
-    checks
+    checks : collections.abc.Iterable[tanjun.abc.CheckSig]
         An iterable of injectable checks.
 
     Returns
@@ -157,7 +158,7 @@ def __len__(self) -> int:
 _KEYWORD_TYPES = {inspect.Parameter.KEYWORD_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD}
 
 
-def get_kwargs(callback: collections.Callable[..., typing.Any], /) -> list[str] | None:
+def get_kwargs(callback: collections.Callable[..., typing.Any], /) -> typing.Union[list[str], None]:
     """Get a list of the keyword argument names for a callback.
 
     Parameters