feat: add once kwarg to Cog.listener (#2403)

* add once kwarg to Cog.listener

* clarify

* style(pre-commit): auto fixes from pre-commit.com hooks

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Lala Sabathil <[email protected]>

Author: 3 people

discord/cog.py

@@ -379,7 +379,9 @@ def _get_overridden_method(cls, method: FuncT) -> FuncT | None:
         )
 
     @classmethod
-    def listener(cls, name: str = MISSING) -> Callable[[FuncT], FuncT]:
+    def listener(
+        cls, name: str = MISSING, once: bool = False
+    ) -> Callable[[FuncT], FuncT]:
         """A decorator that marks a function as a listener.
 
         This is the cog equivalent of :meth:`.Bot.listen`.
@@ -389,6 +391,9 @@ def listener(cls, name: str = MISSING) -> Callable[[FuncT], FuncT]:
         name: :class:`str`
             The name of the event being listened to. If not provided, it
             defaults to the function's name.
+        once: :class:`bool`
+            If this listener should only be called once after each cog load.
+            Defaults to false.
 
         Raises
         ------
@@ -411,6 +416,7 @@ def decorator(func: FuncT) -> FuncT:
                 raise TypeError("Listener function must be a coroutine function.")
             actual.__cog_listener__ = True
             to_assign = name or actual.__name__
+            actual._once = once
             try:
                 actual.__cog_listener_names__.append(to_assign)
             except AttributeError: