What does weakref.finalize(obj, func) register, and when does func run?

## The signature `weakref.finalize(obj, func, /, *args, **kwargs)` is a class in the standard library's `weakref` module. Constructing an instance *registers* a cleanup action: "when `obj` dies, call `func(*args, **kwargs)`". The constructor returns a finalizer object, which is itself callable. `obj` and `func` are positional-only, so every remaining positional and keyword argument is forwarded to `func` — there is no way to pass options to the finalizer through the constructor. ## How it detects death Under the hood the finalizer creates a weak reference to `obj` whose callback is the finalizer itself. A weak reference is one that does **not** count toward keeping an object alive: the reference-counting collector ignores it, and when the last strong reference goes away the object is destroyed and the weak reference's callback fires. That is the whole guarantee — `weakref.finalize` observes the object's death without participating in its lifetime. Crucially, the callback never receives `obj`. Your `func` only sees the arguments you supplied at registration time. That is deliberate: by the time the callback runs, the object is being torn down, and handing it back would allow *resurrection*. ## Where the finalizer lives Live finalizers are kept in a private module-level registry, keyed by the finalizer object. Two consequences follow, and both surprise people: 1. **You do not have to keep the returned object.** `weakref.finalize(obj, func)` on a bare line still works. This is the opposite of `weakref.ref(obj, callback)`, where dropping the reference object means the callback never fires. 2. **It works for objects trapped in reference cycles.** The cyclic garbage collector skips callbacks for weak references that are themselves part of the garbage being collected, to avoid running arbitrary code on half-destroyed data. Because the finalizer is reachable from the module registry rather than from the doomed object, it is never part of that garbage, so its callback still runs. ## At most once, and what it returns A finalizer fires exactly once. Calling the finalizer object yourself runs the callback immediately and returns `func`'s return value; every later call returns `None` and does nothing. This is what makes it a convenient basis for an idempotent `close()`. ## The exit pass Every finalizer that is still alive when the interpreter shuts down is called during exit, in **reverse order of creation** — newest first, on the assumption that later objects may depend on earlier ones. The `weakref` module arranges this by registering one hook with the `atexit` machinery the first time any finalizer is created. Exceptions raised by an exit-time callback are reported through `sys.excepthook` and do not stop the remaining finalizers or change the exit status. This exit pass is a courtesy, not a contract. It does not run if the process is killed with SIGKILL, if it calls `os._exit`, or if the interpreter dies from a fatal error. Never rely on it for anything whose absence corrupts state. ## Requirements and limits The referent must support weak references. Instances of ordinary classes do; built-in `list`, `dict`, `tuple`, `str` and `int` objects do not, and neither does an instance of a class that defines `__slots__` without including `__weakref__`. Registering one raises `TypeError: cannot create weak reference to 'list' object`. ```python import gc, weakref class Session: pass s = Session() f = weakref.finalize(s, print, "session cleaned up") print(f.alive) # True del s gc.collect() print(f.alive) # False - the callback already ran ``` ## Where it fits A `with` block is still the right tool whenever the resource's lifetime matches a block of code: it is deterministic, it runs on the exception path, and a reader can see the scope. `weakref.finalize` is for the cases where that shape does not exist — an object handed out by a factory, a cache entry, a handle stored on a long-lived object — where the only honest answer to "when should this be released?" is "when nobody is using the object any more". Treat it as a backstop that turns a silent leak into an eventual cleanup, not as a destructor you can schedule.