title: kuit description: Graceful shutdown and file-change detection for Python

[ref: #kuit]

kuit

kuit is a tiny Python library for graceful process shutdown and development-time auto-restart.

It gives you three public entry points:

• zx.quit.and_call — register callbacks that run when the process exits.
• zx.quit.and_intercept — append custom handlers to the uncaught-exception chain.
• zx.quit.on — detect file changes or incoming signals and exit cleanly.

[ref: #installation]

Installation

Install with uv:

uv add kuit

Or with any PEP 517-compatible tool:

pip install kuit

[ref: #and-call]

Registering shutdown callbacks with zx.quit.and_call

Use zx.quit.and_call as a decorator or as a plain function call. The callback runs exactly once on SIGINT, SIGTERM, SIGQUIT, or an unhandled exception.

import zx.quit


@zx.quit.and_call
def close_db():
    print("closing database connection")


@zx.quit.and_call
def flush_logs():
    print("flushing logs")

Callbacks are executed in registration order. Exceptions raised by one callback are logged and do not stop the next callback from running.

[ref: #and-intercept]

Adding exception hooks with zx.quit.and_intercept

zx.quit.and_intercept lets you insert a custom function into the chain that runs before the original sys.excepthook.

import zx.quit


def notify_sentry(exc_type, exc_value, traceback):
    print(f"reporting {exc_type.__name__}: {exc_value}")


zx.quit.and_intercept(notify_sentry)

[ref: #on]

Detecting file changes and signals with zx.quit.on

zx.quit.on builds a callable that returns True while the application should keep running and False when it should exit. By default it watches the mtime of sys.argv[0]; if the file changes, it calls func(errno) and returns False.

import signal
import zx.quit


checker = zx.quit.on(signal=signal.SIGUSR1)

while checker.sleep(60):
    pass  # main loop work

checker() performs a single check immediately. checker.sleep(wait, poll=...) blocks for up to wait seconds, polling every poll seconds, and returns as soon as a change is detected or the deadline is reached.

[ref: #on-options]

zx.quit.on options

All arguments are keyword-only.

[ref: #full-example]

Full example

import signal
import zx.quit


@zx.quit.and_call
def cleanup():
    print("shutting down")


def log_uncaught(exc_type, exc_value, traceback):
    print(f"uncaught {exc_type.__name__}: {exc_value}")


zx.quit.and_intercept(log_uncaught)


checker = zx.quit.on(
    signal=signal.SIGUSR1,
    errno=137,
    poll=2.5,
)

while checker.sleep(60):
    pass