SIGTERM and Graceful Shutdown

## Dispositions, not handlers Every Unix process carries a **disposition** for each signal number: what the kernel should do when that signal is delivered. The three possibilities are *default* (`signal.SIG_DFL` — the action baked into the kernel for that signal, which for the terminate family is "destroy the process"), *ignore* (`signal.SIG_IGN`), or *handle* (run a function). A Python process starts life with the dispositions it inherited from its parent, with one interesting exception that CPython itself adds. ## What CPython adds at startup CPython installs exactly one Python-level signal handler of its own during interpreter startup: a handler for `signal.SIGINT`, exposed as `signal.default_int_handler`. All that function does is `raise KeyboardInterrupt`. You can see the asymmetry directly: ```python import signal signal.getsignal(signal.SIGINT) is signal.default_int_handler # True signal.getsignal(signal.SIGTERM) is signal.SIG_DFL # True ``` `signal.SIGTERM` was never touched, so it still carries the kernel default: terminate the process. ## Why the difference matters so much A Python signal handler does not run inside the kernel's delivery context. The C-level handler only records that the signal arrived and sets a flag; the eval loop notices the flag at the next bytecode boundary in the **main thread** and calls your Python function there. For `signal.SIGINT`, that function raises `KeyboardInterrupt`, and from that instant on it is an ordinary exception travelling up an ordinary stack. It runs `finally` blocks. It runs `__exit__` on every context manager it passes. If nothing catches it, the interpreter shuts down normally, which flushes buffered writes and runs everything registered with `atexit.register`. `signal.SIGTERM` at its default disposition never reaches the eval loop at all. The kernel destroys the process image. Nothing in your program observes it happening, which is exactly why the failure is so easy to miss in development, where you stop things with Ctrl-C. ## Ctrl-C is not SIGTERM Pressing Ctrl-C does not send a signal from Python or from the shell — the terminal line discipline sends `signal.SIGINT` to the entire foreground process group. A supervisor stopping a service, by contrast, sends `signal.SIGTERM` to the process (often followed later by `signal.SIGKILL`). They mean roughly the same thing socially — "please stop" — and behave completely differently technically. Testing shutdown with Ctrl-C therefore proves almost nothing about how the program behaves in production. ## KeyboardInterrupt is a BaseException `KeyboardInterrupt` deliberately does **not** inherit from `Exception`; it inherits from `BaseException`, alongside `SystemExit` and `GeneratorExit`. That means a broad `except Exception:` around a worker loop will *not* swallow a Ctrl-C, which is the intended design: an interrupt should not be mistaken for an application error and retried. It also means that code which writes `except BaseException:` or a bare `except:` will swallow interrupts and make the program feel unkillable. Because the exception is raised at an arbitrary bytecode boundary, it can land anywhere — including between acquiring a resource and entering the `try` that would release it. This is the reason to keep the window narrow by acquiring resources with `with` rather than by hand. ## Exit status A process killed by a signal does not have a normal exit code. On POSIX, `subprocess.Popen.wait()` returns the negated signal number (`-15` for `signal.SIGTERM`, `-9` for `signal.SIGKILL`), and shells report `128 + signum` (143 and 137). By convention a program that handles a terminate signal and exits deliberately can mirror that with `SystemExit(128 + signum)`, which keeps dashboards that count 143s honest. ## Making SIGTERM behave The whole fix is one registration, done once, in the main thread: ```python import signal def _on_terminate(signum, frame): raise SystemExit(128 + signum) signal.signal(signal.SIGTERM, _on_terminate) ``` Now `signal.SIGTERM` unwinds the stack exactly like Ctrl-C does: `finally` blocks run, `atexit` hooks run, buffers flush. Raising `SystemExit` from the handler is the simplest correct shape for a short-lived script. A long-running worker usually prefers a handler that sets a flag — an interrupt that lands in the middle of a network write is not a clean place to unwind from — and lets the main loop notice the flag and shut down at a safe point. ## The one signal you cannot do this for `signal.SIGKILL` (and `signal.SIGSTOP`) cannot be caught, handled or ignored. Calling `signal.signal` on them raises `OSError`. That is the whole point of the supervisor's two-stage stop: a catchable request first, an uncatchable one when the grace period expires.