slightly misleading Popen.poll() docs
Hi All, Would anyone object to me making a change to the docs for 2.6, 2.7 and 3.x to clarify the following: http://docs.python.org/3/library/subprocess.html#subprocess.Popen.poll A couple of my colleagues have ended up writing code like this: proc = Popen(['some', 'thing']) code = proc.poll() if code: raise Exception('An error happened: %s' % code) ...on the back of the fact that if your process terminates *really* quickly, *and* the docs say that the returncode is set by poll() (*sigh*). I'd like to change the docs for poll() to say: """ Check if child process has terminated. If it has, the returncode attribute will be set and that value will be returned. If it has not, None will be returned and the returncode attribute will remain None. """ Any objections? Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
Le Wed, 05 Dec 2012 16:08:46 +0000, Chris Withers <chris@simplistix.co.uk> a écrit :
The doc looks clear to me. poll() returns the returncode attribute which is described thusly: "A None value indicates that the process hasn’t terminated yet." Therefore, I don't understand the confusion. poll() is explicitly non-blocking, and it is silly to expect it to return a process return code when the process hasn't returned yet (!). The correct answer is to use the wait() method (or communicate()), which is described two lines below poll(). May I suggest your colleagues didn't read the doc at all? Regards Antoine.
On 05/12/2012 16:34, Antoine Pitrou wrote:
Because lazy/busy people don't bother reading the links underneath docs...
I agree, however, I also: - don't see any harm in the change I propose - do see a slight improvement for the comprehending impaired ;-)
May I suggest your colleagues didn't read the doc at all?
One of them quoted the docs at me at proof that his code must be correct ;-) Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
On 06/12/12 03:08, Chris Withers wrote:
Possibly because it is 4am here, I had to read this three times to understand it. How is this instead? """ Check if child process has terminated. Returns None while the child is still running, any non-None value means that the child has terminated. In either case, the return value is also available from the instance's returncode attribute. """ -- Steven
On 05/12/2012 17:15, Steven D'Aprano wrote:
Do you want to make the commit or shall I? Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
Le Wed, 05 Dec 2012 16:08:46 +0000, Chris Withers <chris@simplistix.co.uk> a écrit :
The doc looks clear to me. poll() returns the returncode attribute which is described thusly: "A None value indicates that the process hasn’t terminated yet." Therefore, I don't understand the confusion. poll() is explicitly non-blocking, and it is silly to expect it to return a process return code when the process hasn't returned yet (!). The correct answer is to use the wait() method (or communicate()), which is described two lines below poll(). May I suggest your colleagues didn't read the doc at all? Regards Antoine.
On 05/12/2012 16:34, Antoine Pitrou wrote:
Because lazy/busy people don't bother reading the links underneath docs...
I agree, however, I also: - don't see any harm in the change I propose - do see a slight improvement for the comprehending impaired ;-)
May I suggest your colleagues didn't read the doc at all?
One of them quoted the docs at me at proof that his code must be correct ;-) Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
On 06/12/12 03:08, Chris Withers wrote:
Possibly because it is 4am here, I had to read this three times to understand it. How is this instead? """ Check if child process has terminated. Returns None while the child is still running, any non-None value means that the child has terminated. In either case, the return value is also available from the instance's returncode attribute. """ -- Steven
On 05/12/2012 17:15, Steven D'Aprano wrote:
Do you want to make the commit or shall I? Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
participants (5)
-
Antoine Pitrou -
Chris Withers -
Chris Withers -
Nick Coghlan -
Steven D'Aprano