[issue10789] Lock.acquire documentation is misleading

[Alex Waygood]

Alex Waygood  added the comment:

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.

--
dependencies:  -Document lack of support for keyword arguments in C functions
nosy: +AlexWaygood
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed
type:  -> behavior

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Mark Lawrence]

Change by Mark Lawrence :


--
nosy:  -BreamoreBoy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Mark Lawrence]

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 rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Georg Brandl]

Georg Brandl ge...@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 rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Terry J. Reedy]

Terry J. Reedy tjre...@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 rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Éric Araujo]

Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Raymond Hettinger]

Raymond Hettinger rhettin...@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 rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Terry J. Reedy]

Terry J. Reedy tjre...@udel.edu added the comment:

I responded to the general questions on #8350.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Terry J. Reedy]

Terry J. Reedy tjre...@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: d...@python - terry.reedy
nosy: +terry.reedy
resolution:  - fixed
stage:  - committed/rejected
status: open - closed

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10789] Lock.acquire documentation is misleading

[Jyrki Pulliainen]

New submission from Jyrki Pulliainen jy...@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: d...@python
components: Documentation
messages: 124861
nosy: Jyrki.Pulliainen, d...@python
priority: normal
severity: normal
status: open
title: Lock.acquire documentation is misleading
versions: Python 2.7, Python 3.1

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10789
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com