[Python-Dev] slightly misleading Popen.poll() docs

[Chris Withers]

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