From 1f37fe72f245b8e92cffce3c0d65614b731a81be Mon Sep 17 00:00:00 2001 From: Rapptz Date: Tue, 13 Oct 2015 05:38:38 -0400 Subject: [PATCH] Documentation cleanup. Documented the new way of listening to events as well the new events that could be listened thanks to the recent refactor. Also uses the versionadded directive to document when something new is added to the library. --- docs/api.rst | 43 +++++++++++++++++++++++++++++++++++-------- docs/logging.rst | 5 +++-- 2 files changed, 38 insertions(+), 10 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 6da78bb50..d796c3b17 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 80b15273f..6490f9fae 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.