matthew/enhanced-discord.py
1
0
Fork 0
Code Issues 4 Pull Requests 21 Projects Releases Wiki Activity

Clarify logging and on_error documentation

Browse Source 
Change the description of on_error to reflect that exceptions are logged
and not output by default. Add a note about not configuring logging
causing exceptions to be silently ignored in handlers in the API. And
add some more explanations and a simpler configuration example to the
logging description.
This commit is contained in:
Hornwitser
2015-09-30 21:00:23 +02:00
parent ea2f35fb24
commit e258c9b893
2 changed files with 47 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/api.rst
View File

@@ -17,9 +17,18 @@ Client
Event Reference
~~~~~~~~~~~~~~~~
This page outlines the different types of events listened to by :meth:`Client.event`.
All events are 'sandboxed', in that if an exception is thrown while the event is called then it is caught and propagated to :func:`on_error`.
This page outlines the different types of events listened to by
:meth:`Client.event`.
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.
.. 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
set up and use the logging module with discord.py.
.. function:: on_ready()
@@ -32,21 +41,20 @@ All events are 'sandboxed', in that if an exception is thrown while the event is
.. function:: on_error(event, \*args, \*\*kwargs)
Usually when an event throws an uncaught exception, a traceback is
printed to stderr and the exception is ignored. If you want to
change this behaviour and handle the uncaught exception for whatever
reason, this event can be overridden. The default behaviour for
on_error is printing a traceback and then ignoring the exception,
but defining an on_error handler will supress this behaviour.
Usually when an event raises an uncaught exception, a traceback is
logged and the exception is ignored. If you want to change this
behaviour and handle the exception for whatever reason yourself,
this event can be overridden. Which, when done, will supress the
default logging done.
The information of the exception rasied and the exception itself can
be retreived with a standard call to ``sys.exc_info()``.
If you want exception to propogate out of the :class:`Client` class
you can define an ``on_error`` handler consisting of a single empty
``raise`` statement. Exceptions raised by ``on_error`` will not be
handled in any way by :class:`Client`.
The information of the exception rasied can be retreived with a
standard call to ``sys.exc_info()``.
:param event: The name of the event that raised the exception.
:param args: The positional arguments for the event that raised the
exception.