[issue11073] threading.Thread documentation can be improved
New submission from Roy Smith <roy@panix.com>: 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. ---------- assignee: docs@python components: Documentation messages: 127566 nosy: docs@python, roysmith priority: normal severity: normal status: open title: threading.Thread documentation can be improved versions: Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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? ---------- nosy: +r.david.murray type: -> feature request versions: +Python 2.7, Python 3.1, Python 3.2 -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
Roy Smith <roy@panix.com> added the comment: What I meant was whether target should be declared as @staticmethod or not. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
Raymond Hettinger <rhettinger@users.sourceforge.net> added the comment: Roy, it's not clear what you're after. What is it that you think is special about the way the target is called? ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
Roy Smith <roy@panix.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
Brian Curtin <curtin@acm.org> added the comment:
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. ---------- nosy: +brian.curtin _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: 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 ---------- nosy: +pitrou resolution: -> works for me status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11073> _______________________________________
participants (5)
-
Antoine Pitrou -
Brian Curtin -
R. David Murray -
Raymond Hettinger -
Roy Smith