feat: on_start event (#927)

* feat: add on_start event

* docs: document the event

Author: Toricane

docs/events.rst

@@ -51,6 +51,7 @@ All events mentioned in this section have the exact naming as they must be put i
 There are several different internal events:
 
     - ``raw_socket_create``
+    - ``on_start``
     - ``on_interaction``
     - ``on_command``
     - ``on_component``
@@ -70,6 +71,15 @@ The value of the argument will be the *raw* data sent from Discord, so it is not
 as long as you don't absolutely need it.
 
 
+Event: ``on_start``
+^^^^^^^^^^^^^^^^^^^
+This event fires only when the bot is started.
+
+This function takes no arguments.
+
+.. attention::
+    Unlike ``on_ready``, this event will never be dispatched more than once.
+
 Event: ``on_interaction``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 This event fires on any interaction (commands, components, autocomplete and modals).

interactions/api/gateway/client.py

@@ -80,6 +80,7 @@ class WebSocketClient:
         "__shard",
         "__presence",
         "__task",
+        "__started",
         "session_id",
         "sequence",
         "ready",
@@ -126,6 +127,7 @@ def __init__(
         self.__shard: Optional[List[Tuple[int]]] = None
         self.__presence: Optional[ClientPresence] = None
         self.__task: Optional[Task] = None
+        self.__started: bool = False
         self.session_id: Optional[str] = None if session_id is MISSING else session_id
         self.sequence: Optional[str] = None if sequence is MISSING else sequence
         self.ready: Event = Event(loop=self._loop) if version_info < (3, 10) else Event()
@@ -258,6 +260,9 @@ async def _handle_connection(
             self.session_id = data["session_id"]
             self.sequence = stream["s"]
             self._dispatch.dispatch("on_ready")
+            if not self.__started:
+                self.__started = True
+                self._dispatch.dispatch("on_start")
             log.debug(f"READY (session_id: {self.session_id}, seq: {self.sequence})")
             self.ready.set()
         else: