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

[vinay.sajip]

Author: vinay.sajip
Date: Tue Oct 20 10:11:52 2009
New Revision: 75553

Log:
Added section on internal objects, and did some miscellaneous tidying up.

Modified:
   peps/trunk/pep-0391.txt

Modified: peps/trunk/pep-0391.txt
==============================================================================
--- peps/trunk/pep-0391.txt	(original)
+++ peps/trunk/pep-0391.txt	Tue Oct 20 10:11:52 2009
@@ -116,7 +116,7 @@
 
 Before describing the schema in detail, it is worth saying a few words
 about object connections, support for user-defined objects and access
-to external objects.
+to external and internal objects.
 
 
 Object connections
@@ -145,11 +145,11 @@
        # configuration of handler with id h2 goes here
     loggers:
       foo.bar.baz:
-        # other configuration for logger "foo.bar.baz"
+        # other configuration for logger 'foo.bar.baz'
         handlers: [h1, h2]
 
-(Note: YAML will be used in this document as it is more readable than
-the equivalent Python source form for the dictionary.)
+(Note: YAML will be used in this document as it is a little more
+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.
@@ -234,7 +234,7 @@
 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)
+    my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)
 
 The key ``'()'`` has been used as the special key because it is not a
 valid keyword parameter name, and so will not clash with the names of
@@ -271,6 +271,68 @@
 ``ext://`` but it will be possible to disable the mechanism completely
 or provide additional or different prefixes for special handling.
 
+Access to internal objects
+''''''''''''''''''''''''''
+
+As well as external objects, there is sometimes also a need to refer
+to objects in the configuration.  This will be done implicitly by the
+configuration system for things that it knows about.  For example, the
+string value ``'DEBUG'`` for a ``level`` in a logger or handler will
+automatically be converted to the value ``logging.DEBUG``, and the
+``handlers``, ``filters`` and ``formatter`` entries will take an
+object id and resolve to the appropriate destination object.
+
+However, a more generic mechanism needs to be provided for the case
+of user-defined objects which are not known to logging.  For example,
+take the instance of ``logging.handlers.MemoryHandler``, which takes
+a ``target`` which is another handler to delegate to. Since the system
+already knows about this class, then in the configuration, the given
+``target`` just needs to be the object id of the relevant target
+handler, and the system will resolve to the handler from the id.  If,
+however, a user defines a ``my.package.MyHandler`` which has a
+``alternate`` handler, the configuration system would not know that
+the ``alternate`` referred to a handler.  To cater for this, a
+generic resolution system will be provided which allows the user to
+specify::
+
+    handlers:
+      file:
+        # configuration of file handler goes here
+        
+      custom:
+        (): my.package.MyHandler
+        alternate: int://handlers.file
+
+The literal string ``'int://handlers.file'`` will be resolved in an
+analogous way to the strings with the ``ext://`` prefix, but looking
+in the configuration itself rather than the import namespace.  The
+mechanism will allow access by dot or by index, in a similar way to
+that provided by ``str.format``.  Thus, given the following snippet::
+
+    handlers:
+      email:
+        class: logging.handlers.SMTPHandler
+        mailhost: localhost
+        fromaddr: my_app at domain.tld
+        toaddrs:
+          - support_team at domain.tld
+          - dev_team at domain.tld
+        subject: Houston, we have a problem.
+
+in the configuration, the string ``'int://handlers'`` would resolve to
+the dict with key ``handlers``, the string ``'int://handlers.email``
+would resolve to the dict with key ``email`` in the ``handlers`` dict,
+and so on.  The string ``'int://handlers.email.toaddrs[1]`` would
+resolve to ``'dev_team.domain.tld'`` and the string
+``'int://handlers.email.toaddrs[0]'`` would resolve to the value
+``'support_team at domain.tld'``. The ``subject`` value could be accessed
+using either ``'int://handlers.email.subject'`` or, equivalently,
+``'int://handlers.email[subject]'``.  The latter form only needs to be
+used if the key contains spaces or non-alphanumeric characters.  If an
+index value consists only of decimal digits, access will be attempted
+using the corresponding integer value, falling back to the string
+value if needed.
+
 
 Dictionary Schema - Detail
 --------------------------
@@ -344,7 +406,7 @@
   ``logging.StreamHandler``, using ``sys.stdout`` as the underlying
   stream.  The handler with id ``file`` is instantiated as a
   ``logging.handlers.RotatingFileHandler`` with the keyword arguments
-  ``filename="logconfig.log", maxBytes=1024, backupCount=3``.
+  ``filename='logconfig.log', maxBytes=1024, backupCount=3``.
 
 * `loggers` - the corresponding value will be a dict in which each key
   is a logger name and each value is a dict describing how to
@@ -453,7 +515,7 @@
 be controlled just by setting levels (and perhaps propagation flags).
 
 Thus, when the ``incremental`` key of a configuration dict is present
-and is ``True``, the system will ignore the ``formatters``,
+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.
@@ -463,9 +525,9 @@
 ====================
 
 If an error is encountered during configuration, the system will raise
-a ``ValueError`` or a ``TypeError`` with a suitably descriptive
-message.  The following is a (possibly incomplete) list of conditions
-which will raise an error:
+a ``ValueError``,``TypeError``, ``AttributeError`` or ``ImportError``
+with a suitably descriptive message.  The following is a (possibly
+incomplete) list of conditions which will raise an error:
 
 * A ``level`` which is not a string or which is a string not
   corresponding to an actual logging level
@@ -476,6 +538,7 @@
 
 * An invalid logger name
 
+* Inability to resolve to an internal or external object
 
 References
 ==========