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.

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.

I think this commit should be reverted:  Arguments with default values no longer use brackets, see for example r73291.  More info on #8350.

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.

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.

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).

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.

I responded to the general questions on #8350.

Has the Argument Clinic had an impact on this or is that a different kettle of fish?

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.