From 1356583428c9fd2c3917b0e6d2f64d08a24bff5d Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Thu, 26 Nov 2009 07:57:39 +0000 Subject: [PATCH] Updated to incorporate suggestions made by Terry Reedy. --- pep-0391.txt | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/pep-0391.txt b/pep-0391.txt index 83fa69d68..acbdc2307 100644 --- a/pep-0391.txt +++ b/pep-0391.txt @@ -51,11 +51,11 @@ considered an integral part of the application configuration. Although the standard library does not contain YAML support at present, support for both JSON and YAML can be provided in a common way because both of these serialization formats allow deserialization -of Python dictionaries. +to Python dictionaries. By providing a way to configure logging by passing the configuration in a dictionary, logging will be easier to configure not only for -users of JSON and/or YAML, but also for users of bespoke configuration +users of JSON and/or YAML, but also for users of custom configuration methods, by providing a common format in which to describe the desired configuration. @@ -90,12 +90,11 @@ used by logging. API --- -The logging.config module will have the following additions: +The logging.config module will have the following addition: * 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. 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`_. `Incremental configuration`_ is covered in its own @@ -117,7 +116,7 @@ The schema is intended to describe a set of logging objects - loggers, handlers, formatters, filters - which are connected to each other in an object graph. Thus, the schema needs to represent connections between the objects. For example, say that, once configured, a -particular logger has an attached to it a particular handler. For the +particular logger has attached to it a particular handler. For the purposes of this discussion, we can say that the logger represents the source, and the handler the destination, of a connection between the two. Of course in the configured objects this is represented by the @@ -183,8 +182,9 @@ the system will not know how to do this. In order to provide complete flexibility for user-defined object instantiation, the user will need to provide a 'factory' - a callable which is called with a configuration dictionary and which returns the instantiated object. -This will be signalled by the factory being made available under the -special key ``'()'``. Here's a concrete example:: +This will be signalled by an absolute import path to the factory being +made available under the special key ``'()'``. Here's a concrete +example:: formatters: brief: @@ -232,10 +232,13 @@ configuration sub-dictionary for the third formatter, with id and this contains the special key ``'()'``, which means that user-defined instantiation is wanted. In this case, the specified -factory callable will be located using normal import mechanisms and -called with the *remaining* items in the configuration sub-dictionary -as keyword arguments. In the above example, the formatter with id -``custom`` will be assumed to be returned by the call:: +factory callable will be used. If it is an actual callable it will be +used directly - otherwise, if you specify a string (as in the example) +the actual callable will be located using normal import mechanisms. +The callable will be called with the *remaining* items in the +configuration sub-dictionary as keyword arguments. In the above +example, the formatter with id ``custom`` will be assumed to be +returned by the call:: my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42) @@ -618,7 +621,7 @@ The existing socket listener implementation will be modified as follows: when a configuration message is received, an attempt will be made to deserialize to a dictionary using the json module. If this step fails, the message will be assumed to be in the fileConfig format -and processed as before. If serialization is successful, then +and processed as before. If deserialization is successful, then ``dictConfig()`` will be called to process the resulting dictionary.