subprocess: unreliability of returncode not clear from docs

[ohuiginn]

BPO	1727024
Nosy	@birkenfeld

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2008-01-06.16:01:43.950>
created_at = <Date 2007-05-28.17:41:22.000>
labels = ['docs']
title = 'subprocess: unreliability of returncode not clear from docs'
updated_at = <Date 2008-01-06.16:01:43.948>
user = 'https://bugs.python.org/ohuiginn'

bugs.python.org fields:

activity = <Date 2008-01-06.16:01:43.948>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2008-01-06.16:01:43.950>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2007-05-28.17:41:22.000>
creator = 'ohuiginn'
dependencies = []
files = []
hgrepos = []
issue_num = 1727024
keywords = []
message_count = 4.0
messages = ['32139', '32140', '32141', '59390']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'collinwinter', 'ohuiginn']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue1727024'
versions = ['Python 2.5']

[ohuiginn]

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]

[collinwinter]

What wording would you rather see in the subprocess docs?

[ohuiginn]

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.

[birkenfeld]

Thanks for the report, fixed the documentation in r59777.

[zitterbewegung]

Note this is closed but there is an open issue that is also a duplication of this issue.
#87452 (comment) and the change isn't in the docs.