diff options
author | Vinay Sajip <vinay_sajip@yahoo.co.uk> | 2012-04-10 19:59:50 +0100 |
---|---|---|
committer | Vinay Sajip <vinay_sajip@yahoo.co.uk> | 2012-04-10 19:59:50 +0100 |
commit | d7b3eb5c57ff909bb6fd581dffdfd4709fd912d5 (patch) | |
tree | 9cb9a1ed524a26d9206eb266200338889687df45 /Doc | |
parent | baf4b330a80021f47adcf6ef89bbbfe15fd328d4 (diff) | |
download | cpython-d7b3eb5c57ff909bb6fd581dffdfd4709fd912d5.tar.gz |
Updated logging reference and HOWTO.
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/howto/logging.rst | 16 | ||||
-rw-r--r-- | Doc/library/logging.rst | 17 |
2 files changed, 31 insertions, 2 deletions
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index 2c9514a58d..44b2f59903 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -651,6 +651,22 @@ You can see that the config file approach has a few advantages over the Python code approach, mainly separation of configuration and code and the ability of noncoders to easily modify the logging properties. +.. warning:: The :func:`fileConfig` function takes a default parameter, + ``disable_existing_loggers``, which defaults to ``True`` for reasons of + backward compatibility. This may or may not be what you want, since it + will cause any loggers existing before the :func:`fileConfig` call to + be disabled unless they (or an ancestor) are explicitly named in the + configuration. Please refer to the reference documentation for more + information, and specify ``False`` for this parameter if you wish. + + The dictionary passed to :func:`dictConfig` can also specify a Boolean + value with key ``disable_existing_loggers``, which if not specified + explicitly in the dictionary also defaults to being interpreted as + ``True``. This leads to the logger-disabling behaviour described above, + which may not be what you want - in which case, provide the key + explicitly with a value of ``False``. + + .. currentmodule:: logging Note that the class names referenced in config files need to be either relative diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 1005b7975b..dc97726258 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -49,9 +49,22 @@ listed below. Logger Objects -------------- -Loggers have the following attributes and methods. Note that Loggers are never +Loggers have the following attributes and methods. Note that Loggers are never instantiated directly, but always through the module-level function -``logging.getLogger(name)``. +``logging.getLogger(name)``. Multiple calls to :func:`getLogger` with the same +name will always return a reference to the same Logger object. + +The ``name`` is potentially a period-separated hierarchical value, like +``foo.bar.baz`` (though it could also be just plain ``foo``, for example). +Loggers that are further down in the hierarchical list are children of loggers +higher up in the list. For example, given a logger with a name of ``foo``, +loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all +descendants of ``foo``. The logger name hierarchy is analogous to the Python +package hierarchy, and identical to it if you organise your loggers on a +per-module basis using the recommended construction +``logging.getLogger(__name__)``. That's because in a module, ``__name__`` +is the module's name in the Python package namespace. + .. class:: Logger |