Add shard related connection and resume events.

These include:
* on_shard_resumed
* on_shard_connect
* on_shard_disconnect

4 files changed, 41 insertions, 0 deletions

diff --git a/discord/gateway.py b/discord/gateway.py
index db3c7fd5..3f92ec1f 100644
--- a/discord/gateway.py
+++ b/discord/gateway.py
@@ -438,11 +438,15 @@ class DiscordWebSocket:
             self._trace = trace = data.get('_trace', [])
             self.sequence = msg['s']
             self.session_id = data['session_id']
+            # pass back shard ID to ready handler
+            data['__shard_id__'] = self.shard_id
             log.info('Shard ID %s has connected to Gateway: %s (Session ID: %s).',
                      self.shard_id, ', '.join(trace), self.session_id)
 
         elif event == 'RESUMED':
             self._trace = trace = data.get('_trace', [])
+            # pass back the shard ID to the resumed handler
+            data['__shard_id__'] = self.shard_id
             log.info('Shard ID %s has successfully RESUMED session %s under trace %s.',
                      self.shard_id, self.session_id, ', '.join(trace))
 
diff --git a/discord/shard.py b/discord/shard.py
index 0b037398..dfa3849c 100644
--- a/discord/shard.py
+++ b/discord/shard.py
@@ -104,6 +104,7 @@ class Shard:
 
     async def _handle_disconnect(self, e):
         self._dispatch('disconnect')
+        self._dispatch('shard_disconnect', self.id)
         if not self._reconnect:
             self._queue.put_nowait(EventItem(EventType.close, self, e))
             return
@@ -136,6 +137,7 @@ class Shard:
     async def reidentify(self, exc):
         self._cancel_task()
         self._dispatch('disconnect')
+        self._dispatch('shard_disconnect', self.id)
         log.info('Got a request to %s the websocket at Shard ID %s.', exc.op, self.id)
         try:
             coro = DiscordWebSocket.from_client(self._client, resume=exc.resume, shard_id=self.id,
diff --git a/discord/state.py b/discord/state.py
index 8b793c20..10403032 100644
--- a/discord/state.py
+++ b/discord/state.py
@@ -1142,5 +1142,10 @@ class AutoShardedConnectionState(ConnectionState):
             self._add_private_channel(factory(me=user, data=pm, state=self))
 
         self.dispatch('connect')
+        self.dispatch('shard_connect', data['__shard_id__'])
         if self._ready_task is None:
             self._ready_task = asyncio.ensure_future(self._delay_ready(), loop=self.loop)
+
+    def parse_resumed(self, data):
+        self.dispatch('resumed')
+        self.dispatch('shard_resumed', data['__shard_id__'])
diff --git a/docs/api.rst b/docs/api.rst
index 5469f9b8..601a6c01 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -117,6 +117,16 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     The warnings on :func:`on_ready` also apply.
 
+.. function:: on_shard_connect(shard_id)
+
+    Similar to :func:`on_connect` except used by :class:`AutoShardedClient`
+    to denote when a particular shard ID has connected to Discord.
+
+    .. versionadded:: 1.4
+
+    :param shard_id: The shard ID that has connected.
+    :type shard_id: :class:`int`
+
 .. function:: on_disconnect()
 
     Called when the client has disconnected from Discord. This could happen either through
@@ -125,6 +135,16 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     This function can be called many times.
 
+.. function:: on_shard_disconnect(shard_id)
+
+    Similar to :func:`on_disconnect` except used by :class:`AutoShardedClient`
+    to denote when a particular shard ID has disconnected from Discord.
+
+    .. versionadded:: 1.4
+
+    :param shard_id: The shard ID that has disconnected.
+    :type shard_id: :class:`int`
+
 .. function:: on_ready()
 
     Called when the client is done preparing the data received from Discord. Usually after login is successful
@@ -149,6 +169,16 @@ to handle it, which defaults to print a traceback and ignoring the exception.
 
     Called when the client has resumed a session.
 
+.. function:: on_shard_resumed(shard_id)
+
+    Similar to :func:`on_resumed` except used by :class:`AutoShardedClient`
+    to denote when a particular shard ID has resumed a session.
+
+    .. versionadded:: 1.4
+
+    :param shard_id: The shard ID that has resumed.
+    :type shard_id: :class:`int`
+
 .. function:: on_error(event, \*args, \*\*kwargs)
 
     Usually when an event raises an uncaught exception, a traceback is