Package XPyLIB :: Module xlogging
[hide private]
[frames] | no frames]

Module xlogging

source code

Some extensions for Python logging package.

This module import standart Python logging namespace " from logging import * ", and you may use only xlogging for most usual targets.

Logging config file format.

Logging file format like config format in python logging package, but have some differents.

The file must contain main sections called [loggers], [handlers], [filters] and [formatters] which identify by name the entities of each type which are defined in the file. For each such entity, there is a separate entity section which identified how that entity is configured. Thus, for a logger named log01 in the [loggers] section, the relevant configuration details are held in a section [logger_log01]. Similarly, a handler called hand01 in the [handlers] section will have its configuration held in a section called [handler_hand01], while a formatter called form01 in the [formatters] section will have its configuration specified in a section called [formatter_form01]. The root logger configuration must be specified in a entity section called [logger_root]. The manager section configure loggers manager. Available only one option: "disable". (It as logging.disable() function). This section and option are optional.

In main sections you must use option keys (it mandatory): Examples of these sections in the file are given below.:
   [manager]
   disable=WARNING
   
   [loggers]
   keys=root, log02, log03
   
   [handlers]
   keys=hand01, hand02, hand03, hand04
   
   [formatters]
   keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
   
   [filters]
   keys=filt01, filt02, filt03
The entity sections may contains actions option. In this option may be listed action's names (it is a options's names with description of action). Each action entity have next format:
   act01=command, objecttype, arg01, arg02, ...
where:

For entity's sections logger_??? and handler_??? you may execute next commands: clear, remove, add. For entity's sections formatter_??? and filter_??? actions will be ignored.

The arg** in commands is name of objects.

As objecttype for sections you must use next types: For entity section you also can specify object attribute and value to set:
   attributes=attr01, attr02
   attr01=attrname, attrvalue
   attr02=attrname, attrvalue

Where attributes is a option with attribute's options names attr01, attr02. Into options attr01, attr02 you must specify attribute name attrname and attribute value attrvalue. The value willbe evaluated using eval() in logging namespace.

The root logger must specify a level, list of handlers and filters. For [logger_???] sections have no mandatory options. By default level, handlers and other attributes are no changed. An example of a root logger section is given below.:
   [logger_root]
   level=NOTSET
   handlers=hand01
   filters=
   actions=act01, act02
   act01=clear, handler
   act02=remove, filter, filt99
   act03=add, handler, hand55
   disabled=0
   attributes=attr01
   attr01= name, A.B.C
For loggers other than the root logger, some additional information is required. The level and handlers entries are interpreted as for the root logger, except that if a non-root logger's level is specified as NOTSET, the system consults loggers higher up the hierarchy to determine the effective level of the logger. The propagate entry is set to 1 (is default) to indicate that messages must propagate to handlers higher up the logger hierarchy from this logger, or 0 to indicate that messages are not propagated to handlers up the hierarchy. The qualname entry is the hierarchical channel name of the logger, that is to say the name used by the application to get the logger. The disabled set this logger disabled (1) or enabled (0). By default disabled is 0 for new or not changed for existing logger. The mandatory options is no. If qualname is not specified then configuration name is used, for below example it is 'parser'. The filters entry, specify filters names to use.If this entry specified then clear all filters then add new filters from filters list. If handlers entry specified then clear all filters then add new handlers from handlers list. This is illustrated by the following example.:
   [logger_parser]
   level=DEBUG
   handlers=hand01
   propagate=1
   qualname=compiler.parser
   filters=
   actions=act01
   act01=clear,handler
   disabled=0
   attributes=attr01
   attr01= name, A.B.C

Sections which specify handler configuration are exemplified by the following. The class entry indicates the handler's class (as determined by eval() in the logging package's namespace). The level is interpreted as for loggers, and NOTSET is taken to mean "log everything".

The formatter entry indicates the key name of the formatter for this handler. If blank, a default formatter (logging._defaultFormatter) is used. If a name is specified, it must appear in the [formatters] section and have a corresponding section in the configuration file.

The args entry, when eval() evaluated in the context of the logging package's namespace, is the list of arguments to the constructor for the handler class. Refer to the constructors for the relevant handlers, or to the examples below, to see how typical entries are constructed.

The filters entry, specify filters names to use.If this entry specified then clear all filters then add new filters from filters list.

The mandatory options is class and args and only for new handlers.:
   [handler_hand01]
   class=StreamHandler
   level=NOTSET
   formatter=form01
   args=(sys.stdout,)
   filters=
   actions=act01
   act01=add, filter, filt01
   attributes=attr01
   attr01= attrname, A.B.C
Sections which specify filter configuration are typified by the following. The mandatory options is class and args and only for new filters.:
   [filter_filt01]
   class=Filter
   args=('App')
   attributes=attr01
   attr01= name, A.B.C
Sections which specify formatter configuration are typified by the following.:
   [formatter_form01]
   format=F1 %(asctime)s %(levelname)s %(message)s
   datefmt=
   class=logging.Formatter
   args=()
   attributes=attr01
   attr01= name, A.B.C

