[New-bugs-announce] [issue18916] Various out-of-date Lock text in 3.2+

[Tim Peters]

New submission from Tim Peters:

Here under 3.3.2:

"""
>>> from threading import Lock
>>> help(Lock)
Help on built-in function allocate_lock in module _thread:

allocate_lock(...)
    allocate_lock() -> lock object
    (allocate() is an obsolete synonym)
    
    Create a new lock object.  See help(LockType) for information about locks.
"""

But there is no relevant LockType anymore.  The type is now:

"""
>>> type(Lock())
<class '_thread.lock'>
"""

The docs should probably say "help(type(Lock())" instead of "help(LockType)" now.  So let's try that:

"""
>>> help(type(Lock()))
Help on class lock in module _thread:

class lock(builtins.object)
 |  A lock object is a synchronization primitive.  To create a lock,
 |  call the PyThread_allocate_lock() function.
"""

That's a problem:  PyThread_allocate_lock() is a C function, not available (under that name) to Python code.  A Python user should probably stick to threading.Lock().

Skipping most other output:

"""
...
 |  acquire(...)
 |      acquire([wait]) -> bool
 |      (acquire_lock() is an obsolete synonym)
 |      
 |      Lock the lock.  Without argument, this blocks if the lock is already
 |      locked (even by the same thread), waiting for another thread to release
 |      the lock, and return True once the lock is acquired.
 |      With an argument, this will only block if the argument is true,
 |      and the return value reflects whether the lock is acquired.
 |      The blocking operation is interruptible.
...
"""

That's not the right signature for acquire anymore.  Should be

acquire(blocking=True, timeout=-1) 

which is what the threading module docs say.  That is, the docs are up-to-date, but the help strings in the code aren't.  Since 3.2 is the first version introducing the timeout option, that's the earliest version I selected on this report.

I'm going to leave this for someone who wants an easy patch exercise - you're welcome ;-)

----------
components: Interpreter Core
keywords: easy
messages: 196881
nosy: tim.peters
priority: low
severity: normal
stage: needs patch
status: open
title: Various out-of-date Lock text in 3.2+
type: behavior
versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5

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