[Python-checkins] cpython (2.7): Updated logging reference and HOWTO.

[vinay.sajip]

http://hg.python.org/cpython/rev/5a4c78fc416d
changeset:   76215:5a4c78fc416d
branch:      2.7
parent:      76210:9b9675995e29
user:        Vinay Sajip <vinay_sajip at yahoo.co.uk>
date:        Tue Apr 10 19:52:06 2012 +0100
summary:
  Updated logging reference and HOWTO.

files:
  Doc/howto/logging.rst   |  15 +++++++++++++++
  Doc/library/logging.rst |  16 ++++++++++++++--
  2 files changed, 29 insertions(+), 2 deletions(-)


diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -642,6 +642,21 @@
 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
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -51,9 +51,21 @@
 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
 

-- 
Repository URL: http://hg.python.org/cpython