Define EXIT_SUCCESS and EXIT_FAILURE constants in sys

[abalkin]

BPO	24053
Nosy	@abalkin, @pitrou, @scoder, @rbtcollins, @skrah, @berkerpeksag, @vadmium, @serhiy-storchaka, @eamanu, @eedmunds, @Fat-Zer
PRs	bpo-24053: Add EXIT_SUCCESS and EXIT_FAILURE values in the sys module #14773
Files	issue24053.patch

^{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/abalkin'
closed_at = None
created_at = <Date 2015-04-24.15:47:49.923>
labels = ['easy', 'type-feature', '3.8']
title = 'Define EXIT_SUCCESS and EXIT_FAILURE constants in sys'
updated_at = <Date 2022-02-19.08:03:29.457>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2022-02-19.08:03:29.457>
actor = 'mark.dickinson'
assignee = 'belopolsky'
closed = False
closed_date = None
closer = None
components = []
creation = <Date 2015-04-24.15:47:49.923>
creator = 'belopolsky'
dependencies = []
files = ['39197']
hgrepos = []
issue_num = 24053
keywords = ['patch', 'easy']
message_count = 37.0
messages = ['241949', '241953', '241960', '241962', '241966', '241972', '241978', '242061', '242126', '242129', '242130', '242131', '242132', '242133', '242135', '242137', '242139', '242141', '242142', '242143', '242144', '242145', '242146', '242147', '242148', '242149', '242150', '242151', '242152', '242153', '242154', '247081', '255473', '331714', '332526', '413528', '413537']
nosy_count = 11.0
nosy_names = ['belopolsky', 'pitrou', 'scoder', 'rbcollins', 'skrah', 'berker.peksag', 'martin.panter', 'serhiy.storchaka', 'eamanu', 'edmundselliot@gmail.com', 'Fat-Zer']
pr_nums = ['14773']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue24053'
versions = ['Python 3.8']

[abalkin]

Python defines some BSDish exit codes in the os module:

    EX_CANTCREAT = 73
    EX_CONFIG = 78
    EX_DATAERR = 65
    EX_IOERR = 74
    EX_NOHOST = 68
    EX_NOINPUT = 66
    EX_NOPERM = 77
    EX_NOUSER = 67
    EX_OK = 0
    EX_OSERR = 71
    EX_OSFILE = 72
    EX_PROTOCOL = 76
    EX_SOFTWARE = 70
    EX_TEMPFAIL = 75
    EX_UNAVAILABLE = 69
    EX_USAGE = 64

but these are documented as only available on UNIX and may not be portable across all flavors.

POSIX [1] and C99 defines EXIT_SUCCESS and EXIT_FAILURE constants. I propose adding those to sys.

Having these constants in sys will make them more discoverable because they will be next to sys.exit().

[1] http://pubs.opengroup.org/onlinepubs/009695399/functions/exit.html

[abalkin]

I am attaching a patch implementing these constants. If this is well-received, I will add documentation.

[ethanfurman]

Where are EXIT_FAILURE and EXIT_SUCCESS defined?

And we should probably call them EX_FAILURE and EX_SUCESS to match what's already there.

[abalkin]

Where are EXIT_FAILURE and EXIT_SUCCESS defined?

In C stdlib:

$ grep EXIT_ /usr/include/stdlib.h
#define	EXIT_FAILURE	1
#define	EXIT_SUCCESS	0

we should probably call them EX_FAILURE and EX_SUCESS to match what's already there.

No. EX_ macros come from a non-standard sysexits.h header. Python stdlib traditionally does not change the spelling of the constants that
come from C libraries or standards.

Even in the absence of POSIX and C99 standards, I would prefer EXIT_ prefix over EX_ for clarity. "EX" does not clearly mean "exit", it may stand for "exception", "execution", "example" etc.

[ethanfurman]

Sounds good, I have no objections.

[serhiy-storchaka]

Aren't EXIT_SUCCESS and EXIT_FAILURE needed only for support VMS?

[abalkin]

I would say, they are there to support *humans*. I am not aware of any human language where "success" is spelled 0. (1 is a failing mark in some schools - so there is a precedent for that. :-)

[pitrou]

Those should be in the os module, not in sys. The os module is for interfaces to the operating system, while the sys module is for Python-specific stuff.

As for the point of adding them, I don't find them useful, but I won't oppose it either :-)

[abalkin]

Those should be in the os module, not in sys.

I disagree. The whole point of this proposal is to have platform-independent status codes available next to the sys.exit() function.

We already have over a dozen BSDish exit codes in os that are hardly ever used.

[pitrou]

We already have over a dozen BSDish exit codes in os that are hardly
ever used.

Then precisely, those new codes should go in the os module as well.

[ethanfurman]

I agree with Antoine -- all the exit codes should be in one place.

[abalkin]

Then precisely, those new codes should go in the os module as well.

