diff options
| -rw-r--r-- | docs/api.rst | 43 | ||||
| -rw-r--r-- | docs/logging.rst | 5 |
2 files changed, 38 insertions, 10 deletions
diff --git a/docs/api.rst b/docs/api.rst index 6da78bb5..d796c3b1 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -17,28 +17,38 @@ Client Event Reference ~~~~~~~~~~~~~~~~ -This page outlines the different types of events listened to by -:meth:`Client.event`. +This page outlines the different types of events listened by :class:`Client`. + +There are two ways to register an event, the first way is through the use of +:meth:`Client.event`. The second way is through subclassing :class:`Client` and +overriding the specific events. For example: :: + + import discord + + class MyClient(discord.Client): + def on_message(self, message): + self.send_message(message.channel, 'Hello World!') + If an event handler raises an exception, :func:`on_error` will be called to handle it, which defaults to log a traceback and ignore the exception. +.. versionadded:: 0.7.0 + Subclassing to listen to events. + .. note:: If the Python logging module is not configured, the logs will not be output anywhere. Meaning that exceptions in handlers will be - silently ignored. See :ref:`logging` for more information on how to + silently ignored. See :ref:`logging_setup` for more information on how to set up and use the logging module with discord.py. + .. function:: on_ready() Called when the client is done preparing the data received from Discord. Usually after login is successful and the :attr:`Client.servers` and co. are filled up. -.. function:: on_disconnect() - - Called when the client disconnects for whatever reason. Be it error or manually. - .. function:: on_error(event, \*args, \*\*kwargs) Usually when an event raises an uncaught exception, a traceback is @@ -67,7 +77,24 @@ to handle it, which defaults to log a traceback and ignore the exception. :param message: A :class:`Message` of the current message. -.. function:: on_response(response) +.. 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 diff --git a/docs/logging.rst b/docs/logging.rst index 80b15273..6490f9fa 100644 --- a/docs/logging.rst +++ b/docs/logging.rst @@ -1,3 +1,6 @@ +.. versionadded:: 0.6.0 +.. _logging_setup: + Setting Up Logging =================== @@ -36,9 +39,7 @@ This is recommended, especially at verbose levels such as ``INFO``, and ``DEBUG`` as there are a lot of events logged and it would clog the stdout of your program. -.. note:: - The logging facilities were added in version 0.6 of discord.py. For more information, check the documentation and tutorial of the `logging`_ module. |