[Python-checkins] r75916 - peps/trunk/pep-0391.txt

Wed Oct 28 11:10:57 CET 2009

Author: vinay.sajip
Date: Wed Oct 28 11:10:57 2009
New Revision: 75916
Log:
Added Handler Id section.
Modified:
 peps/trunk/pep-0391.txt
Modified: peps/trunk/pep-0391.txt
==============================================================================

--- peps/trunk/pep-0391.txt	(original)
+++ peps/trunk/pep-0391.txt	Wed Oct 28 11:10:57 2009
@@ -93,12 +93,14 @@
 The logging.config module will have the following additions:
 
 * A function, called ``dictConfig()``, which takes a single argument
- - the dictionary holding the configuration. Nothing will be
- returned, though exceptions will be raised if there are errors
- while processing the dictionary.
+ - the dictionary holding the configuration. Nothing will be
+ returned, though exceptions will be raised if there are errors while
+ processing the dictionary.
 
 It will be possible to customize this API - see the section on `API
-Customization`_.
+Customization`_. `Incremental configuration`_ is covered in its own
+section.
+
 
 Dictionary Schema - Overview
 ----------------------------
@@ -127,11 +129,18 @@
 
 So, for example, consider the following YAML snippet::
 
+ formatters:
+ brief:
+ # configuration for formatter with id 'brief' goes here
+ precise:
+ # configuration for formatter with id 'precise' goes here
 handlers:
 h1: #This is an id
- # configuration of handler with id h1 goes here
+ # configuration of handler with id 'h1' goes here
+ formatter: brief
 h2: #This is another id
- # configuration of handler with id h2 goes here
+ # configuration of handler with id 'h2' goes here
+ formatter: precise 
 loggers:
 foo.bar.baz:
 # other configuration for logger 'foo.bar.baz'
@@ -142,15 +151,20 @@
 
 The ids for loggers are the logger names which would be used
 programmatically to obtain a reference to those loggers, e.g.
-``foo.bar.baz``. The ids for other objects can be any string value
-(such as ``h1``, ``h2`` above) and they are transient, in that they
-are only meaningful for processing the configuration dictionary and
-used to determine connections between objects, and are not persisted
-anywhere when the configuration call is complete.
+``foo.bar.baz``. The ids for Formatters and Filters can be any string
+value (such as ``brief``, ``precise`` above) and they are transient,
+in that they are only meaningful for processing the configuration
+dictionary and used to determine connections between objects, and are
+not persisted anywhere when the configuration call is complete.
+
+Handler ids are treated specially, see the section on
+`Handler Ids`_, below. 
 
 The above snippet indicates that logger named ``foo.bar.baz`` should
 have two handlers attached to it, which are described by the handler
-ids ``h1`` and ``h2``.
+ids ``h1`` and ``h2``. The formatter for ``h1`` is that described by id
+``brief``, and the formatter for ``h2`` is that described by id
+``precise``.
 
 
 User-defined objects
@@ -260,6 +274,7 @@
 ``ext://`` but it will be possible to disable the mechanism completely
 or provide additional or different prefixes for special handling.
 
+
 Access to internal objects
 ''''''''''''''''''''''''''
 
@@ -334,6 +349,35 @@
 alternatives are suggested during the PEP review process, they will be
 used.
 
+
+Handler Ids
+'''''''''''
+
+Some specific logging configurations require the use of handler levels
+to achieve the desired effect. However, unlike loggers which can
+always be identified by their names, handlers have no persistent
+handles whereby levels can be changed via an incremental configuration
+call.
+
+Therefore, this PEP proposes to add an optional ``name`` property to
+handlers. If used, this will add an entry in a dictionary which maps
+the name to the handler. (The entry will be removed when the handler
+is closed.) When an incremental configuration call is made, handlers
+will be looked up in this dictionary to set the handler level
+according to the value in the configuration. See the section on
+`incremental configuration`_ for more details.
+
+In theory, such a "persistent name" facility could also be provided
+for Filters and Formatters. However, there is not a strong case to be
+made for being able to configure these incrementally. On the basis
+that practicality beats purity, only Handlers will be given this new
+``name`` property. The id of a handler in the configuration will
+become its ``name``.
+
+The handler name lookup dictionary is for configuration use only and
+will not become part of the public API for the package.
+
+
 Dictionary Schema - Detail
 --------------------------
 
@@ -500,25 +544,22 @@
 =========================
 
 It is difficult to provide complete flexibility for incremental
-configuration. For example, because objects such as handlers, filters
+configuration. For example, because objects such as filters
 and formatters are anonymous, once a configuration is set up, it is
 not possible to refer to such anonymous objects when augmenting a
-configuration. For example, if an initial call is made to configure
-the system where logger ``foo`` has a handler with id ``console``
-attached, then a subsequent call to configure a logger ``bar`` with id
-``console`` would create a new handler instance, as the id ``console``
-from the first call isn't kept.
+configuration.
 
 Furthermore, there is not a compelling case for arbitrarily altering
 the object graph of loggers, handlers, filters, formatters at
-run-time, once a configuration is set up; the verbosity of loggers can
-be controlled just by setting levels (and perhaps propagation flags).
+run-time, once a configuration is set up; the verbosity of loggers and
+handlers can be controlled just by setting levels (and, in the case of
+loggers, propagation flags).
 
 Thus, when the ``incremental`` key of a configuration dict is present
-and is ``True``, the system will ignore any ``formatters``,
-``filters``, ``handlers`` entries completely, and process only the
-``level`` and ``propagate`` settings in the ``loggers`` and ``root``
-entries.
+and is ``True``, the system will ignore any ``formatters`` and
+``filters``, entries completely, and process only the ``level``
+settings in the ``handlers`` entries, and the ``level`` and
+``propagate`` settings in the ``loggers`` and ``root`` entries.
 
 It's certainly possible to provide incremental configuration by other
 means, for example making ``dictConfig()`` take an ``incremental``
@@ -579,6 +620,8 @@
 
 * An id which does not have a corresponding destination
 
+* A non-existent handler id found during an incremental call
+
 * An invalid logger name
 
 * Inability to resolve to an internal or external object
