classification
Title: threading.Thread documentation can be improved
Type: enhancement Stage:
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brian.curtin, docs@python, pitrou, r.david.murray, rhettinger, roysmith
Priority: normal Keywords:

Created on 2011-01-31 01:42 by roysmith, last changed 2011-01-31 14:40 by pitrou. This issue is now closed.

Messages (8)
msg127566 - (view) Author: Roy Smith (roysmith) Date: 2011-01-31 01:42
The documentation for the threading.Thread constructor says:

"target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called."

This could be improved by explicitly stating that target is called in a static context.  As written, it takes a bit of thought (and experimentation) to be sure of that.
msg127568 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-01-31 03:10
I have no idea what "a static context" means, so it wouldn't make it any clearer to me.  Can you explain further what your confusion is?
msg127569 - (view) Author: Roy Smith (roysmith) Date: 2011-01-31 03:23
What I meant was whether target should be declared as @staticmethod or not.
msg127581 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-01-31 08:00
I still don't understand.  I haven't used threading much, but I don't believe I've ever used a static method with it.
msg127583 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-01-31 08:15
Roy, it's not clear what you're after.  What is it that you think is special about the way the target is called?
msg127597 - (view) Author: Roy Smith (roysmith) Date: 2011-01-31 13:19
Here's the code I ended up writing:

class Foo():
   def __init__(self):
       self.thread = Thread(target=Foo.runner, args=[self])
       self.thread.start()

   @staticmethod
   def runner(self):
      # blah, blah, blah

It was not immediately clear from the documentation if my runner() method should be declared static or not.  In retrospect, it must be (since this can be used with target functions which are not class methods at all), but it took a bit of thought to get from what the documentation said (i.e. 'callable object to be invoked by the run() method') to that conclusion.  

It seems to me the documentation could be a bit more explicit that your target does not get called as a method of some object.  Changing the text to read, "static function or other callable object" would remove any such confusion.

It could be that some of my confusion is due to my previously working with a C++ threading package where the thread runner functions *were* class methods.  Still, it seems like the potential for other people to be similarly confused exists and a little tweaking of the documentation text would help.
msg127600 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2011-01-31 14:35
> It was not immediately clear from the documentation if my runner() method should be declared static or not.

The doc doesn't mention static methods at all, and my uses and others that I've seen have never used static methods.
msg127601 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-01-31 14:40
You don't have to use any staticmethod here (actually, staticmethod is an anti-pattern in Python). Just write:

class Foo():
   def __init__(self):
       self.thread = Thread(target=self.runner)
       self.thread.start()

   def runner(self):
      # blah, blah, blah
History
Date User Action Args
2011-01-31 14:40:18pitrousetstatus: open -> closed

nosy: + pitrou
messages: + msg127601

resolution: works for me
2011-01-31 14:35:34brian.curtinsetnosy: + brian.curtin
messages: + msg127600
2011-01-31 13:19:14roysmithsetnosy: rhettinger, roysmith, r.david.murray, docs@python
messages: + msg127597
2011-01-31 08:15:24rhettingersetnosy: + rhettinger
messages: + msg127583
2011-01-31 08:00:01r.david.murraysetnosy: roysmith, r.david.murray, docs@python
messages: + msg127581
2011-01-31 03:23:21roysmithsetnosy: roysmith, r.david.murray, docs@python
messages: + msg127569
2011-01-31 03:10:45r.david.murraysetversions: + Python 3.1, Python 2.7, Python 3.2, - Python 2.6
nosy: + r.david.murray

messages: + msg127568

type: enhancement
2011-01-31 01:42:50roysmithcreate