[docs] [issue27624] unclear documentation on Queue.qsize()
report at bugs.python.org
Wed Jul 27 11:12:26 EDT 2016
STINNER Victor added the comment:
Return the number of items in the queue. Note, in multi-threading this mostly just serves as an approximation, and information from this doesn’t guarantee that a subsequent get() or put() will not block.
I dislike this description. If I understand correctly, the issue is that someone must not rely on the size to check if the queue is empty or not. If I'm right, the doc must be more explicit. Something like:
"The size must not be used to check if get() or put() will block. Use get_nowait() and put_nowait(), or get() and put() in non-blocking mode (block=False)."
There is even a Wikipedia article on the bug :-)
(I'm not sure that it's exactly the same class of bug.)
Python tracker <report at bugs.python.org>
More information about the docs