[ python-Bugs-1727024 ] subprocess: unreliability of returncode not clear from docs

[SourceForge.net]

Bugs item #1727024, was opened at 2007-05-28 17:41
Message generated for change (Comment added) made by ohuiginn
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1727024&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.5
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Dan O'Huiginn (ohuiginn)
Assigned to: Nobody/Anonymous (nobody)
Summary: subprocess: unreliability of returncode not clear from docs

Initial Comment:
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]


----------------------------------------------------------------------

>Comment By: Dan O'Huiginn (ohuiginn)
Date: 2007-06-06 18:41

Message:
Logged In: YES 
user_id=1803299
Originator: YES

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.

----------------------------------------------------------------------

Comment By: Collin Winter (collinwinter)
Date: 2007-06-06 16:20

Message:
Logged In: YES 
user_id=1344176
Originator: NO

What wording would you rather see in the subprocess docs?

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1727024&group_id=5470