Debian Codegraph @

Lib/logging/handlers.py

raw
1 # Copyright 2001-2021 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 Additional handlers for the logging package for Python. The core package is
19 based on PEP 282 and comments thereto in comp.lang.python.
20
21 Copyright (C) 2001-2021 Vinay Sajip. All Rights Reserved.
22
23 To use, simply 'import logging.handlers' and log away!
24 """
25
26 import copy
27 import io
28 import logging
29 import os
30 import pickle
31 import queue
32 import re
33 import socket
34 import struct
35 import threading
36 import time
37
38 #
39 # Some constants...
40 #
41
42 DEFAULT_TCP_LOGGING_PORT = 9020
43 DEFAULT_UDP_LOGGING_PORT = 9021
44 DEFAULT_HTTP_LOGGING_PORT = 9022
45 DEFAULT_SOAP_LOGGING_PORT = 9023
46 SYSLOG_UDP_PORT = 514
47 SYSLOG_TCP_PORT = 514
48
49 _MIDNIGHT = 24 * 60 * 60 # number of seconds in a day
50
51 class BaseRotatingHandler(logging.FileHandler):
52 """
53 Base class for handlers that rotate log files at a certain point.
54 Not meant to be instantiated directly. Instead, use RotatingFileHandler
55 or TimedRotatingFileHandler.
56 """
57 namer = None
58 rotator = None
59
60 def __init__(self, filename, mode, encoding=None, delay=False, errors=None):
61 """
62 Use the specified filename for streamed logging
63 """
64 logging.FileHandler.__init__(self, filename, mode=mode,
65 encoding=encoding, delay=delay,
66 errors=errors)
67 self.mode = mode
68 self.encoding = encoding
69 self.errors = errors
70
71 def emit(self, record):
72 """
73 Emit a record.
74
75 Output the record to the file, catering for rollover as described
76 in doRollover().
77 """
78 try:
79 if self.shouldRollover(record):
80 self.doRollover()
81 logging.FileHandler.emit(self, record)
82 except Exception:
83 self.handleError(record)
84
85 def rotation_filename(self, default_name):
86 """
87 Modify the filename of a log file when rotating.
88
89 This is provided so that a custom filename can be provided.
90
91 The default implementation calls the 'namer' attribute of the
92 handler, if it's callable, passing the default name to
93 it. If the attribute isn't callable (the default is None), the name
94 is returned unchanged.
95
96 :param default_name: The default name for the log file.
97 """
98 if not callable(self.namer):
99 result = default_name
100 else:
101 result = self.namer(default_name)
102 return result
103
104 def rotate(self, source, dest):
105 """
106 When rotating, rotate the current log.
107
108 The default implementation calls the 'rotator' attribute of the
109 handler, if it's callable, passing the source and dest arguments to
110 it. If the attribute isn't callable (the default is None), the source
111 is simply renamed to the destination.
112
113 :param source: The source filename. This is normally the base
114 filename, e.g. 'test.log'
115 :param dest: The destination filename. This is normally
116 what the source is rotated to, e.g. 'test.log.1'.
117 """
118 if not callable(self.rotator):
119 # Issue 18940: A file may not have been created if delay is True.
120 if os.path.exists(source):
121 os.rename(source, dest)
122 else:
123 self.rotator(source, dest)
124
125 class RotatingFileHandler(BaseRotatingHandler):
126 """
127 Handler for logging to a set of files, which switches from one file
128 to the next when the current file reaches a certain size.
129 """
130 def __init__(self, filename, mode='a', maxBytes=0, backupCount=0,
131 encoding=None, delay=False, errors=None):
132 """
133 Open the specified file and use it as the stream for logging.
134
135 By default, the file grows indefinitely. You can specify particular
136 values of maxBytes and backupCount to allow the file to rollover at
137 a predetermined size.
138
139 Rollover occurs whenever the current log file is nearly maxBytes in
140 length. If backupCount is >= 1, the system will successively create
141 new files with the same pathname as the base file, but with extensions
142 ".1", ".2" etc. appended to it. For example, with a backupCount of 5
143 and a base file name of "app.log", you would get "app.log",
144 "app.log.1", "app.log.2", ... through to "app.log.5". The file being
145 written to is always "app.log" - when it gets filled up, it is closed
146 and renamed to "app.log.1", and if files "app.log.1", "app.log.2" etc.
147 exist, then they are renamed to "app.log.2", "app.log.3" etc.
148 respectively.
149
150 If maxBytes is zero, rollover never occurs.
151 """
152 # If rotation/rollover is wanted, it doesn't make sense to use another
153 # mode. If for example 'w' were specified, then if there were multiple
154 # runs of the calling application, the logs from previous runs would be
155 # lost if the 'w' is respected, because the log file would be truncated
156 # on each run.
157 if maxBytes > 0:
158 mode = 'a'
159 if "b" not in mode:
160 encoding = io.text_encoding(encoding)
161 BaseRotatingHandler.__init__(self, filename, mode, encoding=encoding,
162 delay=delay, errors=errors)
163 self.maxBytes = maxBytes
164 self.backupCount = backupCount
165
166 def doRollover(self):
167 """
168 Do a rollover, as described in __init__().
169 """
170 if self.stream:
171 self.stream.close()
172 self.stream = None
173 if self.backupCount > 0:
174 for i in range(self.backupCount - 1, 0, -1):
175 sfn = self.rotation_filename("%s.%d" % (self.baseFilename, i))
176 dfn = self.rotation_filename("%s.%d" % (self.baseFilename,
177 i + 1))
178 if os.path.exists(sfn):
179 if os.path.exists(dfn):
180 os.remove(dfn)
181 os.rename(sfn, dfn)
182 dfn = self.rotation_filename(self.baseFilename + ".1")
183 if os.path.exists(dfn):
184 os.remove(dfn)
185 self.rotate(self.baseFilename, dfn)
186 if not self.delay:
187 self.stream = self._open()
188
189 def shouldRollover(self, record):
190 """
191 Determine if rollover should occur.
192
193 Basically, see if the supplied record would cause the file to exceed
194 the size limit we have.
195 """
196 if self.stream is None: # delay was set...
197 self.stream = self._open()
198 if self.maxBytes > 0: # are we rolling over?
199 try:
200 pos = self.stream.tell()
201 except io.UnsupportedOperation:
202 # gh-143237: Never rollover a named pipe.
203 return False
204 if not pos:
205 # gh-116263: Never rollover an empty file
206 return False
207 msg = "%s\n" % self.format(record)
208 if pos + len(msg) >= self.maxBytes:
209 # See bpo-45401: Never rollover anything other than regular files
210 if os.path.exists(self.baseFilename) and not os.path.isfile(self.baseFilename):
211 return False
212 return True
213 return False
214
215 class TimedRotatingFileHandler(BaseRotatingHandler):
216 """
217 Handler for logging to a file, rotating the log file at certain timed
218 intervals.
219
220 If backupCount is > 0, when rollover is done, no more than backupCount
221 files are kept - the oldest ones are deleted.
222 """
223 def __init__(self, filename, when='h', interval=1, backupCount=0,
224 encoding=None, delay=False, utc=False, atTime=None,
225 errors=None):
226 encoding = io.text_encoding(encoding)
227 BaseRotatingHandler.__init__(self, filename, 'a', encoding=encoding,
228 delay=delay, errors=errors)
229 self.when = when.upper()
230 self.backupCount = backupCount
231 self.utc = utc
232 self.atTime = atTime
233 # Calculate the real rollover interval, which is just the number of
234 # seconds between rollovers. Also set the filename suffix used when
235 # a rollover occurs. Current 'when' events supported:
236 # S - Seconds
237 # M - Minutes
238 # H - Hours
239 # D - Days
240 # midnight - roll over at midnight
241 # W{0-6} - roll over on a certain day; 0 - Monday
242 #
243 # Case of the 'when' specifier is not important; lower or upper case
244 # will work.
245 if self.when == 'S':
246 self.interval = 1 # one second
247 self.suffix = "%Y-%m-%d_%H-%M-%S"
248 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?!\d)"
249 elif self.when == 'M':
250 self.interval = 60 # one minute
251 self.suffix = "%Y-%m-%d_%H-%M"
252 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}_\d{2}-\d{2}(?!\d)"
253 elif self.when == 'H':
254 self.interval = 60 * 60 # one hour
255 self.suffix = "%Y-%m-%d_%H"
256 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}_\d{2}(?!\d)"
257 elif self.when == 'D' or self.when == 'MIDNIGHT':
258 self.interval = 60 * 60 * 24 # one day
259 self.suffix = "%Y-%m-%d"
260 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}(?!\d)"
261 elif self.when.startswith('W'):
262 self.interval = 60 * 60 * 24 * 7 # one week
263 if len(self.when) != 2:
264 raise ValueError("You must specify a day for weekly rollover from 0 to 6 (0 is Monday): %s" % self.when)
265 if self.when[1] < '0' or self.when[1] > '6':
266 raise ValueError("Invalid day specified for weekly rollover: %s" % self.when)
267 self.dayOfWeek = int(self.when[1])
268 self.suffix = "%Y-%m-%d"
269 extMatch = r"(?<!\d)\d{4}-\d{2}-\d{2}(?!\d)"
270 else:
271 raise ValueError("Invalid rollover interval specified: %s" % self.when)
272
273 # extMatch is a pattern for matching a datetime suffix in a file name.
274 # After custom naming, it is no longer guaranteed to be separated by
275 # periods from other parts of the filename. The lookup statements
276 # (?<!\d) and (?!\d) ensure that the datetime suffix (which itself
277 # starts and ends with digits) is not preceded or followed by digits.
278 # This reduces the number of false matches and improves performance.
279 self.extMatch = re.compile(extMatch, re.ASCII)
280 self.interval = self.interval * interval # multiply by units requested
281 # The following line added because the filename passed in could be a
282 # path object (see Issue #27493), but self.baseFilename will be a string
283 filename = self.baseFilename
284 if os.path.exists(filename):
285 t = int(os.stat(filename).st_mtime)
286 else:
287 t = int(time.time())
288 self.rolloverAt = self.computeRollover(t)
289
290 def computeRollover(self, currentTime):
291 """
292 Work out the rollover time based on the specified time.
293 """
294 result = currentTime + self.interval
295 # If we are rolling over at midnight or weekly, then the interval is already known.
296 # What we need to figure out is WHEN the next interval is. In other words,
297 # if you are rolling over at midnight, then your base interval is 1 day,
298 # but you want to start that one day clock at midnight, not now. So, we
299 # have to fudge the rolloverAt value in order to trigger the first rollover
300 # at the right time. After that, the regular interval will take care of
301 # the rest. Note that this code doesn't care about leap seconds. :)
302 if self.when == 'MIDNIGHT' or self.when.startswith('W'):
303 # This could be done with less code, but I wanted it to be clear
304 if self.utc:
305 t = time.gmtime(currentTime)
306 else:
307 t = time.localtime(currentTime)
308 currentHour = t[3]
309 currentMinute = t[4]
310 currentSecond = t[5]
311 currentDay = t[6]
312 # r is the number of seconds left between now and the next rotation
313 if self.atTime is None:
314 rotate_ts = _MIDNIGHT
315 else:
316 rotate_ts = ((self.atTime.hour * 60 + self.atTime.minute)*60 +
317 self.atTime.second)
318
319 r = rotate_ts - ((currentHour * 60 + currentMinute) * 60 +
320 currentSecond)
321 if r <= 0:
322 # Rotate time is before the current time (for example when
323 # self.rotateAt is 13:45 and it now 14:15), rotation is
324 # tomorrow.
325 r += _MIDNIGHT
326 currentDay = (currentDay + 1) % 7
327 result = currentTime + r
328 # If we are rolling over on a certain day, add in the number of days until
329 # the next rollover, but offset by 1 since we just calculated the time
330 # until the next day starts. There are three cases:
331 # Case 1) The day to rollover is today; in this case, do nothing
332 # Case 2) The day to rollover is further in the interval (i.e., today is
333 # day 2 (Wednesday) and rollover is on day 6 (Sunday). Days to
334 # next rollover is simply 6 - 2 - 1, or 3.
335 # Case 3) The day to rollover is behind us in the interval (i.e., today
336 # is day 5 (Saturday) and rollover is on day 3 (Thursday).
337 # Days to rollover is 6 - 5 + 3, or 4. In this case, it's the
338 # number of days left in the current week (1) plus the number
339 # of days in the next week until the rollover day (3).
340 # The calculations described in 2) and 3) above need to have a day added.
341 # This is because the above time calculation takes us to midnight on this
342 # day, i.e. the start of the next day.
343 if self.when.startswith('W'):
344 day = currentDay # 0 is Monday
345 if day != self.dayOfWeek:
346 if day < self.dayOfWeek:
347 daysToWait = self.dayOfWeek - day
348 else:
349 daysToWait = 6 - day + self.dayOfWeek + 1
350 result += daysToWait * _MIDNIGHT
351 result += self.interval - _MIDNIGHT * 7
352 else:
353 result += self.interval - _MIDNIGHT
354 if not self.utc:
355 dstNow = t[-1]
356 dstAtRollover = time.localtime(result)[-1]
357 if dstNow != dstAtRollover:
358 if not dstNow: # DST kicks in before next rollover, so we need to deduct an hour
359 addend = -3600
360 if not time.localtime(result-3600)[-1]:
361 addend = 0
362 else: # DST bows out before next rollover, so we need to add an hour
363 addend = 3600
364 result += addend
365 return result
366
367 def shouldRollover(self, record):
368 """
369 Determine if rollover should occur.
370
371 record is not used, as we are just comparing times, but it is needed so
372 the method signatures are the same
373 """
374 t = int(time.time())
375 if t >= self.rolloverAt:
376 # See #89564: Never rollover anything other than regular files
377 if os.path.exists(self.baseFilename) and not os.path.isfile(self.baseFilename):
378 # The file is not a regular file, so do not rollover, but do
379 # set the next rollover time to avoid repeated checks.
380 self.rolloverAt = self.computeRollover(t)
381 return False
382
383 return True
384 return False
385
386 def getFilesToDelete(self):
387 """
388 Determine the files to delete when rolling over.
389
390 More specific than the earlier method, which just used glob.glob().
391 """
392 dirName, baseName = os.path.split(self.baseFilename)
393 fileNames = os.listdir(dirName)
394 result = []
395 if self.namer is None:
396 prefix = baseName + '.'
397 plen = len(prefix)
398 for fileName in fileNames:
399 if fileName[:plen] == prefix:
400 suffix = fileName[plen:]
401 if self.extMatch.fullmatch(suffix):
402 result.append(os.path.join(dirName, fileName))
403 else:
404 for fileName in fileNames:
405 # Our files could be just about anything after custom naming,
406 # but they should contain the datetime suffix.
407 # Try to find the datetime suffix in the file name and verify
408 # that the file name can be generated by this handler.
409 m = self.extMatch.search(fileName)
410 while m:
411 dfn = self.namer(self.baseFilename + "." + m[0])
412 if os.path.basename(dfn) == fileName:
413 result.append(os.path.join(dirName, fileName))
414 break
415 m = self.extMatch.search(fileName, m.start() + 1)
416
417 if len(result) < self.backupCount:
418 result = []
419 else:
420 result.sort()
421 result = result[:len(result) - self.backupCount]
422 return result
423
424 def doRollover(self):
425 """
426 do a rollover; in this case, a date/time stamp is appended to the filename
427 when the rollover happens. However, you want the file to be named for the
428 start of the interval, not the current time. If there is a backup count,
429 then we have to get a list of matching filenames, sort them and remove
430 the one with the oldest suffix.
431 """
432 # get the time that this sequence started at and make it a TimeTuple
433 currentTime = int(time.time())
434 t = self.rolloverAt - self.interval
435 if self.utc:
436 timeTuple = time.gmtime(t)
437 else:
438 timeTuple = time.localtime(t)
439 dstNow = time.localtime(currentTime)[-1]
440 dstThen = timeTuple[-1]
441 if dstNow != dstThen:
442 if dstNow:
443 addend = 3600
444 else:
445 addend = -3600
446 timeTuple = time.localtime(t + addend)
447 dfn = self.rotation_filename(self.baseFilename + "." +
448 time.strftime(self.suffix, timeTuple))
449 if os.path.exists(dfn):
450 # Already rolled over.
451 return
452
453 if self.stream:
454 self.stream.close()
455 self.stream = None
456 self.rotate(self.baseFilename, dfn)
457 if self.backupCount > 0:
458 for s in self.getFilesToDelete():
459 os.remove(s)
460 if not self.delay:
461 self.stream = self._open()
462 self.rolloverAt = self.computeRollover(currentTime)
463
464 class WatchedFileHandler(logging.FileHandler):
465 """
466 A handler for logging to a file, which watches the file
467 to see if it has changed while in use. This can happen because of
468 usage of programs such as newsyslog and logrotate which perform
469 log file rotation. This handler, intended for use under Unix,
470 watches the file to see if it has changed since the last emit.
471 (A file has changed if its device or inode have changed.)
472 If it has changed, the old file stream is closed, and the file
473 opened to get a new stream.
474
475 This handler is not appropriate for use under Windows, because
476 under Windows open files cannot be moved or renamed - logging
477 opens the files with exclusive locks - and so there is no need
478 for such a handler.
479
480 This handler is based on a suggestion and patch by Chad J.
481 Schroeder.
482 """
483 def __init__(self, filename, mode='a', encoding=None, delay=False,
484 errors=None):
485 if "b" not in mode:
486 encoding = io.text_encoding(encoding)
487 logging.FileHandler.__init__(self, filename, mode=mode,
488 encoding=encoding, delay=delay,
489 errors=errors)
490 self.dev, self.ino = -1, -1
491 self._statstream()
492
493 def _statstream(self):
494 if self.stream is None:
495 return
496 sres = os.fstat(self.stream.fileno())
497 self.dev = sres.st_dev
498 self.ino = sres.st_ino
499
500 def reopenIfNeeded(self):
501 """
502 Reopen log file if needed.
503
504 Checks if the underlying file has changed, and if it
505 has, close the old stream and reopen the file to get the
506 current stream.
507 """
508 if self.stream is None:
509 return
510
511 # Reduce the chance of race conditions by stat'ing by path only
512 # once and then fstat'ing our new fd if we opened a new log stream.
513 # See issue #14632: Thanks to John Mulligan for the problem report
514 # and patch.
515 try:
516 # stat the file by path, checking for existence
517 sres = os.stat(self.baseFilename)
518
519 # compare file system stat with that of our stream file handle
520 reopen = (sres.st_dev != self.dev or sres.st_ino != self.ino)
521 except FileNotFoundError:
522 reopen = True
523
524 if not reopen:
525 return
526
527 # we have an open file handle, clean it up
528 self.stream.flush()
529 self.stream.close()
530 self.stream = None # See Issue #21742: _open () might fail.
531
532 # open a new file handle and get new stat info from that fd
533 self.stream = self._open()
534 self._statstream()
535
536 def emit(self, record):
537 """
538 Emit a record.
539
540 If underlying file has changed, reopen the file before emitting the
541 record to it.
542 """
543 self.reopenIfNeeded()
544 logging.FileHandler.emit(self, record)
545
546
547 class SocketHandler(logging.Handler):
548 """
549 A handler class which writes logging records, in pickle format, to
550 a streaming socket. The socket is kept open across logging calls.
551 If the peer resets it, an attempt is made to reconnect on the next call.
552 The pickle which is sent is that of the LogRecord's attribute dictionary
553 (__dict__), so that the receiver does not need to have the logging module
554 installed in order to process the logging event.
555
556 To unpickle the record at the receiving end into a LogRecord, use the
557 makeLogRecord function.
558 """
559
560 def __init__(self, host, port):
561 """
562 Initializes the handler with a specific host address and port.
563
564 When the attribute *closeOnError* is set to True - if a socket error
565 occurs, the socket is silently closed and then reopened on the next
566 logging call.
567 """
568 logging.Handler.__init__(self)
569 self.host = host
570 self.port = port
571 if port is None:
572 self.address = host
573 else:
574 self.address = (host, port)
575 self.sock = None
576 self.closeOnError = False
577 self.retryTime = None
578 #
579 # Exponential backoff parameters.
580 #
581 self.retryStart = 1.0
582 self.retryMax = 30.0
583 self.retryFactor = 2.0
584
585 def makeSocket(self, timeout=1):
586 """
587 A factory method which allows subclasses to define the precise
588 type of socket they want.
589 """
590 if self.port is not None:
591 result = socket.create_connection(self.address, timeout=timeout)
592 else:
593 result = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
594 result.settimeout(timeout)
595 try:
596 result.connect(self.address)
597 except OSError:
598 result.close() # Issue 19182
599 raise
600 return result
601
602 def createSocket(self):
603 """
604 Try to create a socket, using an exponential backoff with
605 a max retry time. Thanks to Robert Olson for the original patch
606 (SF #815911) which has been slightly refactored.
607 """
608 now = time.time()
609 # Either retryTime is None, in which case this
610 # is the first time back after a disconnect, or
611 # we've waited long enough.
612 if self.retryTime is None:
613 attempt = True
614 else:
615 attempt = (now >= self.retryTime)
616 if attempt:
617 try:
618 self.sock = self.makeSocket()
619 self.retryTime = None # next time, no delay before trying
620 except OSError:
621 #Creation failed, so set the retry time and return.
622 if self.retryTime is None:
623 self.retryPeriod = self.retryStart
624 else:
625 self.retryPeriod = self.retryPeriod * self.retryFactor
626 if self.retryPeriod > self.retryMax:
627 self.retryPeriod = self.retryMax
628 self.retryTime = now + self.retryPeriod
629
630 def send(self, s):
631 """
632 Send a pickled string to the socket.
633
634 This function allows for partial sends which can happen when the
635 network is busy.
636 """
637 if self.sock is None:
638 self.createSocket()
639 #self.sock can be None either because we haven't reached the retry
640 #time yet, or because we have reached the retry time and retried,
641 #but are still unable to connect.
642 if self.sock:
643 try:
644 self.sock.sendall(s)
645 except OSError: #pragma: no cover
646 self.sock.close()
647 self.sock = None # so we can call createSocket next time
648
649 def makePickle(self, record):
650 """
651 Pickles the record in binary format with a length prefix, and
652 returns it ready for transmission across the socket.
653 """
654 ei = record.exc_info
655 if ei:
656 # just to get traceback text into record.exc_text ...
657 dummy = self.format(record)
658 # See issue #14436: If msg or args are objects, they may not be
659 # available on the receiving end. So we convert the msg % args
660 # to a string, save it as msg and zap the args.
661 d = dict(record.__dict__)
662 d['msg'] = record.getMessage()
663 d['args'] = None
664 d['exc_info'] = None
665 # Issue #25685: delete 'message' if present: redundant with 'msg'
666 d.pop('message', None)
667 s = pickle.dumps(d, 1)
668 slen = struct.pack(">L", len(s))
669 return slen + s
670
671 def handleError(self, record):
672 """
673 Handle an error during logging.
674
675 An error has occurred during logging. Most likely cause -
676 connection lost. Close the socket so that we can retry on the
677 next event.
678 """
679 if self.closeOnError and self.sock:
680 self.sock.close()
681 self.sock = None #try to reconnect next time
682 else:
683 logging.Handler.handleError(self, record)
684
685 def emit(self, record):
686 """
687 Emit a record.
688
689 Pickles the record and writes it to the socket in binary format.
690 If there is an error with the socket, silently drop the packet.
691 If there was a problem with the socket, re-establishes the
692 socket.
693 """
694 try:
695 s = self.makePickle(record)
696 self.send(s)
697 except Exception:
698 self.handleError(record)
699
700 def close(self):
701 """
702 Closes the socket.
703 """
704 with self.lock:
705 sock = self.sock
706 if sock:
707 self.sock = None
708 sock.close()
709 logging.Handler.close(self)
710
711 class DatagramHandler(SocketHandler):
712 """
713 A handler class which writes logging records, in pickle format, to
714 a datagram socket. The pickle which is sent is that of the LogRecord's
715 attribute dictionary (__dict__), so that the receiver does not need to
716 have the logging module installed in order to process the logging event.
717
718 To unpickle the record at the receiving end into a LogRecord, use the
719 makeLogRecord function.
720
721 """
722 def __init__(self, host, port):
723 """
724 Initializes the handler with a specific host address and port.
725 """
726 SocketHandler.__init__(self, host, port)
727 self.closeOnError = False
728
729 def makeSocket(self):
730 """
731 The factory method of SocketHandler is here overridden to create
732 a UDP socket (SOCK_DGRAM).
733 """
734 if self.port is None:
735 family = socket.AF_UNIX
736 else:
737 family = socket.AF_INET
738 s = socket.socket(family, socket.SOCK_DGRAM)
739 return s
740
741 def send(self, s):
742 """
743 Send a pickled string to a socket.
744
745 This function no longer allows for partial sends which can happen
746 when the network is busy - UDP does not guarantee delivery and
747 can deliver packets out of sequence.
748 """
749 if self.sock is None:
750 self.createSocket()
751 self.sock.sendto(s, self.address)
752
753 class SysLogHandler(logging.Handler):
754 """
755 A handler class which sends formatted logging records to a syslog
756 server. Based on Sam Rushing's syslog module:
757 http://www.nightmare.com/squirl/python-ext/misc/syslog.py
758 Contributed by Nicolas Untz (after which minor refactoring changes
759 have been made).
760 """
761
762 # from <linux/sys/syslog.h>:
763 # ======================================================================
764 # priorities/facilities are encoded into a single 32-bit quantity, where
765 # the bottom 3 bits are the priority (0-7) and the top 28 bits are the
766 # facility (0-big number). Both the priorities and the facilities map
767 # roughly one-to-one to strings in the syslogd(8) source code. This
768 # mapping is included in this file.
769 #
770 # priorities (these are ordered)
771
772 LOG_EMERG = 0 # system is unusable
773 LOG_ALERT = 1 # action must be taken immediately
774 LOG_CRIT = 2 # critical conditions
775 LOG_ERR = 3 # error conditions
776 LOG_WARNING = 4 # warning conditions
777 LOG_NOTICE = 5 # normal but significant condition
778 LOG_INFO = 6 # informational
779 LOG_DEBUG = 7 # debug-level messages
780
781 # facility codes
782 LOG_KERN = 0 # kernel messages
783 LOG_USER = 1 # random user-level messages
784 LOG_MAIL = 2 # mail system
785 LOG_DAEMON = 3 # system daemons
786 LOG_AUTH = 4 # security/authorization messages
787 LOG_SYSLOG = 5 # messages generated internally by syslogd
788 LOG_LPR = 6 # line printer subsystem
789 LOG_NEWS = 7 # network news subsystem
790 LOG_UUCP = 8 # UUCP subsystem
791 LOG_CRON = 9 # clock daemon
792 LOG_AUTHPRIV = 10 # security/authorization messages (private)
793 LOG_FTP = 11 # FTP daemon
794 LOG_NTP = 12 # NTP subsystem
795 LOG_SECURITY = 13 # Log audit
796 LOG_CONSOLE = 14 # Log alert
797 LOG_SOLCRON = 15 # Scheduling daemon (Solaris)
798
799 # other codes through 15 reserved for system use
800 LOG_LOCAL0 = 16 # reserved for local use
801 LOG_LOCAL1 = 17 # reserved for local use
802 LOG_LOCAL2 = 18 # reserved for local use
803 LOG_LOCAL3 = 19 # reserved for local use
804 LOG_LOCAL4 = 20 # reserved for local use
805 LOG_LOCAL5 = 21 # reserved for local use
806 LOG_LOCAL6 = 22 # reserved for local use
807 LOG_LOCAL7 = 23 # reserved for local use
808
809 priority_names = {
810 "alert": LOG_ALERT,
811 "crit": LOG_CRIT,
812 "critical": LOG_CRIT,
813 "debug": LOG_DEBUG,
814 "emerg": LOG_EMERG,
815 "err": LOG_ERR,
816 "error": LOG_ERR, # DEPRECATED
817 "info": LOG_INFO,
818 "notice": LOG_NOTICE,
819 "panic": LOG_EMERG, # DEPRECATED
820 "warn": LOG_WARNING, # DEPRECATED
821 "warning": LOG_WARNING,
822 }
823
824 facility_names = {
825 "auth": LOG_AUTH,
826 "authpriv": LOG_AUTHPRIV,
827 "console": LOG_CONSOLE,
828 "cron": LOG_CRON,
829 "daemon": LOG_DAEMON,
830 "ftp": LOG_FTP,
831 "kern": LOG_KERN,
832 "lpr": LOG_LPR,
833 "mail": LOG_MAIL,
834 "news": LOG_NEWS,
835 "ntp": LOG_NTP,
836 "security": LOG_SECURITY,
837 "solaris-cron": LOG_SOLCRON,
838 "syslog": LOG_SYSLOG,
839 "user": LOG_USER,
840 "uucp": LOG_UUCP,
841 "local0": LOG_LOCAL0,
842 "local1": LOG_LOCAL1,
843 "local2": LOG_LOCAL2,
844 "local3": LOG_LOCAL3,
845 "local4": LOG_LOCAL4,
846 "local5": LOG_LOCAL5,
847 "local6": LOG_LOCAL6,
848 "local7": LOG_LOCAL7,
849 }
850
851 # Originally added to work around GH-43683. Unnecessary since GH-50043 but kept
852 # for backwards compatibility.
853 priority_map = {
854 "DEBUG" : "debug",
855 "INFO" : "info",
856 "WARNING" : "warning",
857 "ERROR" : "error",
858 "CRITICAL" : "critical"
859 }
860
861 def __init__(self, address=('localhost', SYSLOG_UDP_PORT),
862 facility=LOG_USER, socktype=None):
863 """
864 Initialize a handler.
865
866 If address is specified as a string, a UNIX socket is used. To log to a
867 local syslogd, "SysLogHandler(address="/dev/log")" can be used.
868 If facility is not specified, LOG_USER is used. If socktype is
869 specified as socket.SOCK_DGRAM or socket.SOCK_STREAM, that specific
870 socket type will be used. For Unix sockets, you can also specify a
871 socktype of None, in which case socket.SOCK_DGRAM will be used, falling
872 back to socket.SOCK_STREAM.
873 """
874 logging.Handler.__init__(self)
875
876 self.address = address
877 self.facility = facility
878 self.socktype = socktype
879 self.socket = None
880 self.createSocket()
881
882 def _connect_unixsocket(self, address):
883 use_socktype = self.socktype
884 if use_socktype is None:
885 use_socktype = socket.SOCK_DGRAM
886 self.socket = socket.socket(socket.AF_UNIX, use_socktype)
887 try:
888 self.socket.connect(address)
889 # it worked, so set self.socktype to the used type
890 self.socktype = use_socktype
891 except OSError:
892 self.socket.close()
893 if self.socktype is not None:
894 # user didn't specify falling back, so fail
895 raise
896 use_socktype = socket.SOCK_STREAM
897 self.socket = socket.socket(socket.AF_UNIX, use_socktype)
898 try:
899 self.socket.connect(address)
900 # it worked, so set self.socktype to the used type
901 self.socktype = use_socktype
902 except OSError:
903 self.socket.close()
904 raise
905
906 def createSocket(self):
907 """
908 Try to create a socket and, if it's not a datagram socket, connect it
909 to the other end. This method is called during handler initialization,
910 but it's not regarded as an error if the other end isn't listening yet
911 --- the method will be called again when emitting an event,
912 if there is no socket at that point.
913 """
914 address = self.address
915 socktype = self.socktype
916
917 if isinstance(address, str):
918 self.unixsocket = True
919 # Syslog server may be unavailable during handler initialisation.
920 # C's openlog() function also ignores connection errors.
921 # Moreover, we ignore these errors while logging, so it's not worse
922 # to ignore it also here.
923 try:
924 self._connect_unixsocket(address)
925 except OSError:
926 pass
927 else:
928 self.unixsocket = False
929 if socktype is None:
930 socktype = socket.SOCK_DGRAM
931 host, port = address
932 ress = socket.getaddrinfo(host, port, 0, socktype)
933 if not ress:
934 raise OSError("getaddrinfo returns an empty list")
935 for res in ress:
936 af, socktype, proto, _, sa = res
937 err = sock = None
938 try:
939 sock = socket.socket(af, socktype, proto)
940 if socktype == socket.SOCK_STREAM:
941 sock.connect(sa)
942 break
943 except OSError as exc:
944 err = exc
945 if sock is not None:
946 sock.close()
947 if err is not None:
948 raise err
949 self.socket = sock
950 self.socktype = socktype
951
952 def encodePriority(self, facility, priority):
953 """
954 Encode the facility and priority. You can pass in strings or
955 integers - if strings are passed, the facility_names and
956 priority_names mapping dictionaries are used to convert them to
957 integers.
958 """
959 if isinstance(facility, str):
960 facility = self.facility_names[facility]
961 if isinstance(priority, str):
962 priority = self.priority_names[priority]
963 return (facility << 3) | priority
964
965 def close(self):
966 """
967 Closes the socket.
968 """
969 with self.lock:
970 sock = self.socket
971 if sock:
972 self.socket = None
973 sock.close()
974 logging.Handler.close(self)
975
976 def mapPriority(self, levelName):
977 """
978 Map a logging level name to a key in the priority_names map.
979 This is useful in two scenarios: when custom levels are being
980 used, and in the case where you can't do a straightforward
981 mapping by lowercasing the logging level name because of locale-
982 specific issues (see SF #1524081).
983 """
984 return self.priority_map.get(levelName, "warning")
985
986 ident = '' # prepended to all messages
987 append_nul = True # some old syslog daemons expect a NUL terminator
988
989 def emit(self, record):
990 """
991 Emit a record.
992
993 The record is formatted, and then sent to the syslog server. If
994 exception information is present, it is NOT sent to the server.
995 """
996 try:
997 msg = self.format(record)
998 if self.ident:
999 msg = self.ident + msg
1000 if self.append_nul:
1001 msg += '\000'
1002
1003 # We need to convert record level to lowercase, maybe this will
1004 # change in the future.
1005 prio = '<%d>' % self.encodePriority(self.facility,
1006 self.mapPriority(record.levelname))
1007 prio = prio.encode('utf-8')
1008 # Message is a string. Convert to bytes as required by RFC 5424
1009 msg = msg.encode('utf-8')
1010 msg = prio + msg
1011
1012 if not self.socket:
1013 self.createSocket()
1014
1015 if self.unixsocket:
1016 try:
1017 self.socket.send(msg)
1018 except OSError:
1019 self.socket.close()
1020 self._connect_unixsocket(self.address)
1021 self.socket.send(msg)
1022 elif self.socktype == socket.SOCK_DGRAM:
1023 self.socket.sendto(msg, self.address)
1024 else:
1025 self.socket.sendall(msg)
1026 except Exception:
1027 self.handleError(record)
1028
1029 class SMTPHandler(logging.Handler):
1030 """
1031 A handler class which sends an SMTP email for each logging event.
1032 """
1033 def __init__(self, mailhost, fromaddr, toaddrs, subject,
1034 credentials=None, secure=None, timeout=5.0):
1035 """
1036 Initialize the handler.
1037
1038 Initialize the instance with the from and to addresses and subject
1039 line of the email. To specify a non-standard SMTP port, use the
1040 (host, port) tuple format for the mailhost argument. To specify
1041 authentication credentials, supply a (username, password) tuple
1042 for the credentials argument. To specify the use of a secure
1043 protocol (TLS), pass in a tuple for the secure argument. This will
1044 only be used when authentication credentials are supplied. The tuple
1045 will be either an empty tuple, or a single-value tuple with the name
1046 of a keyfile, or a 2-value tuple with the names of the keyfile and
1047 certificate file. (This tuple is passed to the
1048 `ssl.SSLContext.load_cert_chain` method).
1049 A timeout in seconds can be specified for the SMTP connection (the
1050 default is one second).
1051 """
1052 logging.Handler.__init__(self)
1053 if isinstance(mailhost, (list, tuple)):
1054 self.mailhost, self.mailport = mailhost
1055 else:
1056 self.mailhost, self.mailport = mailhost, None
1057 if isinstance(credentials, (list, tuple)):
1058 self.username, self.password = credentials
1059 else:
1060 self.username = None
1061 self.fromaddr = fromaddr
1062 if isinstance(toaddrs, str):
1063 toaddrs = [toaddrs]
1064 self.toaddrs = toaddrs
1065 self.subject = subject
1066 self.secure = secure
1067 self.timeout = timeout
1068
1069 def getSubject(self, record):
1070 """
1071 Determine the subject for the email.
1072
1073 If you want to specify a subject line which is record-dependent,
1074 override this method.
1075 """
1076 return self.subject
1077
1078 def emit(self, record):
1079 """
1080 Emit a record.
1081
1082 Format the record and send it to the specified addressees.
1083 """
1084 try:
1085 import smtplib
1086 from email.message import EmailMessage
1087 import email.utils
1088
1089 port = self.mailport
1090 if not port:
1091 port = smtplib.SMTP_PORT
1092 smtp = smtplib.SMTP(self.mailhost, port, timeout=self.timeout)
1093 msg = EmailMessage()
1094 msg['From'] = self.fromaddr
1095 msg['To'] = ','.join(self.toaddrs)
1096 msg['Subject'] = self.getSubject(record)
1097 msg['Date'] = email.utils.localtime()
1098 msg.set_content(self.format(record))
1099 if self.username:
1100 if self.secure is not None:
1101 import ssl
1102
1103 try:
1104 keyfile = self.secure[0]
1105 except IndexError:
1106 keyfile = None
1107
1108 try:
1109 certfile = self.secure[1]
1110 except IndexError:
1111 certfile = None
1112
1113 context = ssl._create_stdlib_context(
1114 certfile=certfile, keyfile=keyfile
1115 )
1116 smtp.ehlo()
1117 smtp.starttls(context=context)
1118 smtp.ehlo()
1119 smtp.login(self.username, self.password)
1120 smtp.send_message(msg)
1121 smtp.quit()
1122 except Exception:
1123 self.handleError(record)
1124
1125 class NTEventLogHandler(logging.Handler):
1126 """
1127 A handler class which sends events to the NT Event Log. Adds a
1128 registry entry for the specified application name. If no dllname is
1129 provided, win32service.pyd (which contains some basic message
1130 placeholders) is used. Note that use of these placeholders will make
1131 your event logs big, as the entire message source is held in the log.
1132 If you want slimmer logs, you have to pass in the name of your own DLL
1133 which contains the message definitions you want to use in the event log.
1134 """
1135 def __init__(self, appname, dllname=None, logtype="Application"):
1136 logging.Handler.__init__(self)
1137 try:
1138 import win32evtlogutil, win32evtlog
1139 self.appname = appname
1140 self._welu = win32evtlogutil
1141 if not dllname:
1142 dllname = os.path.split(self._welu.__file__)
1143 dllname = os.path.split(dllname[0])
1144 dllname = os.path.join(dllname[0], r'win32service.pyd')
1145 self.dllname = dllname
1146 self.logtype = logtype
1147 # Administrative privileges are required to add a source to the registry.
1148 # This may not be available for a user that just wants to add to an
1149 # existing source - handle this specific case.
1150 try:
1151 self._welu.AddSourceToRegistry(appname, dllname, logtype)
1152 except Exception as e:
1153 # This will probably be a pywintypes.error. Only raise if it's not
1154 # an "access denied" error, else let it pass
1155 if getattr(e, 'winerror', None) != 5: # not access denied
1156 raise
1157 self.deftype = win32evtlog.EVENTLOG_ERROR_TYPE
1158 self.typemap = {
1159 logging.DEBUG : win32evtlog.EVENTLOG_INFORMATION_TYPE,
1160 logging.INFO : win32evtlog.EVENTLOG_INFORMATION_TYPE,
1161 logging.WARNING : win32evtlog.EVENTLOG_WARNING_TYPE,
1162 logging.ERROR : win32evtlog.EVENTLOG_ERROR_TYPE,
1163 logging.CRITICAL: win32evtlog.EVENTLOG_ERROR_TYPE,
1164 }
1165 except ImportError:
1166 print("The Python Win32 extensions for NT (service, event "\
1167 "logging) appear not to be available.")
1168 self._welu = None
1169
1170 def getMessageID(self, record):
1171 """
1172 Return the message ID for the event record. If you are using your
1173 own messages, you could do this by having the msg passed to the
1174 logger being an ID rather than a formatting string. Then, in here,
1175 you could use a dictionary lookup to get the message ID. This
1176 version returns 1, which is the base message ID in win32service.pyd.
1177 """
1178 return 1
1179
1180 def getEventCategory(self, record):
1181 """
1182 Return the event category for the record.
1183
1184 Override this if you want to specify your own categories. This version
1185 returns 0.
1186 """
1187 return 0
1188
1189 def getEventType(self, record):
1190 """
1191 Return the event type for the record.
1192
1193 Override this if you want to specify your own types. This version does
1194 a mapping using the handler's typemap attribute, which is set up in
1195 __init__() to a dictionary which contains mappings for DEBUG, INFO,
1196 WARNING, ERROR and CRITICAL. If you are using your own levels you will
1197 either need to override this method or place a suitable dictionary in
1198 the handler's typemap attribute.
1199 """
1200 return self.typemap.get(record.levelno, self.deftype)
1201
1202 def emit(self, record):
1203 """
1204 Emit a record.
1205
1206 Determine the message ID, event category and event type. Then
1207 log the message in the NT event log.
1208 """
1209 if self._welu:
1210 try:
1211 id = self.getMessageID(record)
1212 cat = self.getEventCategory(record)
1213 type = self.getEventType(record)
1214 msg = self.format(record)
1215 self._welu.ReportEvent(self.appname, id, cat, type, [msg])
1216 except Exception:
1217 self.handleError(record)
1218
1219 def close(self):
1220 """
1221 Clean up this handler.
1222
1223 You can remove the application name from the registry as a
1224 source of event log entries. However, if you do this, you will
1225 not be able to see the events as you intended in the Event Log
1226 Viewer - it needs to be able to access the registry to get the
1227 DLL name.
1228 """
1229 #self._welu.RemoveSourceFromRegistry(self.appname, self.logtype)
1230 logging.Handler.close(self)
1231
1232 class HTTPHandler(logging.Handler):
1233 """
1234 A class which sends records to a web server, using either GET or
1235 POST semantics.
1236 """
1237 def __init__(self, host, url, method="GET", secure=False, credentials=None,
1238 context=None):
1239 """
1240 Initialize the instance with the host, the request URL, and the method
1241 ("GET" or "POST")
1242 """
1243 logging.Handler.__init__(self)
1244 method = method.upper()
1245 if method not in ["GET", "POST"]:
1246 raise ValueError("method must be GET or POST")
1247 if not secure and context is not None:
1248 raise ValueError("context parameter only makes sense "
1249 "with secure=True")
1250 self.host = host
1251 self.url = url
1252 self.method = method
1253 self.secure = secure
1254 self.credentials = credentials
1255 self.context = context
1256
1257 def mapLogRecord(self, record):
1258 """
1259 Default implementation of mapping the log record into a dict
1260 that is sent as the CGI data. Overwrite in your class.
1261 Contributed by Franz Glasner.
1262 """
1263 return record.__dict__
1264
1265 def getConnection(self, host, secure):
1266 """
1267 get a HTTP[S]Connection.
1268
1269 Override when a custom connection is required, for example if
1270 there is a proxy.
1271 """
1272 import http.client
1273 if secure:
1274 connection = http.client.HTTPSConnection(host, context=self.context)
1275 else:
1276 connection = http.client.HTTPConnection(host)
1277 return connection
1278
1279 def emit(self, record):
1280 """
1281 Emit a record.
1282
1283 Send the record to the web server as a percent-encoded dictionary
1284 """
1285 try:
1286 import urllib.parse
1287 host = self.host
1288 h = self.getConnection(host, self.secure)
1289 url = self.url
1290 data = urllib.parse.urlencode(self.mapLogRecord(record))
1291 if self.method == "GET":
1292 if (url.find('?') >= 0):
1293 sep = '&'
1294 else:
1295 sep = '?'
1296 url = url + "%c%s" % (sep, data)
1297 h.putrequest(self.method, url)
1298 # support multiple hosts on one IP address...
1299 # need to strip optional :port from host, if present
1300 i = host.find(":")
1301 if i >= 0:
1302 host = host[:i]
1303 # See issue #30904: putrequest call above already adds this header
1304 # on Python 3.x.
1305 # h.putheader("Host", host)
1306 if self.method == "POST":
1307 h.putheader("Content-type",
1308 "application/x-www-form-urlencoded")
1309 h.putheader("Content-length", str(len(data)))
1310 if self.credentials:
1311 import base64
1312 s = ('%s:%s' % self.credentials).encode('utf-8')
1313 s = 'Basic ' + base64.b64encode(s).strip().decode('ascii')
1314 h.putheader('Authorization', s)
1315 h.endheaders()
1316 if self.method == "POST":
1317 h.send(data.encode('utf-8'))
1318 h.getresponse() #can't do anything with the result
1319 except Exception:
1320 self.handleError(record)
1321
1322 class BufferingHandler(logging.Handler):
1323 """
1324 A handler class which buffers logging records in memory. Whenever each
1325 record is added to the buffer, a check is made to see if the buffer should
1326 be flushed. If it should, then flush() is expected to do what's needed.
1327 """
1328 def __init__(self, capacity):
1329 """
1330 Initialize the handler with the buffer size.
1331 """
1332 logging.Handler.__init__(self)
1333 self.capacity = capacity
1334 self.buffer = []
1335
1336 def shouldFlush(self, record):
1337 """
1338 Should the handler flush its buffer?
1339
1340 Returns true if the buffer is up to capacity. This method can be
1341 overridden to implement custom flushing strategies.
1342 """
1343 return (len(self.buffer) >= self.capacity)
1344
1345 def emit(self, record):
1346 """
1347 Emit a record.
1348
1349 Append the record. If shouldFlush() tells us to, call flush() to process
1350 the buffer.
1351 """
1352 self.buffer.append(record)
1353 if self.shouldFlush(record):
1354 self.flush()
1355
1356 def flush(self):
1357 """
1358 Override to implement custom flushing behaviour.
1359
1360 This version just zaps the buffer to empty.
1361 """
1362 with self.lock:
1363 self.buffer.clear()
1364
1365 def close(self):
1366 """
1367 Close the handler.
1368
1369 This version just flushes and chains to the parent class' close().
1370 """
1371 try:
1372 self.flush()
1373 finally:
1374 logging.Handler.close(self)
1375
1376 class MemoryHandler(BufferingHandler):
1377 """
1378 A handler class which buffers logging records in memory, periodically
1379 flushing them to a target handler. Flushing occurs whenever the buffer
1380 is full, or when an event of a certain severity or greater is seen.
1381 """
1382 def __init__(self, capacity, flushLevel=logging.ERROR, target=None,
1383 flushOnClose=True):
1384 """
1385 Initialize the handler with the buffer size, the level at which
1386 flushing should occur and an optional target.
1387
1388 Note that without a target being set either here or via setTarget(),
1389 a MemoryHandler is no use to anyone!
1390
1391 The ``flushOnClose`` argument is ``True`` for backward compatibility
1392 reasons - the old behaviour is that when the handler is closed, the
1393 buffer is flushed, even if the flush level hasn't been exceeded nor the
1394 capacity exceeded. To prevent this, set ``flushOnClose`` to ``False``.
1395 """
1396 BufferingHandler.__init__(self, capacity)
1397 self.flushLevel = flushLevel
1398 self.target = target
1399 # See Issue #26559 for why this has been added
1400 self.flushOnClose = flushOnClose
1401
1402 def shouldFlush(self, record):
1403 """
1404 Check for buffer full or a record at the flushLevel or higher.
1405 """
1406 return (len(self.buffer) >= self.capacity) or \
1407 (record.levelno >= self.flushLevel)
1408
1409 def setTarget(self, target):
1410 """
1411 Set the target handler for this handler.
1412 """
1413 with self.lock:
1414 self.target = target
1415
1416 def flush(self):
1417 """
1418 For a MemoryHandler, flushing means just sending the buffered
1419 records to the target, if there is one. Override if you want
1420 different behaviour.
1421
1422 The record buffer is only cleared if a target has been set.
1423 """
1424 with self.lock:
1425 if self.target:
1426 for record in self.buffer:
1427 self.target.handle(record)
1428 self.buffer.clear()
1429
1430 def close(self):
1431 """
1432 Flush, if appropriately configured, set the target to None and lose the
1433 buffer.
1434 """
1435 try:
1436 if self.flushOnClose:
1437 self.flush()
1438 finally:
1439 with self.lock:
1440 self.target = None
1441 BufferingHandler.close(self)
1442
1443
1444 class QueueHandler(logging.Handler):
1445 """
1446 This handler sends events to a queue. Typically, it would be used together
1447 with a multiprocessing Queue to centralise logging to file in one process
1448 (in a multi-process application), so as to avoid file write contention
1449 between processes.
1450
1451 This code is new in Python 3.2, but this class can be copy pasted into
1452 user code for use with earlier Python versions.
1453 """
1454
1455 def __init__(self, queue):
1456 """
1457 Initialise an instance, using the passed queue.
1458 """
1459 logging.Handler.__init__(self)
1460 self.queue = queue
1461 self.listener = None # will be set to listener if configured via dictConfig()
1462
1463 def enqueue(self, record):
1464 """
1465 Enqueue a record.
1466
1467 The base implementation uses put_nowait. You may want to override
1468 this method if you want to use blocking, timeouts or custom queue
1469 implementations.
1470 """
1471 self.queue.put_nowait(record)
1472
1473 def prepare(self, record):
1474 """
1475 Prepare a record for queuing. The object returned by this method is
1476 enqueued.
1477
1478 The base implementation formats the record to merge the message and
1479 arguments, and removes unpickleable items from the record in-place.
1480 Specifically, it overwrites the record's `msg` and
1481 `message` attributes with the merged message (obtained by
1482 calling the handler's `format` method), and sets the `args`,
1483 `exc_info` and `exc_text` attributes to None.
1484
1485 You might want to override this method if you want to convert
1486 the record to a dict or JSON string, or send a modified copy
1487 of the record while leaving the original intact.
1488 """
1489 # The format operation gets traceback text into record.exc_text
1490 # (if there's exception data), and also returns the formatted
1491 # message. We can then use this to replace the original
1492 # msg + args, as these might be unpickleable. We also zap the
1493 # exc_info, exc_text and stack_info attributes, as they are no longer
1494 # needed and, if not None, will typically not be pickleable.
1495 msg = self.format(record)
1496 # bpo-35726: make copy of record to avoid affecting other handlers in the chain.
1497 record = copy.copy(record)
1498 record.message = msg
1499 record.msg = msg
1500 record.args = None
1501 record.exc_info = None
1502 record.exc_text = None
1503 record.stack_info = None
1504 return record
1505
1506 def emit(self, record):
1507 """
1508 Emit a record.
1509
1510 Writes the LogRecord to the queue, preparing it for pickling first.
1511 """
1512 try:
1513 self.enqueue(self.prepare(record))
1514 except Exception:
1515 self.handleError(record)
1516
1517
1518 class QueueListener(object):
1519 """
1520 This class implements an internal threaded listener which watches for
1521 LogRecords being added to a queue, removes them and passes them to a
1522 list of handlers for processing.
1523 """
1524 _sentinel = None
1525
1526 def __init__(self, queue, *handlers, respect_handler_level=False):
1527 """
1528 Initialise an instance with the specified queue and
1529 handlers.
1530 """
1531 self.queue = queue
1532 self.handlers = handlers
1533 self._thread = None
1534 self.respect_handler_level = respect_handler_level
1535
1536 def dequeue(self, block):
1537 """
1538 Dequeue a record and return it, optionally blocking.
1539
1540 The base implementation uses get. You may want to override this method
1541 if you want to use timeouts or work with custom queue implementations.
1542 """
1543 return self.queue.get(block)
1544
1545 def start(self):
1546 """
1547 Start the listener.
1548
1549 This starts up a background thread to monitor the queue for
1550 LogRecords to process.
1551 """
1552 if self._thread is not None:
1553 raise RuntimeError("Listener already started")
1554
1555 self._thread = t = threading.Thread(target=self._monitor)
1556 t.daemon = True
1557 t.start()
1558
1559 def prepare(self, record):
1560 """
1561 Prepare a record for handling.
1562
1563 This method just returns the passed-in record. You may want to
1564 override this method if you need to do any custom marshalling or
1565 manipulation of the record before passing it to the handlers.
1566 """
1567 return record
1568
1569 def handle(self, record):
1570 """
1571 Handle a record.
1572
1573 This just loops through the handlers offering them the record
1574 to handle.
1575 """
1576 record = self.prepare(record)
1577 for handler in self.handlers:
1578 if not self.respect_handler_level:
1579 process = True
1580 else:
1581 process = record.levelno >= handler.level
1582 if process:
1583 handler.handle(record)
1584
1585 def _monitor(self):
1586 """
1587 Monitor the queue for records, and ask the handler
1588 to deal with them.
1589
1590 This method runs on a separate, internal thread.
1591 The thread will terminate if it sees a sentinel object in the queue.
1592 """
1593 q = self.queue
1594 has_task_done = hasattr(q, 'task_done')
1595 while True:
1596 try:
1597 record = self.dequeue(True)
1598 if record is self._sentinel:
1599 if has_task_done:
1600 q.task_done()
1601 break
1602 self.handle(record)
1603 if has_task_done:
1604 q.task_done()
1605 except queue.Empty:
1606 break
1607
1608 def enqueue_sentinel(self):
1609 """
1610 This is used to enqueue the sentinel record.
1611
1612 The base implementation uses put_nowait. You may want to override this
1613 method if you want to use timeouts or work with custom queue
1614 implementations.
1615 """
1616 self.queue.put_nowait(self._sentinel)
1617
1618 def stop(self):
1619 """
1620 Stop the listener.
1621
1622 This asks the thread to terminate, and then waits for it to do so.
1623 Note that if you don't call this before your application exits, there
1624 may be some records still left on the queue, which won't be processed.
1625 """
1626 if self._thread: # see gh-114706 - allow calling this more than once
1627 self.enqueue_sentinel()
1628 self._thread.join()
1629 self._thread = None