Debian Codegraph @

Lib/logging/config.py

raw
1 # Copyright 2001-2023 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 Copyright (C) 2001-2022 Vinay Sajip. All Rights Reserved.
23
24 To use, simply 'import logging' and log away!
25 """
26
27 import errno
28 import functools
29 import io
30 import logging
31 import logging.handlers
32 import os
33 import queue
34 import re
35 import socket
36 import struct
37 import threading
38 import traceback
39
40 from socketserver import ThreadingTCPServer, StreamRequestHandler
41
42
43 DEFAULT_LOGGING_CONFIG_PORT = 9030
44
45 RESET_ERROR = errno.ECONNRESET
46
47 #
48 # The following code implements a socket listener for on-the-fly
49 # reconfiguration of logging.
50 #
51 # _listener holds the server object doing the listening
52 _listener = None
53
54 def fileConfig(fname, defaults=None, disable_existing_loggers=True, encoding=None):
55 """
56 Read the logging configuration from a ConfigParser-format file.
57
58 This can be called several times from an application, allowing an end user
59 the ability to select from various pre-canned configurations (if the
60 developer provides a mechanism to present the choices and load the chosen
61 configuration).
62 """
63 import configparser
64
65 if isinstance(fname, str):
66 if not os.path.exists(fname):
67 raise FileNotFoundError(f"{fname} doesn't exist")
68 elif not os.path.getsize(fname):
69 raise RuntimeError(f'{fname} is an empty file')
70
71 if isinstance(fname, configparser.RawConfigParser):
72 cp = fname
73 else:
74 try:
75 cp = configparser.ConfigParser(defaults)
76 if hasattr(fname, 'readline'):
77 cp.read_file(fname)
78 else:
79 encoding = io.text_encoding(encoding)
80 cp.read(fname, encoding=encoding)
81 except configparser.ParsingError as e:
82 raise RuntimeError(f'{fname} is invalid: {e}')
83
84 formatters = _create_formatters(cp)
85
86 # critical section
87 with logging._lock:
88 _clearExistingHandlers()
89
90 # Handlers add themselves to logging._handlers
91 handlers = _install_handlers(cp, formatters)
92 _install_loggers(cp, handlers, disable_existing_loggers)
93
94
95 def _resolve(name):
96 """Resolve a dotted name to a global object."""
97 name = name.split('.')
98 used = name.pop(0)
99 found = __import__(used)
100 for n in name:
101 used = used + '.' + n
102 try:
103 found = getattr(found, n)
104 except AttributeError:
105 __import__(used)
106 found = getattr(found, n)
107 return found
108
109 def _strip_spaces(alist):
110 return map(str.strip, alist)
111
112 def _create_formatters(cp):
113 """Create and return formatters"""
114 flist = cp["formatters"]["keys"]
115 if not len(flist):
116 return {}
117 flist = flist.split(",")
118 flist = _strip_spaces(flist)
119 formatters = {}
120 for form in flist:
121 sectname = "formatter_%s" % form
122 fs = cp.get(sectname, "format", raw=True, fallback=None)
123 dfs = cp.get(sectname, "datefmt", raw=True, fallback=None)
124 stl = cp.get(sectname, "style", raw=True, fallback='%')
125 defaults = cp.get(sectname, "defaults", raw=True, fallback=None)
126
127 c = logging.Formatter
128 class_name = cp[sectname].get("class")
129 if class_name:
130 c = _resolve(class_name)
131
132 if defaults is not None:
133 defaults = eval(defaults, vars(logging))
134 f = c(fs, dfs, stl, defaults=defaults)
135 else:
136 f = c(fs, dfs, stl)
137 formatters[form] = f
138 return formatters
139
140
141 def _install_handlers(cp, formatters):
142 """Install and return handlers"""
143 hlist = cp["handlers"]["keys"]
144 if not len(hlist):
145 return {}
146 hlist = hlist.split(",")
147 hlist = _strip_spaces(hlist)
148 handlers = {}
149 fixups = [] #for inter-handler references
150 for hand in hlist:
151 section = cp["handler_%s" % hand]
152 klass = section["class"]
153 fmt = section.get("formatter", "")
154 try:
155 klass = eval(klass, vars(logging))
156 except (AttributeError, NameError):
157 klass = _resolve(klass)
158 args = section.get("args", '()')
159 args = eval(args, vars(logging))
160 kwargs = section.get("kwargs", '{}')
161 kwargs = eval(kwargs, vars(logging))
162 h = klass(*args, **kwargs)
163 h.name = hand
164 if "level" in section:
165 level = section["level"]
166 h.setLevel(level)
167 if len(fmt):
168 h.setFormatter(formatters[fmt])
169 if issubclass(klass, logging.handlers.MemoryHandler):
170 target = section.get("target", "")
171 if len(target): #the target handler may not be loaded yet, so keep for later...
172 fixups.append((h, target))
173 handlers[hand] = h
174 #now all handlers are loaded, fixup inter-handler references...
175 for h, t in fixups:
176 h.setTarget(handlers[t])
177 return handlers
178
179 def _handle_existing_loggers(existing, child_loggers, disable_existing):
180 """
181 When (re)configuring logging, handle loggers which were in the previous
182 configuration but are not in the new configuration. There's no point
183 deleting them as other threads may continue to hold references to them;
184 and by disabling them, you stop them doing any logging.
185
186 However, don't disable children of named loggers, as that's probably not
187 what was intended by the user. Also, allow existing loggers to NOT be
188 disabled if disable_existing is false.
189 """
190 root = logging.root
191 for log in existing:
192 logger = root.manager.loggerDict[log]
193 if log in child_loggers:
194 if not isinstance(logger, logging.PlaceHolder):
195 logger.setLevel(logging.NOTSET)
196 logger.handlers = []
197 logger.propagate = True
198 else:
199 logger.disabled = disable_existing
200
201 def _install_loggers(cp, handlers, disable_existing):
202 """Create and install loggers"""
203
204 # configure the root first
205 llist = cp["loggers"]["keys"]
206 llist = llist.split(",")
207 llist = list(_strip_spaces(llist))
208 llist.remove("root")
209 section = cp["logger_root"]
210 root = logging.root
211 log = root
212 if "level" in section:
213 level = section["level"]
214 log.setLevel(level)
215 for h in root.handlers[:]:
216 root.removeHandler(h)
217 hlist = section["handlers"]
218 if len(hlist):
219 hlist = hlist.split(",")
220 hlist = _strip_spaces(hlist)
221 for hand in hlist:
222 log.addHandler(handlers[hand])
223
224 #and now the others...
225 #we don't want to lose the existing loggers,
226 #since other threads may have pointers to them.
227 #existing is set to contain all existing loggers,
228 #and as we go through the new configuration we
229 #remove any which are configured. At the end,
230 #what's left in existing is the set of loggers
231 #which were in the previous configuration but
232 #which are not in the new configuration.
233 existing = list(root.manager.loggerDict.keys())
234 #The list needs to be sorted so that we can
235 #avoid disabling child loggers of explicitly
236 #named loggers. With a sorted list it is easier
237 #to find the child loggers.
238 existing.sort()
239 #We'll keep the list of existing loggers
240 #which are children of named loggers here...
241 child_loggers = []
242 #now set up the new ones...
243 for log in llist:
244 section = cp["logger_%s" % log]
245 qn = section["qualname"]
246 propagate = section.getint("propagate", fallback=1)
247 logger = logging.getLogger(qn)
248 if qn in existing:
249 i = existing.index(qn) + 1 # start with the entry after qn
250 prefixed = qn + "."
251 pflen = len(prefixed)
252 num_existing = len(existing)
253 while i < num_existing:
254 if existing[i][:pflen] == prefixed:
255 child_loggers.append(existing[i])
256 i += 1
257 existing.remove(qn)
258 if "level" in section:
259 level = section["level"]
260 logger.setLevel(level)
261 for h in logger.handlers[:]:
262 logger.removeHandler(h)
263 logger.propagate = propagate
264 logger.disabled = 0
265 hlist = section["handlers"]
266 if len(hlist):
267 hlist = hlist.split(",")
268 hlist = _strip_spaces(hlist)
269 for hand in hlist:
270 logger.addHandler(handlers[hand])
271
272 #Disable any old loggers. There's no point deleting
273 #them as other threads may continue to hold references
274 #and by disabling them, you stop them doing any logging.
275 #However, don't disable children of named loggers, as that's
276 #probably not what was intended by the user.
277 #for log in existing:
278 # logger = root.manager.loggerDict[log]
279 # if log in child_loggers:
280 # logger.level = logging.NOTSET
281 # logger.handlers = []
282 # logger.propagate = 1
283 # elif disable_existing_loggers:
284 # logger.disabled = 1
285 _handle_existing_loggers(existing, child_loggers, disable_existing)
286
287
288 def _clearExistingHandlers():
289 """Clear and close existing handlers"""
290 logging._handlers.clear()
291 logging.shutdown(logging._handlerList[:])
292 del logging._handlerList[:]
293
294
295 IDENTIFIER = re.compile('^[a-z_][a-z0-9_]*$', re.I)
296
297
298 def valid_ident(s):
299 m = IDENTIFIER.match(s)
300 if not m:
301 raise ValueError('Not a valid Python identifier: %r' % s)
302 return True
303
304
305 class ConvertingMixin(object):
306 """For ConvertingXXX's, this mixin class provides common functions"""
307
308 def convert_with_key(self, key, value, replace=True):
309 result = self.configurator.convert(value)
310 #If the converted value is different, save for next time
311 if value is not result:
312 if replace:
313 self[key] = result
314 if type(result) in (ConvertingDict, ConvertingList,
315 ConvertingTuple):
316 result.parent = self
317 result.key = key
318 return result
319
320 def convert(self, value):
321 result = self.configurator.convert(value)
322 if value is not result:
323 if type(result) in (ConvertingDict, ConvertingList,
324 ConvertingTuple):
325 result.parent = self
326 return result
327
328
329 # The ConvertingXXX classes are wrappers around standard Python containers,
330 # and they serve to convert any suitable values in the container. The
331 # conversion converts base dicts, lists and tuples to their wrapped
332 # equivalents, whereas strings which match a conversion format are converted
333 # appropriately.
334 #
335 # Each wrapper should have a configurator attribute holding the actual
336 # configurator to use for conversion.
337
338 class ConvertingDict(dict, ConvertingMixin):
339 """A converting dictionary wrapper."""
340
341 def __getitem__(self, key):
342 value = dict.__getitem__(self, key)
343 return self.convert_with_key(key, value)
344
345 def get(self, key, default=None):
346 value = dict.get(self, key, default)
347 return self.convert_with_key(key, value)
348
349 def pop(self, key, default=None):
350 value = dict.pop(self, key, default)
351 return self.convert_with_key(key, value, replace=False)
352
353 class ConvertingList(list, ConvertingMixin):
354 """A converting list wrapper."""
355 def __getitem__(self, key):
356 value = list.__getitem__(self, key)
357 return self.convert_with_key(key, value)
358
359 def pop(self, idx=-1):
360 value = list.pop(self, idx)
361 return self.convert(value)
362
363 class ConvertingTuple(tuple, ConvertingMixin):
364 """A converting tuple wrapper."""
365 def __getitem__(self, key):
366 value = tuple.__getitem__(self, key)
367 # Can't replace a tuple entry.
368 return self.convert_with_key(key, value, replace=False)
369
370 class BaseConfigurator(object):
371 """
372 The configurator base class which defines some useful defaults.
373 """
374
375 CONVERT_PATTERN = re.compile(r'^(?P<prefix>[a-z]+)://(?P<suffix>.*)$')
376
377 WORD_PATTERN = re.compile(r'^\s*(\w+)\s*')
378 DOT_PATTERN = re.compile(r'^\.\s*(\w+)\s*')
379 INDEX_PATTERN = re.compile(r'^\[([^\[\]]*)\]\s*')
380 DIGIT_PATTERN = re.compile(r'^\d+$')
381
382 value_converters = {
383 'ext' : 'ext_convert',
384 'cfg' : 'cfg_convert',
385 }
386
387 # We might want to use a different one, e.g. importlib
388 importer = staticmethod(__import__)
389
390 def __init__(self, config):
391 self.config = ConvertingDict(config)
392 self.config.configurator = self
393
394 def resolve(self, s):
395 """
396 Resolve strings to objects using standard import and attribute
397 syntax.
398 """
399 name = s.split('.')
400 used = name.pop(0)
401 try:
402 found = self.importer(used)
403 for frag in name:
404 used += '.' + frag
405 try:
406 found = getattr(found, frag)
407 except AttributeError:
408 self.importer(used)
409 found = getattr(found, frag)
410 return found
411 except ImportError as e:
412 v = ValueError('Cannot resolve %r: %s' % (s, e))
413 raise v from e
414
415 def ext_convert(self, value):
416 """Default converter for the ext:// protocol."""
417 return self.resolve(value)
418
419 def cfg_convert(self, value):
420 """Default converter for the cfg:// protocol."""
421 rest = value
422 m = self.WORD_PATTERN.match(rest)
423 if m is None:
424 raise ValueError("Unable to convert %r" % value)
425 else:
426 rest = rest[m.end():]
427 d = self.config[m.groups()[0]]
428 #print d, rest
429 while rest:
430 m = self.DOT_PATTERN.match(rest)
431 if m:
432 d = d[m.groups()[0]]
433 else:
434 m = self.INDEX_PATTERN.match(rest)
435 if m:
436 idx = m.groups()[0]
437 if not self.DIGIT_PATTERN.match(idx):
438 d = d[idx]
439 else:
440 try:
441 n = int(idx) # try as number first (most likely)
442 d = d[n]
443 except TypeError:
444 d = d[idx]
445 if m:
446 rest = rest[m.end():]
447 else:
448 raise ValueError('Unable to convert '
449 '%r at %r' % (value, rest))
450 #rest should be empty
451 return d
452
453 def convert(self, value):
454 """
455 Convert values to an appropriate type. dicts, lists and tuples are
456 replaced by their converting alternatives. Strings are checked to
457 see if they have a conversion format and are converted if they do.
458 """
459 if not isinstance(value, ConvertingDict) and isinstance(value, dict):
460 value = ConvertingDict(value)
461 value.configurator = self
462 elif not isinstance(value, ConvertingList) and isinstance(value, list):
463 value = ConvertingList(value)
464 value.configurator = self
465 elif not isinstance(value, ConvertingTuple) and\
466 isinstance(value, tuple) and not hasattr(value, '_fields'):
467 value = ConvertingTuple(value)
468 value.configurator = self
469 elif isinstance(value, str): # str for py3k
470 m = self.CONVERT_PATTERN.match(value)
471 if m:
472 d = m.groupdict()
473 prefix = d['prefix']
474 converter = self.value_converters.get(prefix, None)
475 if converter:
476 suffix = d['suffix']
477 converter = getattr(self, converter)
478 value = converter(suffix)
479 return value
480
481 def configure_custom(self, config):
482 """Configure an object with a user-supplied factory."""
483 c = config.pop('()')
484 if not callable(c):
485 c = self.resolve(c)
486 # Check for valid identifiers
487 kwargs = {k: config[k] for k in config if (k != '.' and valid_ident(k))}
488 result = c(**kwargs)
489 props = config.pop('.', None)
490 if props:
491 for name, value in props.items():
492 setattr(result, name, value)
493 return result
494
495 def as_tuple(self, value):
496 """Utility function which converts lists to tuples."""
497 if isinstance(value, list):
498 value = tuple(value)
499 return value
500
501 def _is_queue_like_object(obj):
502 """Check that *obj* implements the Queue API."""
503 if isinstance(obj, (queue.Queue, queue.SimpleQueue)):
504 return True
505 # defer importing multiprocessing as much as possible
506 from multiprocessing.queues import Queue as MPQueue
507 if isinstance(obj, MPQueue):
508 return True
509 # Depending on the multiprocessing start context, we cannot create
510 # a multiprocessing.managers.BaseManager instance 'mm' to get the
511 # runtime type of mm.Queue() or mm.JoinableQueue() (see gh-119819).
512 #
513 # Since we only need an object implementing the Queue API, we only
514 # do a protocol check, but we do not use typing.runtime_checkable()
515 # and typing.Protocol to reduce import time (see gh-121723).
516 #
517 # Ideally, we would have wanted to simply use strict type checking
518 # instead of a protocol-based type checking since the latter does
519 # not check the method signatures.
520 #
521 # Note that only 'put_nowait' and 'get' are required by the logging
522 # queue handler and queue listener (see gh-124653) and that other
523 # methods are either optional or unused.
524 minimal_queue_interface = ['put_nowait', 'get']
525 return all(callable(getattr(obj, method, None))
526 for method in minimal_queue_interface)
527
528 class DictConfigurator(BaseConfigurator):
529 """
530 Configure logging using a dictionary-like object to describe the
531 configuration.
532 """
533
534 def configure(self):
535 """Do the configuration."""
536
537 config = self.config
538 if 'version' not in config:
539 raise ValueError("dictionary doesn't specify a version")
540 if config['version'] != 1:
541 raise ValueError("Unsupported version: %s" % config['version'])
542 incremental = config.pop('incremental', False)
543 EMPTY_DICT = {}
544 with logging._lock:
545 if incremental:
546 handlers = config.get('handlers', EMPTY_DICT)
547 for name in handlers:
548 if name not in logging._handlers:
549 raise ValueError('No handler found with '
550 'name %r' % name)
551 else:
552 try:
553 handler = logging._handlers[name]
554 handler_config = handlers[name]
555 level = handler_config.get('level', None)
556 if level:
557 handler.setLevel(logging._checkLevel(level))
558 except Exception as e:
559 raise ValueError('Unable to configure handler '
560 '%r' % name) from e
561 loggers = config.get('loggers', EMPTY_DICT)
562 for name in loggers:
563 try:
564 self.configure_logger(name, loggers[name], True)
565 except Exception as e:
566 raise ValueError('Unable to configure logger '
567 '%r' % name) from e
568 root = config.get('root', None)
569 if root:
570 try:
571 self.configure_root(root, True)
572 except Exception as e:
573 raise ValueError('Unable to configure root '
574 'logger') from e
575 else:
576 disable_existing = config.pop('disable_existing_loggers', True)
577
578 _clearExistingHandlers()
579
580 # Do formatters first - they don't refer to anything else
581 formatters = config.get('formatters', EMPTY_DICT)
582 for name in formatters:
583 try:
584 formatters[name] = self.configure_formatter(
585 formatters[name])
586 except Exception as e:
587 raise ValueError('Unable to configure '
588 'formatter %r' % name) from e
589 # Next, do filters - they don't refer to anything else, either
590 filters = config.get('filters', EMPTY_DICT)
591 for name in filters:
592 try:
593 filters[name] = self.configure_filter(filters[name])
594 except Exception as e:
595 raise ValueError('Unable to configure '
596 'filter %r' % name) from e
597
598 # Next, do handlers - they refer to formatters and filters
599 # As handlers can refer to other handlers, sort the keys
600 # to allow a deterministic order of configuration
601 handlers = config.get('handlers', EMPTY_DICT)
602 deferred = []
603 for name in sorted(handlers):
604 try:
605 handler = self.configure_handler(handlers[name])
606 handler.name = name
607 handlers[name] = handler
608 except Exception as e:
609 if ' not configured yet' in str(e.__cause__):
610 deferred.append(name)
611 else:
612 raise ValueError('Unable to configure handler '
613 '%r' % name) from e
614
615 # Now do any that were deferred
616 for name in deferred:
617 try:
618 handler = self.configure_handler(handlers[name])
619 handler.name = name
620 handlers[name] = handler
621 except Exception as e:
622 raise ValueError('Unable to configure handler '
623 '%r' % name) from e
624
625 # Next, do loggers - they refer to handlers and filters
626
627 #we don't want to lose the existing loggers,
628 #since other threads may have pointers to them.
629 #existing is set to contain all existing loggers,
630 #and as we go through the new configuration we
631 #remove any which are configured. At the end,
632 #what's left in existing is the set of loggers
633 #which were in the previous configuration but
634 #which are not in the new configuration.
635 root = logging.root
636 existing = list(root.manager.loggerDict.keys())
637 #The list needs to be sorted so that we can
638 #avoid disabling child loggers of explicitly
639 #named loggers. With a sorted list it is easier
640 #to find the child loggers.
641 existing.sort()
642 #We'll keep the list of existing loggers
643 #which are children of named loggers here...
644 child_loggers = []
645 #now set up the new ones...
646 loggers = config.get('loggers', EMPTY_DICT)
647 for name in loggers:
648 if name in existing:
649 i = existing.index(name) + 1 # look after name
650 prefixed = name + "."
651 pflen = len(prefixed)
652 num_existing = len(existing)
653 while i < num_existing:
654 if existing[i][:pflen] == prefixed:
655 child_loggers.append(existing[i])
656 i += 1
657 existing.remove(name)
658 try:
659 self.configure_logger(name, loggers[name])
660 except Exception as e:
661 raise ValueError('Unable to configure logger '
662 '%r' % name) from e
663
664 #Disable any old loggers. There's no point deleting
665 #them as other threads may continue to hold references
666 #and by disabling them, you stop them doing any logging.
667 #However, don't disable children of named loggers, as that's
668 #probably not what was intended by the user.
669 #for log in existing:
670 # logger = root.manager.loggerDict[log]
671 # if log in child_loggers:
672 # logger.level = logging.NOTSET
673 # logger.handlers = []
674 # logger.propagate = True
675 # elif disable_existing:
676 # logger.disabled = True
677 _handle_existing_loggers(existing, child_loggers,
678 disable_existing)
679
680 # And finally, do the root logger
681 root = config.get('root', None)
682 if root:
683 try:
684 self.configure_root(root)
685 except Exception as e:
686 raise ValueError('Unable to configure root '
687 'logger') from e
688
689 def configure_formatter(self, config):
690 """Configure a formatter from a dictionary."""
691 if '()' in config:
692 factory = config['()'] # for use in exception handler
693 try:
694 result = self.configure_custom(config)
695 except TypeError as te:
696 if "'format'" not in str(te):
697 raise
698 # logging.Formatter and its subclasses expect the `fmt`
699 # parameter instead of `format`. Retry passing configuration
700 # with `fmt`.
701 config['fmt'] = config.pop('format')
702 config['()'] = factory
703 result = self.configure_custom(config)
704 else:
705 fmt = config.get('format', None)
706 dfmt = config.get('datefmt', None)
707 style = config.get('style', '%')
708 cname = config.get('class', None)
709 defaults = config.get('defaults', None)
710
711 if not cname:
712 c = logging.Formatter
713 else:
714 c = _resolve(cname)
715
716 kwargs = {}
717
718 # Add defaults only if it exists.
719 # Prevents TypeError in custom formatter callables that do not
720 # accept it.
721 if defaults is not None:
722 kwargs['defaults'] = defaults
723
724 # A TypeError would be raised if "validate" key is passed in with a formatter callable
725 # that does not accept "validate" as a parameter
726 if 'validate' in config: # if user hasn't mentioned it, the default will be fine
727 result = c(fmt, dfmt, style, config['validate'], **kwargs)
728 else:
729 result = c(fmt, dfmt, style, **kwargs)
730
731 return result
732
733 def configure_filter(self, config):
734 """Configure a filter from a dictionary."""
735 if '()' in config:
736 result = self.configure_custom(config)
737 else:
738 name = config.get('name', '')
739 result = logging.Filter(name)
740 return result
741
742 def add_filters(self, filterer, filters):
743 """Add filters to a filterer from a list of names."""
744 for f in filters:
745 try:
746 if callable(f) or callable(getattr(f, 'filter', None)):
747 filter_ = f
748 else:
749 filter_ = self.config['filters'][f]
750 filterer.addFilter(filter_)
751 except Exception as e:
752 raise ValueError('Unable to add filter %r' % f) from e
753
754 def _configure_queue_handler(self, klass, **kwargs):
755 if 'queue' in kwargs:
756 q = kwargs.pop('queue')
757 else:
758 q = queue.Queue() # unbounded
759
760 rhl = kwargs.pop('respect_handler_level', False)
761 lklass = kwargs.pop('listener', logging.handlers.QueueListener)
762 handlers = kwargs.pop('handlers', [])
763
764 listener = lklass(q, *handlers, respect_handler_level=rhl)
765 handler = klass(q, **kwargs)
766 handler.listener = listener
767 return handler
768
769 def configure_handler(self, config):
770 """Configure a handler from a dictionary."""
771 config_copy = dict(config) # for restoring in case of error
772 formatter = config.pop('formatter', None)
773 if formatter:
774 try:
775 formatter = self.config['formatters'][formatter]
776 except Exception as e:
777 raise ValueError('Unable to set formatter '
778 '%r' % formatter) from e
779 level = config.pop('level', None)
780 filters = config.pop('filters', None)
781 if '()' in config:
782 c = config.pop('()')
783 if not callable(c):
784 c = self.resolve(c)
785 factory = c
786 else:
787 cname = config.pop('class')
788 if callable(cname):
789 klass = cname
790 else:
791 klass = self.resolve(cname)
792 if issubclass(klass, logging.handlers.MemoryHandler):
793 if 'flushLevel' in config:
794 config['flushLevel'] = logging._checkLevel(config['flushLevel'])
795 if 'target' in config:
796 # Special case for handler which refers to another handler
797 try:
798 tn = config['target']
799 th = self.config['handlers'][tn]
800 if not isinstance(th, logging.Handler):
801 config.update(config_copy) # restore for deferred cfg
802 raise TypeError('target not configured yet')
803 config['target'] = th
804 except Exception as e:
805 raise ValueError('Unable to set target handler %r' % tn) from e
806 elif issubclass(klass, logging.handlers.QueueHandler):
807 # Another special case for handler which refers to other handlers
808 # if 'handlers' not in config:
809 # raise ValueError('No handlers specified for a QueueHandler')
810 if 'queue' in config:
811 qspec = config['queue']
812
813 if isinstance(qspec, str):
814 q = self.resolve(qspec)
815 if not callable(q):
816 raise TypeError('Invalid queue specifier %r' % qspec)
817 config['queue'] = q()
818 elif isinstance(qspec, dict):
819 if '()' not in qspec:
820 raise TypeError('Invalid queue specifier %r' % qspec)
821 config['queue'] = self.configure_custom(dict(qspec))
822 elif not _is_queue_like_object(qspec):
823 raise TypeError('Invalid queue specifier %r' % qspec)
824
825 if 'listener' in config:
826 lspec = config['listener']
827 if isinstance(lspec, type):
828 if not issubclass(lspec, logging.handlers.QueueListener):
829 raise TypeError('Invalid listener specifier %r' % lspec)
830 else:
831 if isinstance(lspec, str):
832 listener = self.resolve(lspec)
833 if isinstance(listener, type) and\
834 not issubclass(listener, logging.handlers.QueueListener):
835 raise TypeError('Invalid listener specifier %r' % lspec)
836 elif isinstance(lspec, dict):
837 if '()' not in lspec:
838 raise TypeError('Invalid listener specifier %r' % lspec)
839 listener = self.configure_custom(dict(lspec))
840 else:
841 raise TypeError('Invalid listener specifier %r' % lspec)
842 if not callable(listener):
843 raise TypeError('Invalid listener specifier %r' % lspec)
844 config['listener'] = listener
845 if 'handlers' in config:
846 hlist = []
847 try:
848 for hn in config['handlers']:
849 h = self.config['handlers'][hn]
850 if not isinstance(h, logging.Handler):
851 config.update(config_copy) # restore for deferred cfg
852 raise TypeError('Required handler %r '
853 'is not configured yet' % hn)
854 hlist.append(h)
855 except Exception as e:
856 raise ValueError('Unable to set required handler %r' % hn) from e
857 config['handlers'] = hlist
858 elif issubclass(klass, logging.handlers.SMTPHandler) and\
859 'mailhost' in config:
860 config['mailhost'] = self.as_tuple(config['mailhost'])
861 elif issubclass(klass, logging.handlers.SysLogHandler) and\
862 'address' in config:
863 config['address'] = self.as_tuple(config['address'])
864 if issubclass(klass, logging.handlers.QueueHandler):
865 factory = functools.partial(self._configure_queue_handler, klass)
866 else:
867 factory = klass
868 kwargs = {k: config[k] for k in config if (k != '.' and valid_ident(k))}
869 try:
870 result = factory(**kwargs)
871 except TypeError as te:
872 if "'stream'" not in str(te):
873 raise
874 #The argument name changed from strm to stream
875 #Retry with old name.
876 #This is so that code can be used with older Python versions
877 #(e.g. by Django)
878 kwargs['strm'] = kwargs.pop('stream')
879 result = factory(**kwargs)
880 if formatter:
881 result.setFormatter(formatter)
882 if level is not None:
883 result.setLevel(logging._checkLevel(level))
884 if filters:
885 self.add_filters(result, filters)
886 props = config.pop('.', None)
887 if props:
888 for name, value in props.items():
889 setattr(result, name, value)
890 return result
891
892 def add_handlers(self, logger, handlers):
893 """Add handlers to a logger from a list of names."""
894 for h in handlers:
895 try:
896 logger.addHandler(self.config['handlers'][h])
897 except Exception as e:
898 raise ValueError('Unable to add handler %r' % h) from e
899
900 def common_logger_config(self, logger, config, incremental=False):
901 """
902 Perform configuration which is common to root and non-root loggers.
903 """
904 level = config.get('level', None)
905 if level is not None:
906 logger.setLevel(logging._checkLevel(level))
907 if not incremental:
908 #Remove any existing handlers
909 for h in logger.handlers[:]:
910 logger.removeHandler(h)
911 handlers = config.get('handlers', None)
912 if handlers:
913 self.add_handlers(logger, handlers)
914 filters = config.get('filters', None)
915 if filters:
916 self.add_filters(logger, filters)
917
918 def configure_logger(self, name, config, incremental=False):
919 """Configure a non-root logger from a dictionary."""
920 logger = logging.getLogger(name)
921 self.common_logger_config(logger, config, incremental)
922 logger.disabled = False
923 propagate = config.get('propagate', None)
924 if propagate is not None:
925 logger.propagate = propagate
926
927 def configure_root(self, config, incremental=False):
928 """Configure a root logger from a dictionary."""
929 root = logging.getLogger()
930 self.common_logger_config(root, config, incremental)
931
932 dictConfigClass = DictConfigurator
933
934 def dictConfig(config):
935 """Configure logging using a dictionary."""
936 dictConfigClass(config).configure()
937
938
939 def listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None):
940 """
941 Start up a socket server on the specified port, and listen for new
942 configurations.
943
944 These will be sent as a file suitable for processing by fileConfig().
945 Returns a Thread object on which you can call start() to start the server,
946 and which you can join() when appropriate. To stop the server, call
947 stopListening().
948
949 Use the ``verify`` argument to verify any bytes received across the wire
950 from a client. If specified, it should be a callable which receives a
951 single argument - the bytes of configuration data received across the
952 network - and it should return either ``None``, to indicate that the
953 passed in bytes could not be verified and should be discarded, or a
954 byte string which is then passed to the configuration machinery as
955 normal. Note that you can return transformed bytes, e.g. by decrypting
956 the bytes passed in.
957 """
958
959 class ConfigStreamHandler(StreamRequestHandler):
960 """
961 Handler for a logging configuration request.
962
963 It expects a completely new logging configuration and uses fileConfig
964 to install it.
965 """
966 def handle(self):
967 """
968 Handle a request.
969
970 Each request is expected to be a 4-byte length, packed using
971 struct.pack(">L", n), followed by the config file.
972 Uses fileConfig() to do the grunt work.
973 """
974 try:
975 conn = self.connection
976 chunk = conn.recv(4)
977 if len(chunk) == 4:
978 slen = struct.unpack(">L", chunk)[0]
979 chunk = self.connection.recv(slen)
980 while len(chunk) < slen:
981 chunk = chunk + conn.recv(slen - len(chunk))
982 if self.server.verify is not None:
983 chunk = self.server.verify(chunk)
984 if chunk is not None: # verified, can process
985 chunk = chunk.decode("utf-8")
986 try:
987 import json
988 d =json.loads(chunk)
989 assert isinstance(d, dict)
990 dictConfig(d)
991 except Exception:
992 #Apply new configuration.
993
994 file = io.StringIO(chunk)
995 try:
996 fileConfig(file)
997 except Exception:
998 traceback.print_exc()
999 if self.server.ready:
1000 self.server.ready.set()
1001 except OSError as e:
1002 if e.errno != RESET_ERROR:
1003 raise
1004
1005 class ConfigSocketReceiver(ThreadingTCPServer):
1006 """
1007 A simple TCP socket-based logging config receiver.
1008 """
1009
1010 allow_reuse_address = 1
1011
1012 def __init__(self, host='localhost', port=DEFAULT_LOGGING_CONFIG_PORT,
1013 handler=None, ready=None, verify=None):
1014 # The host can have no IPv4 address, for example if "localhost"
1015 # is only aliased to ::1. Leave resolution errors to the server.
1016 try:
1017 infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
1018 except OSError:
1019 pass
1020 else:
1021 if not any(info[0] == socket.AF_INET for info in infos):
1022 self.address_family = infos[0][0]
1023 ThreadingTCPServer.__init__(self, (host, port), handler)
1024 with logging._lock:
1025 self.abort = 0
1026 self.timeout = 1
1027 self.ready = ready
1028 self.verify = verify
1029
1030 def serve_until_stopped(self):
1031 import select
1032 abort = 0
1033 while not abort:
1034 rd, wr, ex = select.select([self.socket.fileno()],
1035 [], [],
1036 self.timeout)
1037 if rd:
1038 self.handle_request()
1039 with logging._lock:
1040 abort = self.abort
1041 self.server_close()
1042
1043 class Server(threading.Thread):
1044
1045 def __init__(self, rcvr, hdlr, port, verify):
1046 super(Server, self).__init__()
1047 self.rcvr = rcvr
1048 self.hdlr = hdlr
1049 self.port = port
1050 self.verify = verify
1051 self.ready = threading.Event()
1052
1053 def run(self):
1054 try:
1055 server = self.rcvr(port=self.port, handler=self.hdlr,
1056 ready=self.ready,
1057 verify=self.verify)
1058 except BaseException:
1059 # Do not leave the caller waiting for ready forever.
1060 self.ready.set()
1061 raise
1062 if self.port == 0:
1063 self.port = server.server_address[1]
1064 self.ready.set()
1065 global _listener
1066 with logging._lock:
1067 _listener = server
1068 server.serve_until_stopped()
1069
1070 return Server(ConfigSocketReceiver, ConfigStreamHandler, port, verify)
1071
1072 def stopListening():
1073 """
1074 Stop the listening server which was created with a call to listen().
1075 """
1076 global _listener
1077 with logging._lock:
1078 if _listener:
1079 _listener.abort = 1
1080 _listener = None