[docs] [issue18927] Lock.acquire() docs incorrect about negative timeout

[Tim Peters]

New submission from Tim Peters:

Here from the 3.3.2 docs for threading.Lock:

"""
acquire(blocking=True, timeout=-1) 
Acquire a lock, blocking or non-blocking.

...

When invoked with the floating-point timeout argument set to a positive value, block for at most the number of seconds specified by timeout and as long as the lock cannot be acquired. A negative timeout argument specifies an unbounded wait. 

...

"""

However, that's not what the code does for a negative timeout:

>>> from threading import Lock
>>> x = Lock()
>>> x.acquire(1, -0.2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: timeout value must be strictly positive

The only negative value the code allows is -1, in lock_PyThread_acquire_lock():

    if (timeout < 0 && timeout != -1) {
        PyErr_SetString(PyExc_ValueError, "timeout value must be "
                        "strictly positive");
        return NULL;
    }

The docs should change to say that -1 is special ;-)

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 196960
nosy: docs at python, tim.peters
priority: normal
severity: normal
status: open
title: Lock.acquire() docs incorrect about negative timeout
type: behavior
versions: Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue18927>
_______________________________________