Lib/logging/config.py

   1 # Copyright 2001-2007 by Vinay Sajip. All Rights Reserved.
   2 #
   3 # Permission to use, copy, modify, and distribute this software and its
   4 # documentation for any purpose and without fee is hereby granted,
   5 # provided that the above copyright notice appear in all copies and that
   6 # both that copyright notice and this permission notice appear in
   7 # supporting documentation, and that the name of Vinay Sajip
   8 # not be used in advertising or publicity pertaining to distribution
   9 # of the software without specific, written prior permission.
  10 # VINAY SAJIP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  11 # ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  12 # VINAY SAJIP BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  13 # ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  14 # IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  15 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16
  17 """
  18 Configuration functions for the logging package for Python. The core package
  19 is based on PEP 282 and comments thereto in comp.lang.python, and influenced
  20 by Apache's log4j system.
  21
  22 Should work under Python versions >= 1.5.2, except that source line
  23 information is not available unless 'sys._getframe()' is.
  24
  25 Copyright (C) 2001-2007 Vinay Sajip. All Rights Reserved.
  26
  27 To use, simply 'import logging' and log away!
  28 """
  29
  30 import sys, logging, logging.handlers, string, socket, struct, os, traceback, types
  31
  32 try:
  33     import thread
  34     import threading
  35 except ImportError:
  36     thread = None
  37
  38 from SocketServer import ThreadingTCPServer, StreamRequestHandler
  39
  40
  41 DEFAULT_LOGGING_CONFIG_PORT = 9030
  42
  43 if sys.platform == "win32":
  44     RESET_ERROR = 10054   #WSAECONNRESET
  45 else:
  46     RESET_ERROR = 104     #ECONNRESET
  47
  48 #
  49 #   The following code implements a socket listener for on-the-fly
  50 #   reconfiguration of logging.
  51 #
  52 #   _listener holds the server object doing the listening
  53 _listener = None
  54
  55 def fileConfig(fname, defaults=None):
  56     """
  57     Read the logging configuration from a ConfigParser-format file.
  58
  59     This can be called several times from an application, allowing an end user
  60     the ability to select from various pre-canned configurations (if the
  61     developer provides a mechanism to present the choices and load the chosen
  62     configuration).
  63     In versions of ConfigParser which have the readfp method [typically
  64     shipped in 2.x versions of Python], you can pass in a file-like object
  65     rather than a filename, in which case the file-like object will be read
  66     using readfp.
  67     """
  68     import ConfigParser
  69
  70     cp = ConfigParser.ConfigParser(defaults)
  71     if hasattr(cp, 'readfp') and hasattr(fname, 'readline'):
  72         cp.readfp(fname)
  73     else:
  74         cp.read(fname)
  75
  76     formatters = _create_formatters(cp)
  77
  78     # critical section
  79     logging._acquireLock()
  80     try:
  81         logging._handlers.clear()
  82         del logging._handlerList[:]
  83         # Handlers add themselves to logging._handlers
  84         handlers = _install_handlers(cp, formatters)
  85         _install_loggers(cp, handlers)
  86     finally:
  87         logging._releaseLock()
  88
  89
  90 def _resolve(name):
  91     """Resolve a dotted name to a global object."""
  92     name = string.split(name, '.')
  93     used = name.pop(0)
  94     found = __import__(used)
  95     for n in name:
  96         used = used + '.' + n
  97         try:
  98             found = getattr(found, n)
  99         except AttributeError:
 100             __import__(used)
 101             found = getattr(found, n)
 102     return found
 103
 104
 105 def _create_formatters(cp):
 106     """Create and return formatters"""
 107     flist = cp.get("formatters", "keys")
 108     if not len(flist):
 109         return {}
 110     flist = string.split(flist, ",")
 111     formatters = {}
 112     for form in flist:
 113         sectname = "formatter_%s" % string.strip(form)
 114         opts = cp.options(sectname)
 115         if "format" in opts:
 116             fs = cp.get(sectname, "format", 1)
 117         else:
 118             fs = None
 119         if "datefmt" in opts:
 120             dfs = cp.get(sectname, "datefmt", 1)
 121         else:
 122             dfs = None
 123         c = logging.Formatter
 124         if "class" in opts:
 125             class_name = cp.get(sectname, "class")
 126             if class_name:
 127                 c = _resolve(class_name)
 128         f = c(fs, dfs)
 129         formatters[form] = f
 130     return formatters
 131
 132
 133 def _install_handlers(cp, formatters):
 134     """Install and return handlers"""
 135     hlist = cp.get("handlers", "keys")
 136     if not len(hlist):
 137         return {}
 138     hlist = string.split(hlist, ",")
 139     handlers = {}
 140     fixups = [] #for inter-handler references
 141     for hand in hlist:
 142         sectname = "handler_%s" % string.strip(hand)
 143         klass = cp.get(sectname, "class")
 144         opts = cp.options(sectname)
 145         if "formatter" in opts:
 146             fmt = cp.get(sectname, "formatter")
 147         else:
 148             fmt = ""
 149         klass = eval(klass, vars(logging))
 150         args = cp.get(sectname, "args")
 151         args = eval(args, vars(logging))
 152         h = apply(klass, args)
 153         if "level" in opts:
 154             level = cp.get(sectname, "level")
 155             h.setLevel(logging._levelNames[level])
 156         if len(fmt):
 157             h.setFormatter(formatters[fmt])
 158         #temporary hack for FileHandler and MemoryHandler.
 159         if klass == logging.handlers.MemoryHandler:
 160             if "target" in opts:
 161                 target = cp.get(sectname,"target")
 162             else:
 163                 target = ""
 164             if len(target): #the target handler may not be loaded yet, so keep for later...
 165                 fixups.append((h, target))
 166         handlers[hand] = h
 167     #now all handlers are loaded, fixup inter-handler references...
 168     for h, t in fixups:
 169         h.setTarget(handlers[t])
 170     return handlers
 171
 172
 173 def _install_loggers(cp, handlers):
 174     """Create and install loggers"""
 175
 176     # configure the root first
 177     llist = cp.get("loggers", "keys")
 178     llist = string.split(llist, ",")
 179     llist = map(lambda x: string.strip(x), llist)
 180     llist.remove("root")
 181     sectname = "logger_root"
 182     root = logging.root
 183     log = root
 184     opts = cp.options(sectname)
 185     if "level" in opts:
 186         level = cp.get(sectname, "level")
 187         log.setLevel(logging._levelNames[level])
 188     for h in root.handlers[:]:
 189         root.removeHandler(h)
 190     hlist = cp.get(sectname, "handlers")
 191     if len(hlist):
 192         hlist = string.split(hlist, ",")
 193         for hand in hlist:
 194             log.addHandler(handlers[string.strip(hand)])
 195
 196     #and now the others...
 197     #we don't want to lose the existing loggers,
 198     #since other threads may have pointers to them.
 199     #existing is set to contain all existing loggers,
 200     #and as we go through the new configuration we
 201     #remove any which are configured. At the end,
 202     #what's left in existing is the set of loggers
 203     #which were in the previous configuration but
 204     #which are not in the new configuration.
 205     existing = root.manager.loggerDict.keys()
 206     #The list needs to be sorted so that we can
 207     #avoid disabling child loggers of explicitly
 208     #named loggers. With a sorted list it is easier
 209     #to find the child loggers.
 210     existing.sort()
 211     #We'll keep the list of existing loggers
 212     #which are children of named loggers here...
 213     child_loggers = []
 214     #now set up the new ones...
 215     for log in llist:
 216         sectname = "logger_%s" % log
 217         qn = cp.get(sectname, "qualname")
 218         opts = cp.options(sectname)
 219         if "propagate" in opts:
 220             propagate = cp.getint(sectname, "propagate")
 221         else:
 222             propagate = 1
 223         logger = logging.getLogger(qn)
 224         if qn in existing:
 225             i = existing.index(qn)
 226             prefixed = qn + "."
 227             pflen = len(prefixed)
 228             num_existing = len(existing)
 229             i = i + 1 # look at the entry after qn
 230             while (i < num_existing) and (existing[i][:pflen] == prefixed):
 231                 child_loggers.append(existing[i])
 232                 i = i + 1
 233             existing.remove(qn)
 234         if "level" in opts:
 235             level = cp.get(sectname, "level")
 236             logger.setLevel(logging._levelNames[level])
 237         for h in logger.handlers[:]:
 238             logger.removeHandler(h)
 239         logger.propagate = propagate
 240         logger.disabled = 0
 241         hlist = cp.get(sectname, "handlers")
 242         if len(hlist):
 243             hlist = string.split(hlist, ",")
 244             for hand in hlist:
 245                 logger.addHandler(handlers[string.strip(hand)])
 246
 247     #Disable any old loggers. There's no point deleting
 248     #them as other threads may continue to hold references
 249     #and by disabling them, you stop them doing any logging.
 250     #However, don't disable children of named loggers, as that's
 251     #probably not what was intended by the user.
 252     for log in existing:
 253         logger = root.manager.loggerDict[log]
 254         if log in child_loggers:
 255             logger.level = logging.NOTSET
 256             logger.handlers = []
 257             logger.propagate = 1
 258         else:
 259             logger.disabled = 1
 260
 261
 262 def listen(port=DEFAULT_LOGGING_CONFIG_PORT):
 263     """
 264     Start up a socket server on the specified port, and listen for new
 265     configurations.
 266
 267     These will be sent as a file suitable for processing by fileConfig().
 268     Returns a Thread object on which you can call start() to start the server,
 269     and which you can join() when appropriate. To stop the server, call
 270     stopListening().
 271     """
 272     if not thread:
 273         raise NotImplementedError, "listen() needs threading to work"
 274
 275     class ConfigStreamHandler(StreamRequestHandler):
 276         """
 277         Handler for a logging configuration request.
 278
 279         It expects a completely new logging configuration and uses fileConfig
 280         to install it.
 281         """
 282         def handle(self):
 283             """
 284             Handle a request.
 285
 286             Each request is expected to be a 4-byte length, packed using
 287             struct.pack(">L", n), followed by the config file.
 288             Uses fileConfig() to do the grunt work.
 289             """
 290             import tempfile
 291             try:
 292                 conn = self.connection
 293                 chunk = conn.recv(4)
 294                 if len(chunk) == 4:
 295                     slen = struct.unpack(">L", chunk)[0]
 296                     chunk = self.connection.recv(slen)
 297                     while len(chunk) < slen:
 298                         chunk = chunk + conn.recv(slen - len(chunk))
 299                     #Apply new configuration. We'd like to be able to
 300                     #create a StringIO and pass that in, but unfortunately
 301                     #1.5.2 ConfigParser does not support reading file
 302                     #objects, only actual files. So we create a temporary
 303                     #file and remove it later.
 304                     file = tempfile.mktemp(".ini")
 305                     f = open(file, "w")
 306                     f.write(chunk)
 307                     f.close()
 308                     try:
 309                         fileConfig(file)
 310                     except (KeyboardInterrupt, SystemExit):
 311                         raise
 312                     except:
 313                         traceback.print_exc()
 314                     os.remove(file)
 315             except socket.error, e:
 316                 if type(e.args) != types.TupleType:
 317                     raise
 318                 else:
 319                     errcode = e.args[0]
 320                     if errcode != RESET_ERROR:
 321                         raise
 322
 323     class ConfigSocketReceiver(ThreadingTCPServer):
 324         """
 325         A simple TCP socket-based logging config receiver.
 326         """
 327
 328         allow_reuse_address = 1
 329
 330         def __init__(self, host='localhost', port=DEFAULT_LOGGING_CONFIG_PORT,
 331                      handler=None):
 332             ThreadingTCPServer.__init__(self, (host, port), handler)
 333             logging._acquireLock()
 334             self.abort = 0
 335             logging._releaseLock()
 336             self.timeout = 1
 337
 338         def serve_until_stopped(self):
 339             import select
 340             abort = 0
 341             while not abort:
 342                 rd, wr, ex = select.select([self.socket.fileno()],
 343                                            [], [],
 344                                            self.timeout)
 345                 if rd:
 346                     self.handle_request()
 347                 logging._acquireLock()
 348                 abort = self.abort
 349                 logging._releaseLock()
 350
 351     def serve(rcvr, hdlr, port):
 352         server = rcvr(port=port, handler=hdlr)
 353         global _listener
 354         logging._acquireLock()
 355         _listener = server
 356         logging._releaseLock()
 357         server.serve_until_stopped()
 358
 359     return threading.Thread(target=serve,
 360                             args=(ConfigSocketReceiver,
 361                                   ConfigStreamHandler, port))
 362
 363 def stopListening():
 364     """
 365     Stop the listening server which was created with a call to listen().
 366     """
 367     global _listener
 368     if _listener:
 369         logging._acquireLock()
 370         _listener.abort = 1
 371         _listener = None
 372         logging._releaseLock()