Added Handler Id section.

pep-0391.txt

@@ -93,12 +93,14 @@ API
 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 @@ and the destination object with that id.
 
 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 @@ readable than the equivalent Python source form for the dictionary.)
 
 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 @@ The implementation will provide for a set of standard prefixes such as
 ``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 @@ Note: the ``ext`` and ``int`` prefixes are provisional.  If better
 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 @@ Incremental Configuration
 =========================
 
 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 @@ incomplete) list of conditions which will raise an error:
 
 * 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