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