This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: '-' sign typo in example
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ben Kane, abarry, docs@python, r.david.murray
Priority: normal Keywords:

Created on 2016-05-29 19:15 by Ben Kane, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Messages (4)
msg266614 - (view) Author: Ben Kane (Ben Kane) Date: 2016-05-29 19:15
On page https://docs.python.org/3/library/subprocess.html#replacing-os-system

it looks like the code in the realistic example has a spurious '-' sign.
The line:

        print("Child was terminated by signal", -retcode, file=sys.stderr)

shouldn't have the minus sign negating the retcode:

        print("Child was terminated by signal", retcode, file=sys.stderr)

Full code in the example:

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

should be:

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

Thanks, and apologies if I erred somewhere in this report.
msg266616 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2016-05-29 19:23
A negative return code generally means an error occurred. Negating retcode here is equivalent to abs(retcode), which shows you want a positive integer to appear in the message - it's not an error.

Could replace '-retcode' with 'abs(retcode)' to be more clear. Possibly also add a comment in the code example body to further clarify this.
msg266632 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-05-29 20:29
The negative return code indicates the child was terminated by a signal, exactly as the example error message says.  The signal number is the positive value of the return code.  It makes more sense to negate it than it does to call abs, since we *know* it is negative.

IMO the example is correct as written.
msg266732 - (view) Author: Ben Kane (Ben Kane) Date: 2016-05-31 04:01
https://docs.python.org/3/library/subprocess.html#subprocess.Popen.returncode

does mention the negativeness about returncode in conjunction with POSIX signals. It would be helpful to mention this Python-specific (I think) behavior in a comment. 
However, returncode can also be set by poll() and wait(), which can also return errors. In the more realistic example, I would appreciate code that handles those errors as well (a check for returncode > 0), or a comment detailing that other errors aren't handled. I copied that code into mine, and didn't consider those cases initially, because "realistic" was in the description.
History
Date User Action Args
2022-04-11 14:58:31adminsetgithub: 71342
2016-05-31 04:01:55Ben Kanesetmessages: + msg266732
2016-05-29 20:29:48r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg266632

resolution: not a bug
stage: resolved
2016-05-29 19:23:17abarrysetnosy: + abarry
messages: + msg266616
2016-05-29 19:15:29Ben Kanecreate