What is your logic? Having os.EX_ codes in os does not help as far as sys.exit() is concerned: no-one is using them and they are not available on all platforms. If we add EXIT_FAILURE and EXIT_SUCCESS to os now, we will only create confusion: should I use os.EX_OK or os.EXIT_SUCCESS?

Note that sys.exit() is different from os._exit(). It may not even result in termination of the interpreter. Why should users of sys.exit() be required to import os if they want to indicate a failure?

[pitrou]

Well, my favourite answer would be use sys.exit(0) and sys.exit(1), respectively (or raise SystemExit without or with an error message), as everyone is already doing right now. Since I don't really get the usability argument of adding those constants, it's hard for me to buy that they should sit close to sys.exit().

[abalkin]

Ethan> all the exit codes should be in one place.

Do you realize that os.EX_* codes are not available on Windows? Having platform-independent EXIT_* codes next to posix-only EX_* codes will send the wrong message about their availability.

[abalkin]

Antoine> Since I don't really get the usability argument of adding those constants ..

If I am alone in finding exit(EXIT_FAILURE) clearer than exit(1), I should certainly drop my proposal.

[pitrou]

Well it would be clearer if not for the widely established knowledge (amongst most or all programming languages) that zero means success and non-zero means failure. So in this case I find it personally useless.

[skrah]

I'm +0 on adding these. The only reason is that I've seen academic
code written by well-known researchers that used 1 for a successful
exit. :)

I'm not sure about the os module. These are C99 and not OS specific.

[abalkin]

Stefan> I've seen academic code written by well-known researchers
Stefan> that used 1 for a successful exit.

Thank you! What I've seen more than once was exit(True) to indicate success where True is not necessarily a literal, but something like
len(results) > 0.

[serhiy-storchaka]

This can be implemented as separate module on PyPI. No need to add these aliases for 0 and 1 to the stdlib.

[abalkin]

This can be implemented as separate module on PyPI.

Sure! Make them even less discoverable!

Let me try to state my motivations for adding these constants:

1. I find exit(EXIT_FAILURE) much clearer than exit(1).
2. I want people to standardize on status=1 for a generic failure code. I do see exit(-1) used as often as exit(1).
3. I want discourage people from using computed integer results as exit status. For example,

# process files and store errors in a list
sys.exit(len(errors))  # bad - success for multiples of 256 errors
sys.exit(sys.EXIT_SUCCESS if not errors else sys.EXIT_FAILURE)  # good

[ethanfurman]

An entire PyPI module for two constants?

Change of heart, I'm okay with them going in sys, but only +0 on adding them.

This SO answer* has an interesting point to make about the nature of return codes and what their values should be; tl;dr - the convention should be between your program and the other program(s) you are trying communicate with.

• http://stackoverflow.com/a/8869000/208880

[abalkin]

the convention should be between your program and the other program(s) you are trying communicate with.

This may be true in general, but Python stdlib sets the convention in its subprocess.check_call and subprocess.check_output methods. These methods use 0=success convention.

[pitrou]

I want people to standardize on status=1 for a generic failure code.

Why that? Multiple error codes can be used by the same program, depending on the kind of error.

I want discourage people from using computed integer results as exit status.

Ok, that's the first good argument for this feature. Although I would encourage people raise an exception if they want to signify a failure, rather than simply change the error code.

[berkerpeksag]

1. I find exit(EXIT_FAILURE) much clearer than exit(1).

    import sys

    exit(sys.EXIT_FAILURE)

or

    import sys

    sys.exit(sys.EXIT_FAILURE)

don't look too clear to me. On the other hand, these constants may helpful to people who came from C world.

3. I want discourage people from using computed integer results as exit status.

Adding a FAQ entry or updating sys.exit() documentation would be more suitable to achieve the aim of this item. I wouldn't add two constants to the stdlib because of a bad programming practice.

[scoder]

why not spell them "sys.exit.FAILURE" and "sys.exit.SUCCESS" ?

[abalkin]

> I want people to standardize on status=1 for a generic failure code.

Why that? Multiple error codes can be used by the same program, depending on the kind of error.

Antoine, please read what I write carefully before disagreeing. I want "to standardize on status=1 for a **generic** failure code". Cooperating processes can certainly agree on other values for the specific failure modes.

What I really want to avoid is the use of -1 as a generic failure code, because it leads to a rather common error

rc = subprocess.call(..)
if rc < 0:
   raise Error   # never reached!

[serhiy-storchaka]

How often you see EXIT_SUCCESS and EXIT_FAILURE in C code besides GNU tools that should support VMS? And even GNU tools usually use multiple error codes for different kinds of errors.

I think that these constants are rather unusual for C programmers.

I'm only -0 on adding these constants, not -1, because I'm sure they will be never used. But this will add a burden on the documentation and will confuse inexperienced users when they unexpectedly encounter with sys.exit(sys.EXIT_FAILURE) instead of sys.exit(1).

[abalkin]

And even GNU tools usually use multiple error codes for different kinds of errors.

And how often do they not give them symbolic names?

[scoder]

