✨ Use inspect.get_annotations and add utils for it as well

Author: Paillat-dev

discord/errors.py

@@ -40,6 +40,7 @@
     from .interactions import Interaction
 
 __all__ = (
+    "AnnotationMismatch",
     "DiscordException",
     "ClientException",
     "NoMoreItems",
@@ -96,6 +97,8 @@ def __init__(self):
 class ValidationError(DiscordException):
     """An Exception that is raised when there is a Validation Error."""
 
+class AnnotationMismatch(SyntaxError, ValidationError):
+    """An Exception that is raised when an annotation does not match the type of the value."""
 
 def _flatten_error_dict(d: dict[str, Any], key: str = "") -> dict[str, str]:
     items: list[tuple[str, str]] = []

discord/gears/gear.py

@@ -38,6 +38,7 @@
 
 from ..app.event_emitter import Event
 from ..utils import MISSING, Undefined
+from ..utils.annotations import get_annotations
 from ..utils.private import hybridmethod
 
 _T = TypeVar("_T", bound="Gear")
@@ -152,11 +153,15 @@ def detach_gear(self, gear: "Gear") -> None:
     def _parse_listener_signature(
         callback: Callable[[E], Awaitable[None]], is_instance_function: bool = False
     ) -> type[E]:
-        params = list(inspect.signature(callback).parameters.values())
+        params = get_annotations(
+            callback,
+            expected_types={0: type(Event)},
+            custom_error="""Type annotation mismatch for parameter "{parameter}": expected <class 'Event'>, got {got}.\nEither change the signature of the callback or provide the event type explicitly with the "listen(event=Event)" parameter.""",
+        )
         if is_instance_function:
-            event = params[1].annotation
+            event = list(params.values())[1]
         else:
-            event = params[0].annotation
+            event = next(iter(params.values()))
         if issubclass(event, Event):
             return cast(type[E], event)
         raise TypeError("Could not infer event type from callback. Please provide the event type explicitly.")

discord/utils/annotations.py

@@ -0,0 +1,97 @@
+import functools
+import inspect
+from typing import Any, overload
+
+from ..errors import AnnotationMismatch
+
+
+def _unwrap_partial(func: Any) -> Any:
+    while isinstance(func, functools.partial):
+        func = func.func
+    return func
+
+
+@overload
+def get_annotations(
+    obj: Any,
+    *,
+    globals: dict[str, Any] | None = None,
+    locals: dict[str, Any] | None = None,
+    eval_str: bool = False,
+    expected_types: None = None,
+    custom_error: None = None,
+) -> dict[str, Any]: ...
+
+
+@overload
+def get_annotations(
+    obj: Any,
+    *,
+    globals: dict[str, Any] | None = None,
+    locals: dict[str, Any] | None = None,
+    eval_str: bool = False,
+    expected_types: dict[int, type],
+    custom_error: str | None = None,
+) -> dict[str, Any]: ...
+
+
+def get_annotations(
+    obj: Any,
+    *,
+    globals: dict[str, Any] | None = None,
+    locals: dict[str, Any] | None = None,
+    eval_str: bool = False,
+    expected_types: dict[int, type] | None = None,
+    custom_error: str | None = None,
+) -> dict[str, Any]:
+    unwrapped_obj = _unwrap_partial(obj)
+    r = inspect.get_annotations(unwrapped_obj, globals=globals, locals=locals, eval_str=eval_str)
+
+    if expected_types is not None:
+        for i, (k, v) in enumerate(r.items()):
+            if i in expected_types and not isinstance(v, expected_types[i]):
+                filename = unwrapped_obj.__code__.co_filename
+                source_lines, start_line = inspect.getsourcelines(unwrapped_obj)
+
+                param_line = start_line
+                param_text = ""
+                col_offset = 0
+                end_offset = -1
+
+                for j, line in enumerate(source_lines):
+                    if f"{k}:" in line:
+                        param_line = start_line + j
+                        param_text = line
+                        # Find column offset (position of parameter name)
+                        col_offset = line.find(k) + 1
+                        # calculate end offset by finding the next comma or closing parenthesis
+                        end_offset = line[col_offset:].find(",")
+                        if end_offset == -1:
+                            end_offset = line[col_offset:].find(")")
+                        if end_offset != -1:
+                            end_offset += col_offset + 1
+                        break
+
+                error = AnnotationMismatch(
+                    (
+                        custom_error
+                        or 'Type annotation mismatch for parameter "{parameter}": expected {expected}, got {got}'
+                    ).format(
+                        parameter=k,
+                        expected=repr(expected_types[i]),
+                        got=repr(r[k]),
+                    )
+                )
+                error.filename = filename
+                error.lineno = param_line
+                error.offset = col_offset
+                error.end_offset = end_offset
+                error.end_lineno = param_line
+                error.text = param_text
+
+                raise error
+
+    return r
+
+
+__all__ = ("get_annotations", "AnnotationMismatch")