What does atexit.register guarantee about when and in what order your callback runs?

### What the module actually is `atexit` is a very small standard-library module whose entire job is to hold a list of callables that CPython invokes while it is finalizing the interpreter. `atexit.register(func, *args, **kwargs)` appends an entry — the function plus the positional and keyword arguments it should be called with — and returns `func` unchanged, which is why it reads naturally as a decorator: ```python import atexit @atexit.register def write_checkpoint(): ... ``` `atexit.unregister(func)` removes *every* entry whose callable is `func`; registering the same function three times and unregistering once removes all three, and unregistering something that was never registered is silently fine. ### The order: last in, first out Handlers run in reverse order of registration. The reasoning is the same as for a stack of nested resources: whatever was set up last usually depends on what was set up first, so it must be torn down first. In practice registration order tends to follow import order, so a late-imported subsystem's flush runs before the logging shutdown that it wants to log through. ```python import atexit atexit.register(print, "runs second") atexit.register(print, "runs first") ``` That ordering is a real guarantee, not an implementation accident, and interviewers ask about it because the naive answer — "in the order I registered them" — is the wrong half of a coin flip. ### The much weaker guarantee: only *normal* termination The module's own docstring says it plainly: the functions run "upon normal program termination". Normal means the main module finishes, or `sys.exit` unwinds the stack in the usual way. Every abnormal ending bypasses the list entirely: * **`os._exit(status)`** calls the C `_exit` directly. The process disappears without unwinding, without flushing buffered stdio, and without running a single handler. That is not a bug — it is exactly why `os._exit` exists, for instance in a forked child that has inherited the parent's handler list and must not run the parent's cleanups a second time. * **A signal with no Python-level handler.** A default SIGTERM or SIGHUP terminates the process at the OS level. Only SIGINT has a default Python handler (it raises `KeyboardInterrupt`, which unwinds normally and therefore *does* reach the handlers). * **SIGKILL**, which cannot be caught by anything, ever. * **A fatal interpreter error** — a segmentation fault in a C extension, an unrecoverable memory error, or `Py_FatalError`. The practical consequence is a design rule rather than a trivia point: an `atexit` handler is a *best-effort* convenience, never a durability mechanism. State that must survive the process must be written as it is produced, or written to a place that can be repaired on the next start. If losing what the handler would have written is unacceptable, the handler is the wrong tool. ### What happens when a handler itself fails On CPython 3.14, an exception raised inside a handler is routed to `sys.unraisablehook`. The default hook prints a traceback tagged as an ignored exception in an atexit callback; the remaining handlers still run; and the exit status of the process is unaffected. So a handler cannot be used to turn a successful run into a failed one — if the caller must learn that shutdown work failed, the code has to detect and report the failure before shutdown, or write a marker the next start can read. ### Where handlers sit relative to object finalization Handlers run early in interpreter finalization, before the bulk of module and object teardown. An object whose `__del__` would also print something will typically be finalized *after* the handlers, not before — so a handler that reaches for a resource "the object will close later" still sees it open, while an object finalizer that reaches for something a handler already tore down sees the wreckage. ### Practical shape of a good handler Keep it short, keep it non-blocking, and make it idempotent. A handler that waits on a work queue or joins on something still in flight turns a clean shutdown into a hang, and the operator's response to a hang is a signal that skips the handler completely. Anything long-running belongs in an explicit shutdown call the program makes on its own terms; `atexit` is the safety net for the paths that forgot to make it.