Actually, my guess is also that these constants will not be used. Not because they are not helpful, but because they'd only be available in Python 3.5+. Meaning that if you use them, your code won't work with long time supported CPython versions like 3.4 for the next decade or so.

[abalkin]

will confuse inexperienced users when they unexpectedly encounter with sys.exit(sys.EXIT_FAILURE) instead of sys.exit(1).

Are you serious? I've seen senior programmers who thought that status < 0 means failure and status >= 0 means success. Why would anyone who understands English would need to know what the numerical value of EXIT_FAILURE is to understand that status=EXIT_FAILURE means "failure"?

Not to mention that google returns a pageful of relevant links for "EXIT_FAILURE".

[abalkin]

if you use them, your code won't work with long time
supported CPython versions like 3.4 for the next decade or so.

This would be a generic argument against any new feature. I don't think it is very compelling in this case. For people who develop on a latest version. these constants will pop up in sys.<tab> autocompletion and they will likely use them. If they need to support pre-3.5 versions,

try:
from sys import exit, EXIT_FAILURE
except ImportError:
from sys import exit
EXIT_FAILURE = 1

is not a hard work-around.

You would say, why not just use EXIT_FAILURE = 1 to begin with? To avoid Bob using EXIT_FAILURE = -1, Alice using EX_FAIL = 1 and Karl
giving up and using exit(1) in perpetuity.

[vadmium]

FWIW I have wondered in the past why these constants were missing. I would be more likely to use them when checking an exit status than when setting one. I typically do “raise SystemExit()” or “raise SystemExit('Error message')”, which implicitly sets the status.

My preference would be to put EXIT_SUCCESS and EXIT_FAILURE in the “os” module, next to the existing EX_ codes. But I guess the “sys” module would also work.

[rbtcollins]

@serhiy, EXIT_FAILURE is used in Python's C code itself (just once admittedly, and then we use 0 sometimes for success and sometimes for errors, and then 1 for errors... aiee.)

FWIW to the extent that folk want to write posix code in Python, I'm all for helping them, I find the amount of help this will be to be hard to assess. There is some code to adding the constants in documentation and learning surface area.

Right now we don't document all the ways Python can interact with exit codes, and I suspect thats actually a bigger burden than writing the code to generate any given code.

[eedmunds]

I have personally come across situations where I am calling a Python script from a C program and would like to check the exit codes of the script, and have had to write sys.exit(1) and sys.exit(0) in Python, and compared them to EXIT_SUCCESS/EXIT_FAILURE in C. It would have been easy to introduce a bug where I returned the wrong exit code, so I was hoping they would have been implemented in sys.

It seems like a no-brainer to add these, they reduce magic number use and improve the accessibility of Python to people coming from C. I would love to add these if everyone is OK with it.

[eamanu]

Hi Elliot!

It seems like a no-brainer to add these, they reduce magic number use and improve the accessibility of Python to people coming from C. I would love to add these if everyone is OK with it.

Sound great. But IMO I think that this can be solved doing:

    EXIT_FAILURE = 1
    EXIT_SUCCESS = 0

    sys.exit(EXIT_SUCCES)

And what is the difference between EX_OK and EXIT_SUCCESS? both values are 0.

BTW, I think this is a good improve and more for C coder.

I recommend you mmake the PR.

[Fat-Zer]

Any reasons the PR still not merged?

[scoder]

Any reasons the PR still not merged?

There was dissent about whether these constants should be added or not. It doesn't help to merge a PR that is not expected to provide a benefit.

[arhadthedev]

If I am alone in finding exit(EXIT_FAILURE) clearer than exit(1), I should certainly drop my proposal.

@abalkin Currently, sys.exit(message) chooses the EXIT_SUCCESS/EXIT_FAILURE code depending on whether the message is None.

Is sys.exit(EXIT_SUCCESS)/sys.exit(EXIT_FAILURE) still relevant then?

[calestyo]

Is sys.exit(EXIT_SUCCESS)/sys.exit(EXIT_FAILURE) still relevant then?

Maybe one doesn't want to give an actual message but just control the exit status?

Also I have for example code, where depending on what happens I set some exit_status variable. But I don't e.g. just pass that to sys.exit() in the end, but have another if before, that would want to check something like exit_status != EXIT_SUCCESS and do extra things depending on that.

So I think one really "needs" the symbol.

Also, these are really standardised system symbols, so people might want to use them for checking exit statuses of subprocesses and not just as part of sys.exit().

As for the discussion about sys vs. os... AFAIU POSIX, only EXIT_SUCCESS is defined to be a fixed value (0)... so I'd interpret that as EXIT_FAILURE being potentially platform-dependent.

Oh and it was mentioned that EX_OK would be documented as UNIX-only, but current documentation seems to say "Availability: Unix, Windows.".

[pitrou]

Hmm... let's be pragmatic here. sys.exit(0) is known to exit with success. sys.exit(non-zero integer) is known to be a failure exit. Which exit code you choose is on you: many CLI utilities can actually return different error codes depending on the actual error.

Since all concrete use cases are well-served already, I will close this isuue.