[issue40094] Add os.status_to_exitcode() function

[STINNER Victor]

STINNER Victor <vstinner at python.org> added the comment:

The function can be used to convert the result of the following functions:

* os.system() (on Unix)
* os.wait()
* os.waitpid()
* os.wait3()
* os.wait4()
* pty.spawn()

Note: waitid() has a different API, si_status can be used directly, its meaning depends on si_code.

--

First, I proposed os._wait_status_to_returncode() name.

I renamed it to os.status_to_exitcode().

Maybe the "status" term used alone is too general. 

I'm not sure neither if it's correct to write "exitcode" a single word. For example, Windows uses GetExitCodeProcess() name: "Exit Code" means that they are two separated words. The Python os documentation uses "exit code" and "exit status", but never "exitcode" or "exitstatus".

The system() function manual page says:

"""
RETURN VALUE
  (...)
   In the last two cases, the return value is a "wait status" that can be examined using the macros described in waitpid(2).  (i.e., WIFEXITED(), WEXITSTATUS(), and so on).
"""

Python pty.spawn() documentation says: "(...) returns the status value from os.waitpid() on the child process".

--

In my current PR, the function documentation is: "Convert an exit status to an exit code"

Other name ideas:

* exit_status_to_code()
* exit_status_to_exit_code()
* wait_status_to_exit_code()

The Wikipedia article is called "Exit status" and then tells about "exit status code" :-) So it can be surprising to have a function supposed to convert an "exit status" into an "exit code".

It seems like "Convert a waitpid() wait status to an exit code" is the best documentation and so that wait_status_to_exit_code() is the most correct and least confusing name, even if it's longer than other name candidates.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40094>
_______________________________________