logging.handlers.QueueHandler acts unexpected

[kaijmueller]

BPO	44473
Nosy	@vsajip, @miss-islington, @jdevries3133
PRs	bpo-44473: Update docstring and documentation for QueueHandler.prepar… #27140

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2021-07-28.10:46:03.613>
created_at = <Date 2021-06-21.13:04:38.286>
labels = ['3.7', '3.8', '3.9', '3.10', '3.11', 'type-feature', 'docs']
title = 'logging.handlers.QueueHandler acts unexpected'
updated_at = <Date 2021-07-28.10:46:03.613>
user = 'https://bugs.python.org/kaijmueller'

bugs.python.org fields:

activity = <Date 2021-07-28.10:46:03.613>
actor = 'vinay.sajip'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-07-28.10:46:03.613>
closer = 'vinay.sajip'
components = ['Documentation']
creation = <Date 2021-06-21.13:04:38.286>
creator = 'kai.jmueller'
dependencies = []
files = []
hgrepos = []
issue_num = 44473
keywords = ['patch']
message_count = 4.0
messages = ['396243', '397504', '397518', '397540']
nosy_count = 5.0
nosy_names = ['vinay.sajip', 'docs@python', 'miss-islington', 'jack__d', 'kai.jmueller']
pr_nums = ['27140']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue44473'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9', 'Python 3.10', 'Python 3.11']

[kaijmueller]

According to the docstring of logging.handlers.QueueHandler
"The base implementation formats the record to merge the message and arguments, and removes unpickleable items from the record in-place."
But, if a just a log message is used w/o any arguments, the arguments are still set to None, which IMHO unexpected. Especially, according to the typeshed project, the "args" is ALWAYS either a dict or a tuple. But in this case, they are set to None which surprised my a lot.

Would it be possible to improve the docstring to state, that args, exc_info, exc_text are set to None and that msg is overwritten. If you miss this tiny but very important detail, additional handlers can act very wrong.
In addition, it seems to be that the type information needs to be improved in typeshed or are there any other plans on your side?

[jdevries3133]

I have another question about the docstring in the source beneath logging.handlers.QueueHandler.prepare. It says:

The object returned by this method is enqueued.

But, the prepare method doesn't do the enqueuing operation, it just prepares the record and returns it back, so it seems like this statement is not accurate?

[miss-islington]

New changeset 3b8075f by Vinay Sajip in branch 'main':
bpo-44473: Update docstring and documentation for QueueHandler.prepar… (GH-27140)
3b8075f

[vsajip]

But, the prepare method doesn't do the enqueuing operation, it just prepares the record and returns it back, so it seems like this statement is not accurate?

It merely states what happens to the return value. It doesn't say it has already been enqueued. If you look at the entire documentation for the class (rather than just individual sentences) I don't think the way the class works is unclear.