classification
Title: Various out-of-date Lock text in 3.2+
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, cjwelborn, docs@python, python-dev, r.david.murray, tim.peters
Priority: low Keywords: easy, patch

Created on 2013-09-04 00:39 by tim.peters, last changed 2016-05-02 09:26 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
threading.lock.docs.3.3-with-comment.patch cjwelborn, 2014-01-31 19:51 Doc string fixes for threading.Lock (3.3 no argument clinic) review
Messages (10)
msg196881 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2013-09-04 00:39
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 ;-)
msg196883 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-09-04 01:46
Thanks.  I suspect someone will indeed latch on to this soon enough.

We use the 'versions' to track what version we are going to fix the bug in.  So I've removed 3.2, since that only gets security fixes, and 3.5, since that doesn't exist yet.  (If we don't fix this for 3.4, we will change the versions next time we visit the issue.)
msg209740 - (view) Author: Christopher Welborn (cjwelborn) * Date: 2014-01-30 22:02
Hello, my name is Chris Welborn (or Cj). I've been looking for opportunities to work on python. I figured a little Doc fix would be perfect for my first patch, as you originally planned. I ran the python unit-tests and `make test`, plus a 'patchcheck'. Even though I really only changed a couple strings, I wanted to be sure. I hope this patch is acceptable, but if it's not I would be glad to tidy it up in whatever way you see fit.

Thanks for leaving this for someone like me :)

-Cj
msg209743 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-01-31 01:18
Thanks for working on this.  The patch looks pretty good.  I would prefer to flow the two lines in the Lock docstring as a paragraph, rather than have once sentence per line.  Also, the OP mentions that the docs for type(Lock) mention PyThread_allocate_lock...do you want to look at fixing that as well?  As mentioned, it should reference Lock() instead.  The reference to PyThread_allocate_lock should be moved into comments in the type, IMO.

Also, this patch may be affected by the Argument Clinic Derby.  I don't know if the threading module is one of the ones that is being converted or not.  You can just ignore that issue since the full patch is needed for 3.3, but if you feel like figuring it out, and it is affected, you could produce an additional patch for 3.4.  Otherwise whoever applies your patch will figure out how to merge it.
msg209745 - (view) Author: Christopher Welborn (cjwelborn) * Date: 2014-01-31 03:03
Yep, I missed the PyThread_allocate_lock reference. As far as the Argument Clinic Derby, I've been following the python-dev list and reading about Argument Clinic, but I don't know enough about it to do the conversion. It's a really good tool from what I can tell. I'll have to study it some more so in the future I can possibly help with the conversions.

I see the threading module listed in <a href="http://bugs.python.org/issue20185">Issue #20185</a> (Derby #17), but no patch for it yet.

Forgive my newbness, but I omitted putting a reference to PyThread_allocate_lock in the comments because I was confused about what kind of reference you were talking about. Something about making sure Python users see "threading.Lock" instead of "PyThread_allocate_lock", or moving a statement like "to create a lock in C, call the PyThread_allocate_lock function" into the comments. If it's important for it to be there, could you let me know so I can make the edit?

Hopefully I have been of some help, instead of just wasting your time.
msg209746 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-01-31 03:50
Yes, the latter: since someone thought it was important to mention, but only people working with the C code would benefit, it ought to be a comment in the C source.

If there's no AC patch for threading yet, then there's no problem with that, and your patch will be good for both 3.3 and 3.4.
msg209823 - (view) Author: Christopher Welborn (cjwelborn) * Date: 2014-01-31 19:51
Here's the 3.3 version, with the PyThread_allocate_lock comment in the lock type.
Still working on the 3.4 argument clinic version.
msg209828 - (view) Author: Christopher Welborn (cjwelborn) * Date: 2014-01-31 20:54
I meant to say 'attempting to work on the 3.4 arg clinic version', i can't make any promises. I'm using it as a learning experience but probably won't yield any real results any time soon.
msg264633 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-05-02 09:26
New changeset 203c9c4ccb2a by Berker Peksag in branch '3.5':
Issue #18916: Update thread module docstrings
https://hg.python.org/cpython/rev/203c9c4ccb2a

New changeset 57a475e0e378 by Berker Peksag in branch 'default':
Issue #18916: Update thread module docstrings
https://hg.python.org/cpython/rev/57a475e0e378
msg264634 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-05-02 09:26
Thanks for the path, Christopher.
History
Date User Action Args
2016-05-02 09:26:51berker.peksagsetstatus: open -> closed

assignee: docs@python
components: + Documentation, - Interpreter Core
versions: + Python 3.5, Python 3.6, - Python 3.3, Python 3.4
nosy: + berker.peksag, docs@python

messages: + msg264634
resolution: fixed
stage: needs patch -> resolved
2016-05-02 09:26:00python-devsetnosy: + python-dev
messages: + msg264633
2014-01-31 20:54:08cjwelbornsetmessages: + msg209828
2014-01-31 19:51:15cjwelbornsetfiles: - threading.lock.docs3.3.patch
2014-01-31 19:51:05cjwelbornsetfiles: + threading.lock.docs.3.3-with-comment.patch

messages: + msg209823
2014-01-31 03:50:44r.david.murraysetmessages: + msg209746
2014-01-31 03:23:00cjwelbornsetfiles: - threading.lock.docs.patch
2014-01-31 03:03:02cjwelbornsetfiles: + threading.lock.docs3.3.patch

messages: + msg209745
2014-01-31 01:18:03r.david.murraysetmessages: + msg209743
2014-01-30 22:02:06cjwelbornsetfiles: + threading.lock.docs.patch

nosy: + cjwelborn
messages: + msg209740

keywords: + patch
2013-09-04 01:46:40r.david.murraysetnosy: + r.david.murray

messages: + msg196883
versions: - Python 3.2, Python 3.5
2013-09-04 00:39:05tim.peterscreate