Add @consume_event decorator

docs/source/api_references/events.rst

@@ -0,0 +1,6 @@
+====================
+Events API Reference
+====================
+
+.. automodule:: toolbox.events
+   :members:

requirements.txt

@@ -1 +1,2 @@
-hikari>=2.0.0.dev113
+hikari>=2.0.0.dev113
+typing_extensions>=4.4.0

toolbox/__init__.py

@@ -1,5 +1,6 @@
 from .commands import *
 from .errors import *
+from .events import *
 from .members import *
 from .messages import *
 from .roles import *

toolbox/events.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import typing as t
+import typing_extensions as te
+
+import hikari
+import functools
+
+__all__: t.Sequence[str] = ["consume_event"]
+
+P = te.ParamSpec("P")
+T = t.TypeVar("T")
+
+
+def consume_event(
+    callback: t.Callable[P, t.Awaitable[T]]
+) -> t.Callable[te.Concatenate[hikari.Event, P], t.Awaitable[T]]:
+    """
+    Consume the first argument of an event callback.
+
+    .. code-block:: python
+
+        import hikari
+        import toolbox
+
+        @toolbox.consume_event
+        async def on_started():
+            ...
+
+        bot = hikari.GatewayBot("TOKEN")
+        bot.subscribe(hikari.StartingEvent, on_started)
+        bot.run()
+    """
+
+    @functools.wraps(callback)
+    async def inner(_event: hikari.Event, /, *args: P.args, **kwargs: P.kwargs) -> T:
+        return await callback(*args, **kwargs)
+
+    return inner