[issue10789] Lock.acquire documentation is misleading
New submission from Jyrki Pulliainen jyrki@dywypi.org:
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.
---------- assignee: docs@python components: Documentation messages: 124861 nosy: Jyrki.Pulliainen, docs@python priority: normal severity: normal status: open title: Lock.acquire documentation is misleading versions: Python 2.7, Python 3.1
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
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.
---------- assignee: docs@python -> terry.reedy nosy: +terry.reedy resolution: -> fixed stage: -> committed/rejected status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
I think this commit should be reverted: Arguments with default values no longer use brackets, see for example r73291. More info on #8350.
---------- nosy: +eric.araujo, georg.brandl
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Georg Brandl georg@python.org added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
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.
---------- resolution: fixed -> stage: committed/rejected -> needs patch status: closed -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
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).
---------- dependencies: +Document lack of support for keyword arguments in C functions
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Raymond Hettinger rhettinger@users.sourceforge.net added the comment:
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.
---------- nosy: +rhettinger
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
I responded to the general questions on #8350.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Mark Lawrence added the comment:
Has the Argument Clinic had an impact on this or is that a different kettle of fish?
---------- nosy: +BreamoreBoy versions: +Python 3.4, Python 3.5 -Python 3.1
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10789 _______________________________________
Change by Mark Lawrence breamoreboy@gmail.com:
---------- nosy: -BreamoreBoy
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue10789 _______________________________________
participants (6)
-
Georg Brandl -
Jyrki Pulliainen
-
Mark Lawrence
-
Raymond Hettinger
-
Terry J. Reedy
-
Éric Araujo