Fix inaccurate wording in multiple logging module docstrings

[lpyu001]

Summary

Fix seven inaccurate or outdated docstrings in the logging package. Items 1 and 3 are also wrong in Doc/library/logging.handlers.rst, which is updated as well.

1. SMTPHandler default timeout is 5 seconds

Correct the documented default timeout from one second to five seconds.

from logging.handlers import SMTPHandler

h = SMTPHandler("localhost", "from@example.com", "to@example.com", "subject")
print(h.timeout)
# 5.0

2. SysLogHandler.emit() sends exception information

Remove the statement that exception information is not sent to the server. emit() sends the output of self.format(record), which includes the formatted traceback when exc_info is set.

import logging, logging.handlers, socket, sys

srv = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
srv.bind(("127.0.0.1", 0))
h = logging.handlers.SysLogHandler(address=srv.getsockname())
try:
    1 / 0
except ZeroDivisionError:
    h.emit(logging.makeLogRecord({"msg": "boom", "exc_info": sys.exc_info()}))
print(b"ZeroDivisionError" in srv.recv(65536))
# True

3. QueueHandler.prepare() modifies a copy of the record

Clarify that prepare() returns a modified copy and leaves the original record's msg, args, exc_info and stack_info intact. The record has been copied before modification since bpo-35726, but the docstring and logging.handlers.rst still say it is modified in-place. Also mention that stack_info is set to None.

import logging, queue
from logging.handlers import QueueHandler

record = logging.makeLogRecord({"msg": "x=%s", "args": (1,)})
prepared = QueueHandler(queue.Queue()).prepare(record)
print(prepared is record, record.msg, record.args)
print(prepared.msg, prepared.args)
# False x=%s (1,)
# x=1 None

4. basicConfig() rejects stream together with filename

Correct the description of stream: passing it together with filename raises ValueError instead of ignoring stream. This matches logging.rst and the versionchanged:: 3.3 note in the same docstring.

import io, logging

logging.basicConfig(stream=io.StringIO(), filename="app.log")
# ValueError: 'stream' and 'filename' should not be specified together

5. basicConfig() accepts filemode together with stream

Correct the versionchanged:: 3.3 note to list the combinations that actually raise ValueError, as logging.rst does. filemode together with stream does not raise; filemode is ignored.

import io, logging

logging.basicConfig(stream=io.StringIO(), filemode="w")
print(logging.root.handlers)
# [<StreamHandler (NOTSET)>]

6. StreamHandler.emit() does not use the stream's encoding

Remove the statement that the stream's encoding attribute is used to determine how the output is written. emit() writes the formatted string to the stream without consulting encoding.

import logging

class Stream:
    encoding = "ascii"
    def write(self, s):
        print(repr(s))
    def flush(self):
        pass

logging.StreamHandler(Stream()).emit(logging.makeLogRecord({"msg": "café"}))
# 'café\n'

7. Logger.callHandlers() falls back to lastResort

Describe the handler of last resort. When no handler is found, the record is passed to logging.lastResort if it is set; the one-off "No handlers could be found" message is only written when lastResort is None.

import logging

logging.getLogger("demo").warning("hello")
logging.lastResort = None
logging.getLogger("demo").warning("hello")
# hello
# No handlers could be found for logger "demo"

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34773910 | 📁 Comparing c6e3e48 against main (8122ff4)

  🔍 Preview build  

1 file changed

± library/logging.handlers.html