classification
Title: Queue: document that zero is accepted as timeout value
Type: behavior Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.4, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: docs@python, python-dev, r.david.murray, sbt, terry.reedy, zyluo
Priority: normal Keywords: patch

Created on 2013-08-07 13:52 by zyluo, last changed 2013-08-10 23:03 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
queue_timeout_docstring.patch zyluo, 2013-08-08 01:22 queue module docstring patch for trunk review
queue_timeout_docstring.patch zyluo, 2013-08-08 01:45 queue module docstring patch for v2.7.5 review
queue_timeout_docstring.patch zyluo, 2013-08-08 01:48 queue module docstring patch for v3.3.2 review
Messages (7)
msg194611 - (view) Author: Zhongyue Luo (zyluo) Date: 2013-08-07 13:52
The docstring of methods put() and get() in Queue.py states

get(): If 'timeout' is a positive number, it blocks at most 'timeout' seconds and raises the Full exception if no free slot was available within that time.

put(): If 'timeout' is a positive number, it blocks at most 'timeout' seconds and raises the Empty exception if no item was available within that time.

Additionally the ValueError both methods raise is

 raise ValueError("'timeout' must be a positive number")

However the logic checks if 'timeout' is non-negative.

 elif timeout < 0:
     raise ValueError("'timeout' must be a positive number")

The logic should change as

 elif timeout <= 0:
     raise ValueError("'timeout' must be a positive number")
msg194613 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-08-07 14:11
This is more of a documentation issue than a code issue.  To be mathematically precise, the text and error message should read "a non-negative value".  Alternatively the text and error could be changed to report that timeout may not be negative, which would probably be clearer.  (Note that timeout is a float value, and thus the proposed code change would only break code, it would not change the functionality in any significant way.)
msg194626 - (view) Author: Zhongyue Luo (zyluo) Date: 2013-08-07 21:47
David,

How about like below?

  elif timeout < sys.float_info.epsilon:
     raise ValueError("'timeout' must be a positive number")

The docstring has been there for quite a while and IMHO it just doesn't make sense passing 0.0 as a timeout value.
msg194630 - (view) Author: Richard Oudkerk (sbt) * (Python committer) Date: 2013-08-07 22:13
> IMHO it just doesn't make sense passing 0.0 as a timeout value.

I have written lots of code that looks like

    timeout = max(deadline - time.time(), 0)
    some_function(..., timeout=timeout)

This makes perfect sense.  Working code should not be broken -- it is the docsting that should be changed.

I can't think of *any* function taking a timeout which rejects a zero timeout.  See select(), poll(), Condition.wait(), Lock.acquire(), Thread.join().  In each case a zero timeout causes a non-blocking call.

Also, note that the implementation does not contradict the docstring or documentation: they say nothing about what happens it timeout is zero (or negative).
msg194631 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-08-07 22:15
Exactly.  0 means "Don't wait, just raise an error immediately if the queue is empty/full".
msg194846 - (view) Author: Roundup Robot (python-dev) Date: 2013-08-10 22:40
New changeset 737b53ec5d1a by Terry Jan Reedy in branch '2.7':
Issue #18676: Change 'positive' to 'non-negative' in queue.py put and get
http://hg.python.org/cpython/rev/737b53ec5d1a

New changeset 2122d56d6bc5 by Terry Jan Reedy in branch '3.3':
Issue #18676: Change 'positive' to 'non-negative' in queue.py put and get
http://hg.python.org/cpython/rev/2122d56d6bc5

New changeset d9a9fe5e700d by Terry Jan Reedy in branch 'default':
Issue #18676: Merge from 3.3
http://hg.python.org/cpython/rev/d9a9fe5e700d
msg194847 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-08-10 23:03
Zhongyue, we merge 3.x patches forward (currently 3.3 to 3.4) so only one patch is usually needed unless the differences are non-trivial. It is easier if different version patches are tagged with the version in the filename.('-27', for instance.

If you think you will ever contribute another patch, especially one less trivial than this one, please go to
http://www.python.org/psf/contrib/ and
http://www.python.org/psf/contrib/contrib-form/
Note that the agreement can now be submitted electronically.
History
Date User Action Args
2013-08-10 23:03:53terry.reedysetstatus: open -> closed
resolution: fixed
messages: + msg194847

stage: commit review -> resolved
2013-08-10 22:40:28python-devsetnosy: + python-dev
messages: + msg194846
2013-08-10 21:57:23terry.reedysetassignee: docs@python -> terry.reedy

nosy: + terry.reedy
stage: commit review
2013-08-08 01:48:21zyluosetfiles: + queue_timeout_docstring.patch
2013-08-08 01:45:01zyluosetfiles: + queue_timeout_docstring.patch
2013-08-08 01:22:25zyluosetfiles: + queue_timeout_docstring.patch
keywords: + patch
2013-08-07 22:15:33r.david.murraysetmessages: + msg194631
2013-08-07 22:13:41sbtsetnosy: + sbt
messages: + msg194630
2013-08-07 21:47:28zyluosetmessages: + msg194626
2013-08-07 14:11:40r.david.murraysetassignee: docs@python

components: + Documentation
title: Queue: zero should not be accepted as timeout value -> Queue: document that zero is accepted as timeout value
nosy: + r.david.murray, docs@python
versions: + Python 3.3, Python 3.4
messages: + msg194613
2013-08-07 13:52:08zyluocreate