Add and remove some of the on_socket_* events.

on_socket_raw_receive and on_socket_raw_send were added back in an odd
way. The rest of them such as on_socket_closed, on_socket_opened, and
on_socket_receive were removed.

discord/client.py

@@ -147,6 +147,11 @@ class Client:
         filename = hashlib.md5(email.encode('utf-8')).hexdigest()
         return os.path.join(tempfile.gettempdir(), 'discord_py', filename)
 
+    @asyncio.coroutine
+    def _send_ws(self, data):
+        self.dispatch('socket_raw_send', data)
+        yield from self.ws.send(data)
+
     @asyncio.coroutine
     def _login_via_cache(self, email, password):
         try:
@@ -282,7 +287,7 @@ class Client:
 
                 msg = 'Keeping websocket alive with timestamp {}'
                 log.debug(msg.format(payload['d']))
-                yield from self.ws.send(utils.to_json(payload))
+                yield from self._send_ws(utils.to_json(payload))
                 yield from asyncio.sleep(interval)
         except asyncio.CancelledError:
             pass
@@ -302,6 +307,8 @@ class Client:
 
     @asyncio.coroutine
     def received_message(self, msg):
+        self.dispatch('socket_raw_receive', msg)
+
         if isinstance(msg, bytes):
             msg = zlib.decompress(msg, 15, 10490000) # This is 10 MiB
             msg = msg.decode('utf-8')
@@ -386,7 +393,7 @@ class Client:
                 }
             }
 
-            yield from self.ws.send(utils.to_json(payload))
+            yield from self._send_ws(utils.to_json(payload))
             log.info('sent the initial payload to create the websocket')
 
     @asyncio.coroutine
@@ -415,7 +422,7 @@ class Client:
         }
 
         log.info('sending reconnection frame to websocket {}'.format(payload))
-        yield from self.ws.send(utils.to_json(payload))
+        yield from self._send_ws(utils.to_json(payload))
 
     # login state management
 
@@ -1462,7 +1469,7 @@ class Client:
 
         sent = utils.to_json(payload)
         log.debug('Sending "{}" to change status'.format(sent))
-        yield from self.ws.send(sent)
+        yield from self._send_ws(sent)
 
     # Channel management
 
@@ -2431,7 +2438,7 @@ class Client:
             }
         }
 
-        yield from self.ws.send(utils.to_json(payload))
+        yield from self._send_ws(utils.to_json(payload))
         yield from asyncio.wait_for(self._session_id_found.wait(), timeout=5.0, loop=self.loop)
         yield from asyncio.wait_for(self._voice_data_found.wait(), timeout=5.0, loop=self.loop)
 

docs/api.rst

@@ -133,67 +133,41 @@ to handle it, which defaults to print a traceback and ignore the exception.
 
     :param message: A :class:`Message` of the current message.
 
-.. function:: on_socket_opened()
-
-    Called whenever the websocket is successfully opened. This is not the same thing as being ready.
-    For that, use :func:`on_ready`.
-
-.. function:: on_socket_closed()
-
-    Called whenever the websocket is closed, through an error or otherwise.
-
-.. function:: on_socket_update(event, data)
-
-    Called whenever a recognised websocket event is found. This function would normally be not be
-    called as there are higher level events in the library such as :func:`on_message`.
-
-    :param str event: The string of the event received. e.g. ``READY``.
-    :param data: The data associated with the socket event. Usually a ``dict``.
-
-.. function:: on_socket_response(response)
-
-    Called whenever a message is received from the websocket. Used mainly for debugging purposes.
-    The parameter passed is raw data that was parsed via ``json.loads``. Note that this is called
-    before the :class:`Client` processes the event.
-
-    :param response: The received message response after gone through ``json.loads``.
-
 .. function:: on_socket_raw_receive(msg)
 
     Called whenever a message is received from the websocket, before
-    it's processed. Unlike ``on_socket_response`` this event is always
+    it's processed.This event is always dispatched when a message is
-    dispatched when a message is received and the passed data is not
+    received and the passed data is not processed in any way.
-    processed in any way.
 
-    This is only really useful for grabing the websocket stream and
+    This is only really useful for grabbing the websocket stream and
     debugging purposes.
 
-    :param msg: The message passed on from the ws4py library. Can be an
+    .. note::
-        instance of either ws4py.messaging.TextMessage, or
+
-        ws4py.messaging.BinaryMessage.
+        This is only for the messages received from the client
+        websocket. The voice websocket will not trigger this event.
+
+    :param msg: The message passed in from the websocket library.
+                Could be ``bytes`` for a binary message or ``str``
+                for a regular message.
 
-.. function:: on_socket_raw_send(payload, binary=False)
+.. function:: on_socket_raw_send(payload)
 
     Called whenever a send operation is done on the websocket before the
     message is sent. The passed parameter is the message that is to
     sent to the websocket.
 
-    This is only really useful for grabing the websocket stream and
+    This is only really useful for grabbing the websocket stream and
     debugging purposes.
 
     .. note::
 
-        If the ``payload`` parameter is mutable, and modified during the
+        This is only for the messages received from the client
-        execution of this event, then the actual data sent out on the
+        websocket. The voice websocket will not trigger this event.
-        websocket will be mangled. This is especially true if
-        ``payload`` is a generator, as reading them modifies their
-        state.
 
     :param payload: The message that is about to be passed on to the
-        ws4py library. It can be any of a string, a bytearray, an
+                    websocket library. It can be ``bytes`` to denote a binary
-        instance of ws4py.message.Message and a generator.
+                    message or ``str`` to denote a regular text message.
-    :param bool binary: True if the message being sent out is marked as
-        binary.
 
 .. function:: on_message_delete(message)
               on_message_edit(before, after)

docs/migrating.rst

@@ -79,6 +79,7 @@ Before:
     def on_status(member): pass
     def on_server_role_update(role): pass
     def on_voice_state_update(member): pass
+    def on_socket_raw_send(payload, is_binary): pass
 
 
 After:
@@ -89,9 +90,10 @@ After:
     def on_member_update(before, after): pass
     def on_server_role_update(before, after): pass
     def on_voice_state_update(before, after): pass
+    def on_socket_raw_send(payload): pass
 
 Note that ``on_status`` was removed. If you want its functionality, use :func:`on_member_update`.
-See :ref:`discord-api-events` for more information.
+See :ref:`discord-api-events` for more information. Other removed events include ``on_socket_closed``, ``on_socket_receive``, and ``on_socket_opened``.
 
 
 .. _migrating-coroutines: