All ideas for numbering the error codes are welcome here.

[GijsTimmers]

I was thinking of something like:

xyy: x = action, yy = result. For instance:

100 = login done, no errors
101 = login error, couldn't reach server
102 = login error, credentials incorrect

200 = logout done, no errors
201 = logout error, couldn't reach server
202 = logout error, credentials incorrect

[jovanbulck]

As far as I know a user program can in principle use any exit value in the range 0..255. Some things you should know however:

1. exit code 0 (and only zero) means success, any other exit code is failure. e.g. kotnetcli && echo done will be interpreted by the shell to only print done when kotnetcli has a zero exit code
2. some exit codes are reserved and should be avoided
3. There has been some effort on standardizing application exit codes: cat /usr/include/sysexits.h in the range 64 - 113:

/*
 *  SYSEXITS.H -- Exit status codes for system programs.
 *
 *  This include file attempts to categorize possible error
 *  exit statuses for system programs, notably delivermail
 *  and the Berkeley network.
 *
 *  Error numbers begin at EX__BASE to reduce the possibility of
 *  clashing with other exit statuses that random programs may
 *  already return.  The meaning of the codes is approximately
 *  as follows:
 *
 *  EX_USAGE -- The command was used incorrectly, e.g., with
 *      the wrong number of arguments, a bad flag, a bad
 *      syntax in a parameter, or whatever.
 *  EX_DATAERR -- The input data was incorrect in some way.
 *      This should only be used for user's data & not
 *      system files.
 *  EX_NOINPUT -- An input file (not a system file) did not
 *      exist or was not readable.  This could also include
 *      errors like "No message" to a mailer (if it cared
 *      to catch it).
 *  EX_NOUSER -- The user specified did not exist.  This might
 *      be used for mail addresses or remote logins.
 *  EX_NOHOST -- The host specified did not exist.  This is used
 *      in mail addresses or network requests.
 *  EX_UNAVAILABLE -- A service is unavailable.  This can occur
 *      if a support program or file does not exist.  This
 *      can also be used as a catchall message when something
 *      you wanted to do doesn't work, but you don't know
 *      why.
 *  EX_SOFTWARE -- An internal software error has been detected.
 *      This should be limited to non-operating system related
 *      errors as possible.
 *  EX_OSERR -- An operating system error has been detected.
 *      This is intended to be used for such things as "cannot
 *      fork", "cannot create pipe", or the like.  It includes
 *      things like getuid returning a user that does not
 *      exist in the passwd file.
 *  EX_OSFILE -- Some system file (e.g., /etc/passwd, /etc/utmp,
 *      etc.) does not exist, cannot be opened, or has some
 *      sort of error (e.g., syntax error).
 *  EX_CANTCREAT -- A (user specified) output file cannot be
 *      created.
 *  EX_IOERR -- An error occurred while doing I/O on some file.
 *  EX_TEMPFAIL -- temporary failure, indicating something that
 *      is not really an error.  In sendmail, this means
 *      that a mailer (e.g.) could not create a connection,
 *      and the request should be reattempted later.
 *  EX_PROTOCOL -- the remote system returned something that
 *      was "not possible" during a protocol exchange.
 *  EX_NOPERM -- You did not have sufficient permission to
 *      perform the operation.  This is not intended for
 *      file system problems, which should use NOINPUT or
 *      CANTCREAT, but rather for higher level permissions.
 */

#define EX_OK       0   /* successful termination */

#define EX__BASE    64  /* base value for error messages */

#define EX_USAGE    64  /* command line usage error */
#define EX_DATAERR  65  /* data format error */
#define EX_NOINPUT  66  /* cannot open input */
#define EX_NOUSER   67  /* addressee unknown */
#define EX_NOHOST   68  /* host name unknown */
#define EX_UNAVAILABLE  69  /* service unavailable */
#define EX_SOFTWARE 70  /* internal software error */
#define EX_OSERR    71  /* system error (e.g., can't fork) */
#define EX_OSFILE   72  /* critical OS file missing */
#define EX_CANTCREAT    73  /* can't create (user) output file */
#define EX_IOERR    74  /* input/output error */
#define EX_TEMPFAIL 75  /* temp failure; user is invited to retry */
#define EX_PROTOCOL 76  /* remote error in protocol */
#define EX_NOPERM   77  /* permission denied */
#define EX_CONFIG   78  /* configuration error */

#define EX__MAX 78  /* maximum listed value */

Of course another thing to do is put exit code definitions in a separate file and only use exit codes through their symbolic constant name (as in the sysexits.h C language file but then in Python).

[GijsTimmers]

Thank you, I can't believe I missed the 0 for success 😆

[jovanbulck]

More specific proposal to adhere to the 'standard' somehow:

EX_OK = 0 = success

EX_USAGE = 64 = wrong combination of command line options ....

EX_DATAERR = 65 = user input error (e.g. when asking credentials and its in the wrong format or so)

EX_UNAVAILABLE = 69 = when netlogin.kuleuven.be cannot be reached

EX_SOFTWARE = 70  = when depending packages fail unexpected (mechanize, keyring, ....) or cannot be imported

EX_IOERR = 74  = when dealing with files

some other appropriate code from the list when logging in / out failed: should be different when credentials were wrong (EX_NOPERM or so) and when credentials ok but already logged in

Point here is that exit codes should reflect the error category. I think for shell scripting and the like it's not a good idea to have multiple exit codes for essentially the same error, depending on the action being performed (e.g. login error, couldn't reach server <> logout error, couldn't reach server).

[GijsTimmers]

Point here is that exit codes should reflect the error category.

I agree. This is also a lot easier to code.

[GijsTimmers]

Error codes file has been added. b09bad4

[jovanbulck]

nice! looking good 👍

maybe also refer / give credit to the "standard" at cat /usr/include/sysexits.h

[GijsTimmers]

Yes, I'll write that.

[jovanbulck]

I implemented a basic dummy login testsuite: https://github.com/GijsTimmers/kotnetcli/blob/dev/testsuite.py; run with kotnetcli_test.py --run-tests

when we implement fine grained exit codes as discussed above, we can assert them there too :-)