refactor(typing): replace **kwargs: Any with Unpack[T] in (app) command decorators (#1539)

Author: shiftinv

changelog/1539.feature.rst

@@ -0,0 +1 @@
+|commands| Improve typing of :func:`@command <ext.commands.command>`, :func:`@slash_command <ext.commands.command>`, and similar command decorators, making type-checkers warn about unknown/misspelled parameters.

disnake/ext/commands/base_core.py

@@ -12,6 +12,7 @@
     TYPE_CHECKING,
     Any,
     TypeAlias,
+    TypedDict,
     TypeVar,
     cast,
     overload,
@@ -30,7 +31,7 @@
 if TYPE_CHECKING:
     from typing import Concatenate
 
-    from typing_extensions import ParamSpec, Self
+    from typing_extensions import ParamSpec, Self, Unpack
 
     from disnake.interactions import ApplicationCommandInteraction
 
@@ -50,6 +51,13 @@
         | Callable[Concatenate[ApplicationCommandInteractionT, P], Coro[Any]]
     )
 
+    class _AppCommandArgs(TypedDict, total=False):
+        guild_only: bool
+        extras: dict[str, Any] | None
+        checks: list[AppCheck]
+        cooldown: CooldownMapping | None
+        max_concurrency: MaxConcurrency | None
+
 
 __all__ = (
     "InvokableApplicationCommand",
@@ -137,7 +145,9 @@ def __new__(cls, *args: Any, **kwargs: Any) -> Self:
         self.__original_kwargs__ = {k: v for k, v in kwargs.items() if v is not None}
         return self
 
-    def __init__(self, func: CommandCallback, *, name: str | None = None, **kwargs: Any) -> None:
+    def __init__(
+        self, func: CommandCallback, *, name: str | None = None, **kwargs: Unpack[_AppCommandArgs]
+    ) -> None:
         self.__command_flag__ = None
         self._callback: CommandCallback = func
         self.name: str = name or func.__name__

disnake/ext/commands/core.py

@@ -14,6 +14,7 @@
     Literal,
     Protocol,
     TypeAlias,
+    TypedDict,
     TypeVar,
     Union,
     cast,
@@ -59,12 +60,34 @@
 if TYPE_CHECKING:
     from typing import Concatenate
 
-    from typing_extensions import ParamSpec, Self
+    from typing_extensions import ParamSpec, Self, Unpack
 
     from disnake.message import Message
 
     from ._types import AppCheck, Check, Coro, CoroFunc, Error, Hook
 
+    class _CommandArgs(TypedDict, total=False):
+        enabled: bool
+        help: str | None
+        brief: str | None
+        usage: str | None
+        rest_is_raw: bool
+        aliases: list[str] | tuple[str, ...]
+        extras: dict[str, Any]
+        description: str
+        hidden: bool
+        checks: list[Check]
+        cooldown: CooldownMapping | None
+        max_concurrency: MaxConcurrency | None
+        require_var_positional: bool
+        ignore_extra: bool
+        cooldown_after_parsing: bool
+        parent: GroupMixin[Any] | None
+
+    class _GroupArgs(_CommandArgs, total=False):
+        invoke_without_command: bool
+        case_insensitive: bool
+
 
 __all__ = (
     "Command",
@@ -201,7 +224,7 @@ class Command(_BaseCommand, Generic[CogT, P, T]):
         The short help text for the command.
     usage: :class:`str` | :data:`None`
         A replacement for arguments in the default help text.
-    aliases: :class:`list`\[:class:`str`] | :class:`tuple`\[:class:`str`]
+    aliases: :class:`list`\[:class:`str`] | :class:`tuple`\[:class:`str`, ...]
         The list of aliases the command can be invoked under.
     enabled: :class:`bool`
         Whether the command is currently enabled.
@@ -277,13 +300,15 @@ def __new__(cls, *args: Any, **kwargs: Any) -> Self:
     def __init__(
         self,
         func: CommandCallback[CogT, ContextT, P, T],
-        **kwargs: Any,
+        *,
+        name: str | None = None,
+        **kwargs: Unpack[_CommandArgs],
     ) -> None:
         if not inspect.iscoroutinefunction(func):
             msg = "Callback must be a coroutine function."
             raise TypeError(msg)
 
-        name = kwargs.get("name") or func.__name__
+        name = name or func.__name__
         if not isinstance(name, str):
             msg = "Name of a command must be a string."
             raise TypeError(msg)
@@ -305,7 +330,7 @@ def __init__(
         self.brief: str | None = kwargs.get("brief")
         self.usage: str | None = kwargs.get("usage")
         self.rest_is_raw: bool = kwargs.get("rest_is_raw", False)
-        self.aliases: list[str] | tuple[str] = kwargs.get("aliases", [])
+        self.aliases: list[str] | tuple[str, ...] = kwargs.get("aliases", [])
         self.extras: dict[str, Any] = kwargs.get("extras", {})
 
         if not isinstance(self.aliases, (list, tuple)):
@@ -351,7 +376,7 @@ def __init__(
 
         # bandaid for the fact that sometimes parent can be the bot instance
         parent = kwargs.get("parent")
-        self.parent: GroupMixin | None = parent if isinstance(parent, _BaseCommand) else None  # pyright: ignore[reportAttributeAccessIssue]
+        self.parent: GroupMixin | None = parent if isinstance(parent, _BaseCommand) else None
 
         self._before_invoke: Hook | None = None
         try:
@@ -433,6 +458,8 @@ def remove_check(self, func: Check) -> None:
         except ValueError:
             pass
 
+    # n.b. this continues to use `**kwargs: Any` instead of _CommandArgs,
+    # since custom command subclasses may accept additional parameters
     def update(self, **kwargs: Any) -> None:
         """Updates :class:`Command` instance with updated attribute.
 
@@ -1283,18 +1310,16 @@ def get_command(self, name: str) -> Command[CogT, Any, Any] | None:
     @overload
     def command(
         self,
-        name: str,
-        cls: type[CommandT],
-        *args: Any,
-        **kwargs: Any,
-    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], CommandT]: ...
+        name: str = ...,
+        **attrs: Unpack[_CommandArgs],
+    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], Command[CogT, P, T]]: ...
 
     @overload
     def command(
         self,
-        name: str = ...,
-        *args: Any,
+        name: str,
         cls: type[CommandT],
+        *args: Any,
         **kwargs: Any,
     ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], CommandT]: ...
 
@@ -1303,8 +1328,9 @@ def command(
         self,
         name: str = ...,
         *args: Any,
+        cls: type[CommandT],
         **kwargs: Any,
-    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], Command[CogT, P, T]]: ...
+    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], CommandT]: ...
 
     def command(
         self,
@@ -1333,18 +1359,16 @@ def decorator(func: CommandCallback[CogT, ContextT, P, T]) -> Command[Any, Any,
     @overload
     def group(
         self,
-        name: str,
-        cls: type[GroupT],
-        *args: Any,
-        **kwargs: Any,
-    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], GroupT]: ...
+        name: str = ...,
+        **attrs: Unpack[_GroupArgs],
+    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], Group[CogT, P, T]]: ...
 
     @overload
     def group(
         self,
-        name: str = ...,
-        *args: Any,
+        name: str,
         cls: type[GroupT],
+        *args: Any,
         **kwargs: Any,
     ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], GroupT]: ...
 
@@ -1353,8 +1377,9 @@ def group(
         self,
         name: str = ...,
         *args: Any,
+        cls: type[GroupT],
         **kwargs: Any,
-    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], Group[CogT, P, T]]: ...
+    ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], GroupT]: ...
 
     def group(
         self,
@@ -1404,9 +1429,9 @@ class Group(GroupMixin[CogT], Command[CogT, P, T]):
         Defaults to ``False``.
     """
 
-    def __init__(self, *args: Any, **attrs: Any) -> None:
+    def __init__(self, *args: Any, name: str | None = None, **attrs: Unpack[_GroupArgs]) -> None:
         self.invoke_without_command: bool = attrs.pop("invoke_without_command", False)
-        super().__init__(*args, **attrs)
+        super().__init__(*args, name=name, **attrs)
 
     def copy(self: GroupT) -> GroupT:
         """Creates a copy of this :class:`Group`.
@@ -1522,15 +1547,17 @@ def __call__(
         ) -> Group[CogT, P, T]: ...
 
 
-# Small explanation regarding these overloads:
-# The overloads with the `cls` parameter need to be first,
-# as the other overload would otherwise match first even if `cls` is given.
-# To prevent the overloads with `cls` from matching everything, the parameter
-# cannot have a default value, which in turn means it has to be split into two
-# overloads, one with a positional `cls` parameter and one with a kwarg parameter,
-# as `name` should still be optional.
+@overload
+def command(
+    name: str = ...,
+    **attrs: Unpack[_CommandArgs],
+) -> CommandDecorator: ...
 
 
+# Typing **attrs correctly here is not possible with current ParamSpec/Concatenate features,
+# as it does not support adding kw-only arguments.
+# This overload is split into two, since `cls` cannot have a default without implicitly
+# becoming a fallback when the previous overload didn't match (due to typo'd parameters, etc.)
 @overload
 def command(
     name: str,
@@ -1548,19 +1575,12 @@ def command(
 ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], CommandT]: ...
 
 
-@overload
-def command(
-    name: str = ...,
-    **attrs: Any,
-) -> CommandDecorator: ...
-
-
 def command(
     name: str = MISSING,
     cls: type[Command[Any, Any, Any]] = MISSING,
     **attrs: Any,
 ) -> Any:
-    """A decorator that transforms a function into a :class:`.Command`
+    r"""A decorator that transforms a function into a :class:`.Command`
     or if called with :func:`.group`, :class:`.Group`.
 
     By default the ``help`` attribute is received automatically from the
@@ -1580,7 +1600,7 @@ def command(
     cls
         The class to construct with. By default this is :class:`.Command`.
         You usually do not change this.
-    attrs
+    \*\*attrs
         Keyword arguments to pass into the construction of the class denoted
         by ``cls``.
 
@@ -1603,16 +1623,14 @@ def decorator(func: CommandCallback[CogT, ContextT, P, T]) -> Command[Any, Any,
 
 @overload
 def group(
-    name: str,
-    cls: type[GroupT],
-    **attrs: Any,
-) -> Callable[[CommandCallback[CogT, ContextT, P, T]], GroupT]: ...
+    name: str = ...,
+    **attrs: Unpack[_GroupArgs],
+) -> GroupDecorator: ...
 
 
 @overload
 def group(
-    name: str = ...,
-    *,
+    name: str,
     cls: type[GroupT],
     **attrs: Any,
 ) -> Callable[[CommandCallback[CogT, ContextT, P, T]], GroupT]: ...
@@ -1621,8 +1639,10 @@ def group(
 @overload
 def group(
     name: str = ...,
+    *,
+    cls: type[GroupT],
     **attrs: Any,
-) -> GroupDecorator: ...
+) -> Callable[[CommandCallback[CogT, ContextT, P, T]], GroupT]: ...
 
 
 def group(