diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index 7230224b4fc532..b75d61b62daee9 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -874,7 +874,7 @@ The :class:`SMTPHandler` class, located in the :mod:`!logging.handlers` module, supports sending logging messages to an email address via SMTP. -.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0) +.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=5.0) Returns a new instance of the :class:`SMTPHandler` class. The instance is initialized with the from and to addresses and subject line of the email. The @@ -1090,16 +1090,18 @@ possible, while any potentially slow operations (such as sending an email via method is enqueued. The base implementation formats the record to merge the message, - arguments, exception and stack information, if present. It also removes - unpickleable items from the record in-place. Specifically, it overwrites - the record's :attr:`msg` and :attr:`message` attributes with the merged + arguments, exception and stack information, if present. It also removes + unpickleable items from a copy of the record. Specifically, it overwrites + the copy's :attr:`msg` and :attr:`message` attributes with the merged message (obtained by calling the handler's :meth:`format` method), and - sets the :attr:`args`, :attr:`exc_info` and :attr:`exc_text` attributes - to ``None``. + sets the :attr:`args`, :attr:`exc_info`, :attr:`exc_text` and + :attr:`stack_info` attributes to ``None``. + + These changes are made on the copy, so they do not affect the original + record. You might want to override this method if you want to convert - the record to a dict or JSON string, or send a modified copy - of the record while leaving the original intact. + the record to a dict or JSON string. .. note:: The base implementation formats the message with arguments, sets the ``message`` and ``msg`` attributes to the formatted message and diff --git a/Lib/logging/__init__.py b/Lib/logging/__init__.py index 549a6b3c457b2c..607fb7c0b938e5 100644 --- a/Lib/logging/__init__.py +++ b/Lib/logging/__init__.py @@ -1146,9 +1146,7 @@ def emit(self, record): If a formatter is specified, it is used to format the record. The record is then written to the stream with a trailing newline. If exception information is present, it is formatted using - traceback.print_exception and appended to the stream. If the stream - has an 'encoding' attribute, it is used to determine how to do the - output to the stream. + traceback.print_exception and appended to the stream. """ try: msg = self.format(record) @@ -1747,9 +1745,11 @@ def callHandlers(self, record): Pass a record to all relevant handlers. Loop through all handlers for this logger and its parents in the - logger hierarchy. If no handler was found, output a one-off error - message to sys.stderr. Stop searching up the hierarchy whenever a - logger with the "propagate" attribute set to zero is found - that + logger hierarchy. If no handler was found, the record is passed to + lastResort, if set and if the record's level is appropriate. If + lastResort is not set and raiseExceptions is true, output a one-off + error message to sys.stderr. Stop searching up the hierarchy whenever + a logger with the "propagate" attribute set to zero is found - that will be the last logger whose handlers are called. """ c = self @@ -2055,7 +2055,7 @@ def basicConfig(**kwargs): level Set the root logger level to the specified level. stream Use the specified stream to initialize the StreamHandler. Note that this argument is incompatible with 'filename' - if both - are present, 'stream' is ignored. + are present, a ValueError is raised. handlers If specified, this should be an iterable of already created handlers, which will be added to the root logger. Any handler in the list which does not have a formatter assigned will be @@ -2093,9 +2093,8 @@ def basicConfig(**kwargs): .. versionchanged:: 3.3 Added the ``handlers`` parameter. A ``ValueError`` is now thrown for incompatible arguments (e.g. ``handlers`` specified together with - ``filename``/``filemode``, or ``filename``/``filemode`` specified - together with ``stream``, or ``handlers`` specified together with - ``stream``. + ``filename`` or ``stream``, or ``stream`` specified together with + ``filename``). .. versionchanged:: 3.8 Added the ``force`` parameter. diff --git a/Lib/logging/handlers.py b/Lib/logging/handlers.py index e225a21da408fa..2f88727dd5efd9 100644 --- a/Lib/logging/handlers.py +++ b/Lib/logging/handlers.py @@ -1026,8 +1026,7 @@ def emit(self, record): """ Emit a record. - The record is formatted, and then sent to the syslog server. If - exception information is present, it is NOT sent to the server. + The record is formatted, and then sent to the syslog server. """ try: msg = self.format(record) @@ -1083,7 +1082,7 @@ def __init__(self, mailhost, fromaddr, toaddrs, subject, certificate file. (This tuple is passed to the `ssl.SSLContext.load_cert_chain` method). A timeout in seconds can be specified for the SMTP connection (the - default is one second). + default is five seconds). """ logging.Handler.__init__(self) if isinstance(mailhost, (list, tuple)): @@ -1525,15 +1524,17 @@ def prepare(self, record): enqueued. The base implementation formats the record to merge the message and - arguments, and removes unpickleable items from the record in-place. - Specifically, it overwrites the record's `msg` and + arguments, and removes unpickleable items from a copy of the record. + Specifically, it overwrites the copy's `msg` and `message` attributes with the merged message (obtained by calling the handler's `format` method), and sets the `args`, - `exc_info` and `exc_text` attributes to None. + `exc_info`, `exc_text` and `stack_info` attributes to None. + + These changes are made on the copy, so they do not affect the original + record. You might want to override this method if you want to convert - the record to a dict or JSON string, or send a modified copy - of the record while leaving the original intact. + the record to a dict or JSON string. """ # The format operation gets traceback text into record.exc_text # (if there's exception data), and also returns the formatted