How does a Python program set the exit status its supervisor sees when it fails?

## Exit status is the only thing a supervisor can read without parsing When the process ends, the supervisor reaps it and gets one small integer. That number decides whether the run counts as a success, whether a restart happens, and — with policies that distinguish codes — whether the service should stay down. So producing the right number is **part of the service's contract**, not a detail. ## How CPython produces it There are three ordinary paths. 1. First, the program runs to the end of its top-level code and the interpreter exits with 0. 2. Second, an exception propagates out of the top level: CPython prints the traceback to `sys.stderr` and exits with 1 — always 1, regardless of what the exception was. 3. Third, the program raises `SystemExit`, normally via `sys.exit`, and the interpreter uses the value carried on the exception. That third path deserves care because it is routinely misdescribed. **`sys.exit` does not terminate anything; it raises.** The exception then unwinds the stack like any other, which is precisely what you want: `finally` blocks run, `with` blocks call their `__exit__`, and functions registered with `atexit.register` run at the end. The argument becomes the exception's `code` attribute: - an `int` is used as the status; - `None` (the default) means 0; - anything else is printed to `sys.stderr` and the status becomes 1. That last rule is why `sys.exit('config file missing')` is a legitimate one-liner in a small script — it writes the message where the supervisor's log capture will see it and exits non-zero — and also why nobody should expect a string to become a numeric code. ## Why the base class matters `SystemExit` derives from `BaseException`, not from `Exception`. This is deliberate: the defensive `except Exception:` you wrap a request handler in must not accidentally cancel a shutdown. A bare `except:` or `except BaseException:` does catch it, and that is the classic bug where a **service refuses to die** — the intended exit is swallowed by a catch-all in a loop and the process runs on, doing nothing useful, while the supervisor sees a perfectly healthy process. A second surprise lives in **threads**. `SystemExit` raised inside a non-main thread ends only that thread; the threading machinery treats it as a normal way for a thread to finish and the process carries on, eventually exiting 0. A worker that decides the whole service must stop has to communicate that to the main thread — an event, a queue sentinel, a flag the main loop checks — rather than calling `sys.exit` where it stands. ## The numeric range On Unix the wait status carries only the **low eight bits** of what the process passed, so codes live in 0–255. `sys.exit(256)` is reported as 0, which looks like success and is one of the nastier self-inflicted wounds available; negative numbers wrap, so -1 arrives as 255. Keep codes small and deliberate. A common shape is: - 0 for success, - 1 for a generic failure, - and a couple of specific codes for classes the operator cares about — for example one code meaning `this configuration cannot work, restarting will not help` and another meaning `a dependency was unavailable, restarting later probably will`. Whether the supervisor can act on the distinction depends on its policy, but the codes cost nothing and they document intent in the logs. ## The blunt instrument `os._exit` ends the process immediately with the status given, skipping stack unwinding, `finally`, `atexit` and any flushing of buffered output. That is the right tool in a forked child that must not run the parent's cleanup handlers, and the wrong tool everywhere else — a service that exits this way regularly loses its last, most interesting log lines. ## Putting it together - Write `main()` so that it returns an `int` and does not call `sys.exit` from deep inside helper functions, where an exit is invisible to the reader and untestable. - Call it once, at the bottom of the module, as `sys.exit(main())`. - Let genuinely unexpected exceptions propagate so the traceback reaches the standard error stream and the status is 1; catch the ones you can classify and turn them into a deliberate code. The result is a process whose ending is readable both by a human scanning the log and by whatever started it.