From e50f4d2220c22cc84208ba3f1702ffa4e9df6196 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Mon, 7 Jan 2013 14:16:52 +0000 Subject: [PATCH] Issue #16884: updated logging documentation to include lastResort and use 'note' directives where appropriate. --- Doc/howto/logging.rst | 15 +++++++------- Doc/library/logging.rst | 43 +++++++++++++++++++++++++++-------------- 2 files changed, 37 insertions(+), 21 deletions(-) diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index 44b2f59903..1e8b662db4 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -780,13 +780,14 @@ should have the desired effect. If an organisation produces a number of libraries, then the logger name specified can be 'orgname.foo' rather than just 'foo'. -**PLEASE NOTE:** It is strongly advised that you *do not add any handlers other -than* :class:`~logging.NullHandler` *to your library's loggers*. This is -because the configuration of handlers is the prerogative of the application -developer who uses your library. The application developer knows their target -audience and what handlers are most appropriate for their application: if you -add handlers 'under the hood', you might well interfere with their ability to -carry out unit tests and deliver logs which suit their requirements. +.. note:: It is strongly advised that you *do not add any handlers other + than* :class:`~logging.NullHandler` *to your library's loggers*. This is + because the configuration of handlers is the prerogative of the application + developer who uses your library. The application developer knows their + target audience and what handlers are most appropriate for their + application: if you add handlers 'under the hood', you might well interfere + with their ability to carry out unit tests and deliver logs which suit their + requirements. Logging Levels diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index b6622e3ead..7a9db728fb 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -928,14 +928,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. + .. 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) @@ -991,12 +991,12 @@ functions. This function does nothing if the root logger already has handlers configured for it. - 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. + .. 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. @@ -1080,6 +1080,21 @@ functions. :kwargs: Additional keyword arguments. +Module-Level Attributes +----------------------- + +.. attribute:: lastResort + + A "handler of last resort" is available through this attribute. This + is a :class:`StreamHandler` writing to ``sys.stderr`` with a level of + ``WARNING``, and is used to handle logging events in the absence of any + logging configuration. The end result is to just print the message to + ``sys.stderr``. This replaces the earlier error message saying that + "no handlers could be found for logger XYZ". If you need the earlier + behaviour for some reason, ``lastResort`` can be set to ``None``. + + .. versionadded:: 3.2 + Integration with the warnings module ------------------------------------ -- 2.40.0