Repository navigation
Lock.acquire documentation is misleading #54998
Description
| BPO | 10789 |
|---|---|
| Nosy | @birkenfeld, @rhettinger, @terryjreedy, @merwok, @AlexWaygood |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2021-12-19.15:58:11.920>
created_at = <Date 2010-12-29.17:41:13.256>
labels = ['type-bug', 'docs']
title = 'Lock.acquire documentation is misleading'
updated_at = <Date 2021-12-19.15:58:11.918>
user = 'https://bugs.python.org/nailor'bugs.python.org fields:
activity = <Date 2021-12-19.15:58:11.918>
actor = 'AlexWaygood'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2021-12-19.15:58:11.920>
closer = 'AlexWaygood'
components = ['Documentation']
creation = <Date 2010-12-29.17:41:13.256>
creator = 'nailor'
dependencies = []
files = []
hgrepos = []
issue_num = 10789
keywords = []
message_count = 10.0
messages = ['124861', '124983', '125004', '125005', '125008', '125022', '125023', '125027', '227855', '408908']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'rhettinger', 'terry.reedy', 'eric.araujo', 'docs@python', 'nailor', 'AlexWaygood']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue10789'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']
Activity
nailor commentedon Dec 29, 2010
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.
terryjreedy commentedon Jan 1, 2011
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.
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
_thread.lock.acquire now accepts keywords.
merwok commentedon Jan 1, 2011
I think this commit should be reverted: Arguments with default values no longer use brackets, see for example r73291. More info on bpo-8350.
birkenfeld commentedon Jan 1, 2011
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.
terryjreedy commentedon Jan 1, 2011
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.
merwok commentedon Jan 2, 2011
Thanks for the correction Georg.
In msg104113 (on bpo-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).
rhettinger commentedon Jan 2, 2011
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.
terryjreedy commentedon Jan 2, 2011
I responded to the general questions on bpo-8350.
BreamoreBoy commentedon Sep 29, 2014
Has the Argument Clinic had an impact on this or is that a different kettle of fish?
AlexWaygood commentedon Dec 19, 2021
I am closing this issue. The original topic of discussion (Lock.acquire documentation) has been resolved, and there were other issues opened to discuss the more general issue. There has also been no real activity in this issue thread for a decade.