diff options
| -rw-r--r-- | Doc/library/logging.rst | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 247725ee6a..ee1bc84415 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -593,6 +593,22 @@ decides to actually dispatch an event, the :meth:`emit` method is used to send the message to its destination. Most user-defined subclasses of :class:`Handler` will need to override this :meth:`emit`. +.. _custom-levels: + +Custom Levels +^^^^^^^^^^^^^ + +Defining your own levels is possible, but should not be necessary, as the +existing levels have been chosen on the basis of practical experience. +However, if you are convinced that you need custom levels, great care should +be exercised when doing this, and it is possibly *a very bad idea to define +custom levels if you are developing a library*. That's because if multiple +library authors all define their own custom levels, there is a chance that +the logging output from such multiple libraries used together will be +difficult for the using developer to control and/or interpret, because a +given numeric value might mean different things for different libraries. + + Useful Handlers --------------- @@ -792,6 +808,14 @@ functions. Logs a message with level *level* on the root logger. The other arguments are interpreted as for :func:`debug`. + PLEASE NOTE: The above module-level functions which delegate to the root + logger should *not* be used in threads, in versions of Python earlier than + 2.7.1 and 3.2, unless at least one handler has been added to the root + logger *before* the threads are started. These convenience functions call + :func:`basicConfig` to ensure that at least one handler is available; in + earlier versions of Python, this can (under rare circumstances) lead to + handlers being added multiple times to the root logger, which can in turn + lead to multiple messages for the same event. .. function:: disable(lvl) @@ -813,6 +837,8 @@ functions. registered using this function, levels should be positive integers and they should increase in increasing order of severity. + NOTE: If you are thinking of defining your own levels, please see the section + on :ref:`custom-levels`. .. function:: getLevelName(lvl) @@ -847,6 +873,13 @@ functions. .. versionchanged:: 2.4 Formerly, :func:`basicConfig` did not take any keyword arguments. + PLEASE NOTE: This function should be called from the main thread + before other threads are started. In versions of Python prior to + 2.7.1 and 3.2, if this function is called from multiple threads, + it is possible (in rare circumstances) that a handler will be added + to the root logger more than once, leading to unexpected results + such as messages being duplicated in the log. + The following keyword arguments are supported. +--------------+---------------------------------------------+ |