The mandatory options is format and datefmt.

The format entry is the overall format string, and the datefmt entry is the strftime()-compatible date/time format string. If empty, the package substitutes ISO8601 format date/times, which is almost equivalent to specifying the date format string "The ISO8601 format also specifies milliseconds, which are appended to the result of using the above format string, with a comma separator. An example time in ISO8601 format is 2003-01-23 00:29:50,411.

The class entry is optional. It indicates the name of the formatter's class (as a dotted module and class name.) This option is useful for instantiating a Formatter subclass. Subclasses of Formatter can present exception tracebacks in an expanded or condensed format.


Warning: You must accurate use remove or clear options or commands, becouse may be conflict with currently executed code in runtime if it use removed objects.

Note: After importing xlogging XLogger class set as default class for new loggers.

Classes [hide private]
  NullHandler
Handler that do no output.
  RangeFilter
Filter available output only if level in specified range.
  NamesFilter
Filter available output only if logger name equal any from 'names'.
  IndentFormatter
Formatter with indentation level support.
  XLogger
Functions [hide private]
 
getLevelByName(levelname)
Return level name by level value.
source code
 
applyConfigFile(fname, defaults=None)
Read the logging configuration from a ConfigParser-format file.
source code
 
_applyAttrs(opts, inst)
Apply attributes from dictionary "opts" to object instance "inst".
source code
dict
_options(sec, cp, raw=0)
Return readed options and it's values in dictionary.
source code
 
_applyFilters(flts, inst, cp, filters)
Aplly filters with names listed in "flts": to object "inst".
source code
 
_applyFormatter(fmtr, inst, cp, formatters)
Aplly formatter with name listed in "fmtr": to object "inst".
source code
 
_applyHandlers(hdls, inst, cp, handlers, formatters, filters)
Aplly handlerss with names listed in "hdls": to object "inst".
source code
 
_applyActions(opts, inst, cp, handlers, formatters, filters)
Aplly actions with names listed in "opts['actions']": to object "inst".
source code
 
_trace(self, msg, *args, **kwargs)
Log 'msg % args' with severity 'TRACE'.
source code
 
_dbgtrace(self, msg, *args, **kwargs)
Log 'msg % args' with severity 'DBGTRACE'.
source code
 
trace(msg, *args, **kwargs)
Log a message with severity 'TRACE' on the root logger.
source code
 
dbgtrace(msg, *args, **kwargs)
Log a message with severity 'DBGTRACE' on the root logger.
source code
 
_debug() source code
Variables [hide private]
int TRACE = 15
Logging level constant, used for prereliase tracing.
int DBGTRACE = 5
Logging level constant, used for debug tracing.

Imports: logging, logging.cStringIO, logging.setLoggerClass, logging.ERROR, logging.critical, logging.Filterer, logging.atexit, logging.Handler, logging.LogRecord, logging.shutdown, logging.Logger, logging.Formatter, logging.BASIC_FORMAT, logging.getLevelName, logging.Filter, logging.logProcesses, logging.error, logging.addLevelName, logging.log, logging.getLogger, logging.FileHandler, logging.WARNING, logging.fatal, logging.CRITICAL, logging.StreamHandler, logging.raiseExceptions, logging.currentframe, logging.INFO, logging.string, logging.info, logging.exception, logging.logThreads, logging.sys, logging.disable, logging.warn, logging.exithook, logging.codecs, logging.DEBUG, logging.FATAL, logging.PlaceHolder, logging.types, logging.WARN, logging.BufferingFormatter, logging.NOTSET, logging.root, logging.makeLogRecord, logging.traceback, logging.Manager, logging.warning, logging.getLoggerClass, logging.basicConfig, logging.time, logging.debug, logging.os, logging.RootLogger, functools.wraps, threading, thread, dbg, logging.Logger


Function Details [hide private]

getLevelByName(levelname)

source code 

Return level name by level value.

If no such level then raise error KeyError.

applyConfigFile(fname, defaults=None)

source code 

Read the logging configuration from a ConfigParser-format file.

This can be called several times from an application, allowing an end user the ability to select from various pre-canned configurations (if the developer provides a mechanism to present the choices and load the chosen configuration). In versions of ConfigParser which have the readfp method [typically shipped in 2.x versions of Python], you can pass in a file-like object rather than a filename, in which case the file-like object will be read using readfp.

