classification
Title: Lock.acquire documentation is misleading
Type: Stage: needs patch
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: 8350 Superseder:
Assigned To: terry.reedy Nosy List: docs@python, eric.araujo, georg.brandl, nailor, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2010-12-29 17:41 by nailor, last changed 2019-04-26 20:39 by BreamoreBoy.

Messages (9)
msg124861 - (view) Author: Jyrki Pulliainen (nailor) * Date: 2010-12-29 17:41
In threading module, the Lock.acquire documentation is misleading. The signature suggests that the blocking can be given as a keyword argument but that would lead to an TypeError, as thread.lock.acquire does not accept keyword arguments.

The signature in documentation should be formatted as in thread.lock.acquire.
msg124983 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-01-01 00:37
Since threading is written in Python, one might expect Lock to be written in Python and its methods to accept keywords. However, threading.py (3.2) has
  _acquire_lock = _thread.acquire_lock
  Lock = _aquire_lock
so threading.Lock objects are C-coded _thread.lock objects and hence *might* not accept keyword args.

In 3.1:
lock.acquire([waitflag]) # same 2.7
Lock.acquire(blocking=True) # [blocking=1] in 2.7
Indeed the first is correct.

>>> from threading import Lock
>>> l=Lock()
>>> l.acquire(blocking=True)
Traceback (most recent call last):
  File "<pyshell#2>", line 1, in <module>
    l.acquire(blocking=True)
TypeError: acquire() takes no keyword arguments
>>> l.acquire(True)
True

r87596, r87596

In 3.2:
lock.acquire(waitflag=1, timeout=-1) 
Lock.acquire(blocking=True, timeout=-1)
The edit in 3.2 is actually correct 

>>> from threading import Lock
>>> l=Lock()
>>> l.acquire(blocking=True)
True
>>> l.acquire(timeout=1)
False

_thread.lock.acquire now accepts keywords.
msg125004 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-01-01 18:01
I think this commit should be reverted:  Arguments with default values no longer use brackets, see for example r73291.  More info on #8350.
msg125005 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-01-01 18:21
No, that's not true.  Arguments that can't be given as kwargs are presented with brackets.

However, the default value now isn't indicated anywhere; it should be added to the main text.
msg125008 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-01-01 21:31
OK, I will add defaults in the texts and condense them a bit at the same time. Will post patches for review.

"Arguments that can't be given as kwargs are presented with brackets."
I think this should be stated in the introduction to the Lib manual, along with any other conventions a reader should know. If you agree, one of us can open an issue for this.
msg125022 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-01-02 00:51
Thanks for the correction Georg.

In msg104113 (on #8350), I quoted http://docs.python.org/dev/reference/expressions#calls :

“An implementation may provide built-in functions whose positional parameters do not have names, even if they are ‘named’ for the purpose of documentation, and which therefore cannot be supplied by keyword.”

Previous consensus seemed to be that this warning was enough, but recent bugs such as this one show that it does trip up users, so there is further discussion about how best to document this CPython limitation (hence the dependency I’m adding).
msg125023 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-01-02 01:16
I concur that the one warning is enough.  Implementations have been given wide latitude in this regard.  Even within CPython there is not much uniformity -- some funcs/methods don't accept keywords, some will disregard keywords, and others may have keywords that are different from the name in the docs.  

I believe it would be a mistake to make to lock in the present state of accidental implementation details by documenting them in the main docs.
msg125027 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-01-02 02:23
I responded to the general questions on #8350.
msg227855 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-09-29 22:58
Has the Argument Clinic had an impact on this or is that a different kettle of fish?
History
Date User Action Args
2019-04-26 20:39:38BreamoreBoysetnosy: - BreamoreBoy
2014-09-29 22:58:16BreamoreBoysetnosy: + BreamoreBoy

messages: + msg227855
versions: + Python 3.4, Python 3.5, - Python 3.1
2011-01-02 02:23:35terry.reedysetnosy: georg.brandl, rhettinger, terry.reedy, eric.araujo, docs@python, nailor
messages: + msg125027
2011-01-02 01:16:47rhettingersetnosy: + rhettinger
messages: + msg125023
2011-01-02 00:51:16eric.araujosetnosy: georg.brandl, terry.reedy, eric.araujo, docs@python, nailor
dependencies: + Document lack of support for keyword arguments in C functions
messages: + msg125022
2011-01-01 21:31:36terry.reedysetstatus: closed -> open
nosy: georg.brandl, terry.reedy, eric.araujo, docs@python, nailor
messages: + msg125008

resolution: fixed ->
stage: resolved -> needs patch
2011-01-01 18:21:46georg.brandlsetnosy: georg.brandl, terry.reedy, eric.araujo, docs@python, nailor
messages: + msg125005
2011-01-01 18:01:42eric.araujosetnosy: + eric.araujo, georg.brandl
messages: + msg125004
2011-01-01 00:37:39terry.reedysetstatus: open -> closed

assignee: docs@python -> terry.reedy

nosy: + terry.reedy
messages: + msg124983
resolution: fixed
stage: resolved
2010-12-29 17:41:13nailorcreate