[issue18916] Various out-of-date Lock text in 3.2+

[Berker Peksag]

Berker Peksag added the comment:

Thanks for the path, Christopher.

--
assignee:  -> docs@python
components: +Documentation -Interpreter Core
nosy: +berker.peksag, docs@python
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed
versions: +Python 3.5, Python 3.6 -Python 3.3, Python 3.4

___
Python tracker 

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

[issue18916] Various out-of-date Lock text in 3.2+

[Roundup Robot]

Roundup Robot added the comment:

New changeset 203c9c4ccb2a by Berker Peksag in branch '3.5':
Issue #18916: Update thread module docstrings
https://hg.python.org/cpython/rev/203c9c4ccb2a

New changeset 57a475e0e378 by Berker Peksag in branch 'default':
Issue #18916: Update thread module docstrings
https://hg.python.org/cpython/rev/57a475e0e378

--
nosy: +python-dev

___
Python tracker 

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

[issue18916] Various out-of-date Lock text in 3.2+

[Christopher Welborn]

Christopher Welborn added the comment:

Here's the 3.3 version, with the PyThread_allocate_lock comment in the lock 
type.
Still working on the 3.4 argument clinic version.

--
Added file: 
http://bugs.python.org/file33838/threading.lock.docs.3.3-with-comment.patch

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

[issue18916] Various out-of-date Lock text in 3.2+

[Christopher Welborn]

Changes by Christopher Welborn cjwelb...@live.com:


Removed file: http://bugs.python.org/file33819/threading.lock.docs3.3.patch

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

[issue18916] Various out-of-date Lock text in 3.2+

[Christopher Welborn]

Christopher Welborn added the comment:

I meant to say 'attempting to work on the 3.4 arg clinic version', i can't make 
any promises. I'm using it as a learning experience but probably won't yield 
any real results any time soon.

--

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

[issue18916] Various out-of-date Lock text in 3.2+

[Christopher Welborn]

Christopher Welborn added the comment:

Hello, my name is Chris Welborn (or Cj). I've been looking for opportunities to 
work on python. I figured a little Doc fix would be perfect for my first patch, 
as you originally planned. I ran the python unit-tests and `make test`, plus a 
'patchcheck'. Even though I really only changed a couple strings, I wanted to 
be sure. I hope this patch is acceptable, but if it's not I would be glad to 
tidy it up in whatever way you see fit.

Thanks for leaving this for someone like me :)

-Cj

--
keywords: +patch
nosy: +cjwelborn
Added file: http://bugs.python.org/file33818/threading.lock.docs.patch

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

[issue18916] Various out-of-date Lock text in 3.2+

[R. David Murray]

R. David Murray added the comment:

Thanks for working on this.  The patch looks pretty good.  I would prefer to 
flow the two lines in the Lock docstring as a paragraph, rather than have once 
sentence per line.  Also, the OP mentions that the docs for type(Lock) mention 
PyThread_allocate_lock...do you want to look at fixing that as well?  As 
mentioned, it should reference Lock() instead.  The reference to 
PyThread_allocate_lock should be moved into comments in the type, IMO.

Also, this patch may be affected by the Argument Clinic Derby.  I don't know if 
the threading module is one of the ones that is being converted or not.  You 
can just ignore that issue since the full patch is needed for 3.3, but if you 
feel like figuring it out, and it is affected, you could produce an additional 
patch for 3.4.  Otherwise whoever applies your patch will figure out how to 
merge it.

--

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

[issue18916] Various out-of-date Lock text in 3.2+

[Christopher Welborn]

Christopher Welborn added the comment:

Yep, I missed the PyThread_allocate_lock reference. As far as the Argument 
Clinic Derby, I've been following the python-dev list and reading about 
Argument Clinic, but I don't know enough about it to do the conversion. It's a 
really good tool from what I can tell. I'll have to study it some more so in 
the future I can possibly help with the conversions.

I see the threading module listed in a 
href=http://bugs.python.org/issue20185;Issue #20185/a (Derby #17), but no 
patch for it yet.

Forgive my newbness, but I omitted putting a reference to 
PyThread_allocate_lock in the comments because I was confused about what kind 
of reference you were talking about. Something about making sure Python users 
see threading.Lock instead of PyThread_allocate_lock, or moving a statement 
like to create a lock in C, call the PyThread_allocate_lock function into the 
comments. If it's important for it to be there, could you let me know so I can 
make the edit?

Hopefully I have been of some help, instead of just wasting your time.

--
Added file: http://bugs.python.org/file33819/threading.lock.docs3.3.patch

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

[issue18916] Various out-of-date Lock text in 3.2+

[Christopher Welborn]

Changes by Christopher Welborn cjwelb...@live.com:


Removed file: http://bugs.python.org/file33818/threading.lock.docs.patch

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

[issue18916] Various out-of-date Lock text in 3.2+

[R. David Murray]

R. David Murray added the comment:

Yes, the latter: since someone thought it was important to mention, but only 
people working with the C code would benefit, it ought to be a comment in the C 
source.

If there's no AC patch for threading yet, then there's no problem with that, 
and your patch will be good for both 3.3 and 3.4.

--

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

[issue18916] Various out-of-date Lock text in 3.2+

[Tim Peters]

New submission from Tim Peters:

Here under 3.3.2:


 from threading import Lock
 help(Lock)
Help on built-in function allocate_lock in module _thread:

allocate_lock(...)
allocate_lock() - lock object
(allocate() is an obsolete synonym)

Create a new lock object.  See help(LockType) for information about locks.


But there is no relevant LockType anymore.  The type is now:


 type(Lock())
class '_thread.lock'


The docs should probably say help(type(Lock()) instead of help(LockType) 
now.  So let's try that:


 help(type(Lock()))
Help on class lock in module _thread:

class lock(builtins.object)
 |  A lock object is a synchronization primitive.  To create a lock,
 |  call the PyThread_allocate_lock() function.


That's a problem:  PyThread_allocate_lock() is a C function, not available 
(under that name) to Python code.  A Python user should probably stick to 
threading.Lock().

Skipping most other output:


...
 |  acquire(...)
 |  acquire([wait]) - bool
 |  (acquire_lock() is an obsolete synonym)
 |  
 |  Lock the lock.  Without argument, this blocks if the lock is already
 |  locked (even by the same thread), waiting for another thread to release
 |  the lock, and return True once the lock is acquired.
 |  With an argument, this will only block if the argument is true,
 |  and the return value reflects whether the lock is acquired.
 |  The blocking operation is interruptible.
...


That's not the right signature for acquire anymore.  Should be

acquire(blocking=True, timeout=-1) 

which is what the threading module docs say.  That is, the docs are up-to-date, 
but the help strings in the code aren't.  Since 3.2 is the first version 
introducing the timeout option, that's the earliest version I selected on this 
report.

I'm going to leave this for someone who wants an easy patch exercise - you're 
welcome ;-)

--
components: Interpreter Core
keywords: easy
messages: 196881
nosy: tim.peters
priority: low
severity: normal
stage: needs patch
status: open
title: Various out-of-date Lock text in 3.2+
type: behavior
versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5

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

[issue18916] Various out-of-date Lock text in 3.2+

[R. David Murray]

R. David Murray added the comment:

Thanks.  I suspect someone will indeed latch on to this soon enough.

We use the 'versions' to track what version we are going to fix the bug in.  So 
I've removed 3.2, since that only gets security fixes, and 3.5, since that 
doesn't exist yet.  (If we don't fix this for 3.4, we will change the versions 
next time we visit the issue.)

--
nosy: +r.david.murray
versions:  -Python 3.2, Python 3.5

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