classification
Title: subprocess: unreliability of returncode not clear from docs
Type: Stage:
Components: Documentation Versions: Python 2.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: collinwinter, georg.brandl, ohuiginn
Priority: normal Keywords:

Created on 2007-05-28 17:41 by ohuiginn, last changed 2008-01-06 16:01 by georg.brandl. This issue is now closed.

Messages (4)
msg32139 - (view) Author: Dan O'Huiginn (ohuiginn) Date: 2007-05-28 17:41
The docs for the subprocess module (http://docs.python.org/lib/node533.html) give the impression that you can reliably find the return code of a process by checking returncode:

--------
returncode
    The child return code. A None value indicates that the process hasn't terminated yet. A negative value -N indicates that the child was terminated by signal N (Unix only).
--------

But in fact, returncode is only updated when the poll() method is called, and therefore will often be out-of-date. For instance

>>> process=subprocess.Popen('true') #*nix command to do nothing
>>> process.returncode
>>> process.returncode==None
True
>>> process.poll()
0
>>> process.returncode
0


As far as I can see, it is always better to use poll() to check the status or return code of a subprocess. It might be good to either remove returncode from the docs entirely, or at least to explain that it won't always be correct.

[incidentally, having returncode/poll() give None for a running process, and 0 for a process that has exited successfully, seems like a recipe for generating bugs. But I guess it's too late to do anything about that now]
msg32140 - (view) Author: Collin Winter (collinwinter) * (Python committer) Date: 2007-06-06 16:20
What wording would you rather see in the subprocess docs?
msg32141 - (view) Author: Dan O'Huiginn (ohuiginn) Date: 2007-06-06 18:41
Thanks for the reply, Collin. Perhaps something like:
Note: The value stored in returncode may be out-of-date. Use poll() to reliably find the current return code.

Alternatively, would it be possible to leave it out completely [and move the explanation of what return codes mean up into the description of poll()]? I canĀ“t imagine many situations where it is a good idea to check returncode directly, and as I understand it the module documentation only covers variables that are useful to the outside world.
msg59390 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-01-06 16:01
Thanks for the report, fixed the documentation in r59777.
History
Date User Action Args
2008-01-06 16:01:43georg.brandlsetstatus: open -> closed
assignee: georg.brandl
resolution: fixed
messages: + msg59390
nosy: + georg.brandl
2007-05-28 17:41:22ohuiginncreate