From: Vinay Sajip Date: Tue, 10 Apr 2012 18:52:06 +0000 (+0100) Subject: Updated logging reference and HOWTO. X-Git-Tag: v2.7.4rc1~911^2~2^2~1 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2a1c13bb2d933f7166fd5739799a8f1543303e69;p=python Updated logging reference and HOWTO. --- diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index 029a0abf95..79e4dc9876 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -642,6 +642,21 @@ 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 665485d660..b4185c3b9d 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -51,9 +51,21 @@ 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