Algorithm:

  1. Read [loggers], [handlers], [filters], [formatters] keys into DICT.
  2. FOR _logger_ IN [loggers]:
    1. IF _logger_ EXIST get it, ELSE create new
    2. Read _fs_=[filters].
    3. IF _fs_ THEN:
      1. _filters_.clear.
      2. FOR _f_ IN _fs_:
        1. Read filter from config.
        2. Create new filter.
        3. Add filter to _logger_.
    4. FOR _f_ IN _fs_:
      1. Read filter changes from config section.
      2. Change filter _f_.
      3. Read [attributes] and apply.
    5. Read _hs_=[handlers].
    6. IF _hs_ THEN:
      1. _handlers_.clear.
      2. FOR _h_ IN _hs_:
        1. Read handler from config.
        2. Create new handler.
        3. Add handler to _logger_.
    7. FOR _h_ IN _hs_:
      1. Read handler changes from config section.
      2. Change handler _h_.
      3. Read [formatter] and ADD or CHANGE.
      4. Read [filters] and ADD or CHANGE.
      5. Read [attributes] and apply.
    8. Read [attributes] and apply.
Logger section example:
   [manager]
   #disable=WARNING
   
   [logger_parser]
   level=DEBUG
   handlers=hand01
   propagate=1
   qualname=compiler.parser
   filters=
   actions=act01
   act01=clear,handler
   disabled=0
   attributes=attr01
   attr01= name, A.B.C

_applyAttrs(opts, inst)

source code 
Apply attributes from dictionary "opts" to object instance "inst".
Parameters:
  • opts (dict) - Dictionary with item "attributes" and items listed in "attributes" which will be applied.
  • inst - Object instance.

_options(sec, cp, raw=0)

source code 
Return readed options and it's values in dictionary.
Parameters:
  • sec (str) - Section name.
  • cp (ConfigParser) - Config parser instance.
  • raw (int = {0}) - Raw mode for get in ConfigParser.
Returns: dict
Dictionary with options and values.

_applyFilters(flts, inst, cp, filters)

source code 

Aplly filters with names listed in "flts": to object "inst".

First try find named filter into "inst.filters" list (which have attribute "name"), if not find then try find into "filters" dict, else create new. Then apply changes to filter. Filter name must exist in filters list. To add filter to inst used "addFilter" method. To created or added filters set attribute "name" to filter name.
Parameters:
  • flts (list) - List with filter's names.
  • inst (Object instance) - Object instance to apply filters.
  • cp (ConfigParser) - Config parser instance.
  • filters (

    dict

    Filter section example:
       [filter_filt01]
       class=Filter
       args=('App')
       attributes=attr01
       attr01= name, A.B.C
    
    ) - Permited filters name with existing or None instances.

_applyFormatter(fmtr, inst, cp, formatters)

source code 

Aplly formatter with name listed in "fmtr": to object "inst".

First try find named formatter into "inst.formatter" list (which have attribute "name"), if not find then try find into "formatters" dict, else create new. Then apply changes to formatter. Formatter name must exist in formatters list. To add filter to inst used "setFormatter" method.
Parameters:
  • fmtr (list) - Formatter name.
  • inst (Object instance) - Object instance to apply formatter.
  • cp (ConfigParser) - Config parser instance.
  • formatters (

    dict

    Formatter section example:
       [formatter_form01]
       format=F1 %(asctime)s %(levelname)s %(message)s
       datefmt=
       class=logging.Formatter
       args=()
       attributes=attr01
       attr01= name, A.B.C
    
    ) - Permited formatters name with existing or None instances.

Warning: Options for formatter readed in raw mode (see ConfigParser).

_applyHandlers(hdls, inst, cp, handlers, formatters, filters)

source code 

Aplly handlerss with names listed in "hdls": to object "inst".

First try find named handler into "inst.handlers" list (which have attribute "name"), if not then try find in "handlers" dict, else create new. Then apply changes to handler. Handler name must exist in handlers list. To add handler to inst used "addHandler" method.
Parameters:
  • hdls (list) - List with hamdler's names.
  • inst (Object instance) - Object instance to apply handlers.
  • cp (ConfigParser) - Config parser instance.
  • handlers (dict) - Permited handlers name with existing or None instances.
  • formatters (dict) - Permited formatters.
  • filters (

    dict

    Handler section example:
       [handler_hand01]
       class=StreamHandler
       level=NOTSET
       formatter=form01
       args=(sys.stdout,)
       filters=
       actions=act01
       act01=add, filter, filt01
       attributes=attr01
       attr01= attrname, A.B.C
    
    ) - Permited filters.

_applyActions(opts, inst, cp, handlers, formatters, filters)

source code 

Aplly actions with names listed in "opts['actions']": to object "inst".

First try find named filter into "filters" dict, if not find then (which have attribute "name") into "inst.filters" list, else create new. Then apply changes to filter. Filter name must exist in filters list. To add filter to inst used "addFilter" method.
Parameters:
  • opts (dict) - Dictionary with actions describes.
  • inst (

    Object instance

    Action example:
       actions=act01
       act01=add, filter, filt01
    
    ) - Object instance to apply actions.

_trace(self, msg, *args, **kwargs)

source code 

Log 'msg % args' with severity 'TRACE'.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.trace("Houston, we have a %s", "thorny problem", exc_info=1)

_dbgtrace(self, msg, *args, **kwargs)

source code 

Log 'msg % args' with severity 'DBGTRACE'.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.dbgtrace("Houston, we have a %s", "thorny problem", exc_info=1)