classification
Title: Simplify threading.Lock.acquire() description
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, python-dev, r.david.murray, thread13
Priority: normal Keywords: patch

Created on 2012-05-16 00:49 by thread13, last changed 2012-05-19 02:21 by thread13. This issue is now closed.

Files
File name Uploaded Description Edit
threading.txt.patch thread13, 2012-05-16 00:49 suggested patch for the threading module documentation
Messages (7)
msg160786 - (view) Author: Q (thread13) Date: 2012-05-16 00:49
Hi there,

I suggest to improve the description of Lock.acquire()
[ http://docs.python.org/library/threading.html#threading.Lock.acquire ]
in the following way:

>>>>> current version >>>>>
Lock.acquire([blocking])

   Acquire a lock, blocking or non-blocking.

   When invoked without arguments, block until the lock is unlocked,
   then set it to locked, and return true.

   When invoked with the *blocking* argument set to true, do the same
   thing as when called without arguments, and return true.

   When invoked with the *blocking* argument set to false, do not
   block.  If a call without an argument would block, return false
   immediately; otherwise, do the same thing as when called without
   arguments, and return true.

<<<<< current version <<<<<


>>>>> suggested version >>>>>
Lock.acquire([blocking])

   Acquire a lock, blocking or non-blocking.

   When invoked with the *blocking* argument set to true 
   (the default), block until the lock is unlocked, 
   then set it to locked, and return true.

   When invoked with the *blocking* argument set to false, do not
   block.  If a call without an argument would block, return false
   immediately; otherwise, set the lock to locked, and return true.

<<<<< suggested version <<<<<

The idea is to simplify the structure of the explanation: get rid of an unnecessary "goto" -- "do the same thing as" as well as the extra branching ("when invoked without arguments" ... "when invoked with *blocking* argument set to true") .

The suggested patch for the text version of the documentation ( http://docs.python.org/download.html -> http://docs.python.org/archives/python-2.7.3-docs-text.tar.bz2 ) is attached. 

PS. I did not dare to capitalize the boolean variables ("true" -> "True") to adhere to the general style of the document (obviously inherited from Java). For the same reason I didn't either change the argument signature from "[blocking]" to "[blocking=True]".
msg160788 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-05-16 01:02
Thanks for the suggestion and the patch.

The 'true' isn't inherited from java.  The actual value can be either an integer or True/False.  (If it were a function written in Python it would be any value that evaluates as true, but because it is written in C it is actually restricted to an integer...this is a bit of a wart, actually).

In the Python3 docs it is indeed documented as 'blocking=True'.  The Python2 docs use an older signature style that we didn't bother to fix up.
msg160949 - (view) Author: Q (thread13) Date: 2012-05-17 03:31
Well, as threading is a Python wrapper, this could easily be fixed. (I am not certain whether it *should* be fixed or not -- perhaps things are fine just as they are, at least with that particular detail. ) 

But this is good to know, thank you.
msg160968 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-05-17 13:15
New changeset 6ab4128acccc by R David Murray in branch '3.2':
#14823: Simplify threading.Lock.acquire argument discussion.
http://hg.python.org/cpython/rev/6ab4128acccc

New changeset b5e95bb79ba3 by R David Murray in branch 'default':
#14823: Simplify threading.Lock.acquire argument discussion.
http://hg.python.org/cpython/rev/b5e95bb79ba3

New changeset 251463919f3c by R David Murray in branch '2.7':
#14823: Simplify threading.Lock.acquire argument discussion.
http://hg.python.org/cpython/rev/251463919f3c
msg160969 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-05-17 13:18
Instead I decided to go ahead and document the argument as True/False.  That something else is accepted is a CPython implementation detail that shouldn't be depended on.

By the way, I couldn't actually use your patch file, since it wasn't against the threading.rst file from the repository.
msg160973 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-05-17 15:23
I suspect the patch was made against the source files served by Sphinx with a txt extension.
msg161089 - (view) Author: Q (thread13) Date: 2012-05-19 02:21
My bad. That's indeed what I did. Won't repeat the mistake, sorry.
History
Date User Action Args
2012-05-19 02:21:54thread13setmessages: + msg161089
2012-05-17 15:23:19eric.araujosetnosy: + eric.araujo
messages: + msg160973
2012-05-17 13:18:26r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg160969

stage: commit review -> resolved
2012-05-17 13:15:17python-devsetnosy: + python-dev
messages: + msg160968
2012-05-17 03:31:19thread13setmessages: + msg160949
2012-05-16 01:02:46r.david.murraysetversions: + Python 3.2, Python 3.3, - Python 2.6
nosy: + r.david.murray

messages: + msg160788

type: behavior
stage: commit review
2012-05-16 00:49:16thread13create