How does weakref.finalize improve on __del__ for releasing an external resource?

### The shape of the API ```python import weakref class Cache: def __init__(self, name): self.name = name def flush(name): print("flushed", name) c = Cache("pages") fin = weakref.finalize(c, flush, c.name) ``` `weakref.finalize(obj, func, *args, **kwargs)` says: *when `obj` is collected, call `func(*args, **kwargs)` — once*. The call returns a finalizer object with a small, well-chosen surface: * **`alive`** — `True` while the callback is still pending. * **calling the finalizer** — `fin()` runs the callback immediately, returns its result, and marks the finalizer dead so it will not fire again. * **`detach()`** — cancels it, returning the original `(obj, func, args, kwargs)` if it was still alive. * **`peek()`** — inspects the same tuple without cancelling. * **`atexit`** — a flag, true by default, meaning a still-pending finalizer is also run at normal interpreter shutdown. The finalizer object is registered in a module-level table, so it stays alive even if you drop your reference to it. You get a handle if you want one and lose nothing if you throw it away. ### Why it beats a finalizer method **It is external.** `__del__` is part of the class, so it is inherited, overridable, and easy to break: a subclass that defines its own `__del__` without calling the parent's silently loses the cleanup. A finalizer registered from the constructor — or, better, from the factory that acquires the resource — belongs to the acquisition site instead of the type hierarchy. **It is off the deallocation path.** An object with `__del__` carries a finalizer slot for its whole life and is torn down through it. A `weakref.finalize` callback is invoked by the weak-reference machinery instead, which keeps the object's own teardown ordinary. **It runs at most once, by construction.** No resurrection subtleties to reason about: once fired or detached, the finalizer is dead. **It is callable early and cancellable.** This is the feature that makes the pattern work in real code. The explicit `close()` calls the finalizer, which performs the release and marks it dead; the automatic path is then a genuine backstop rather than a competing owner. ```python class Session: def __init__(self, handle): self._handle = handle self._finalizer = weakref.finalize(self, self._release, handle) @staticmethod def _release(handle): handle.close() def close(self): self._finalizer() @property def closed(self): return not self._finalizer.alive ``` Note carefully what `_release` receives: the raw handle, not `self`. That is the discipline the API demands. ### The trap: never capture the object If `func` or any argument holds a strong reference to `obj`, the registry keeps that reference alive, `obj` is never collected, and the finalizer never fires. This is why `_release` above is a `staticmethod` taking the handle — a bound method `self._release` would capture `self` and pin the session forever. Pass the resource, never the owner. ### Shutdown behaviour With `atexit` left at its default, still-pending finalizers run during normal interpreter shutdown, in reverse order of creation — the same last-in-first-out reasoning `atexit` handlers use. That gives one registration point covering both "the object was dropped mid-run" and "the process is ending with the object still live", which is precisely the pair that `__del__` handles unreliably and an `atexit` handler alone does not handle at all. Setting `atexit` to false opts out, for cleanup that only makes sense while the program is genuinely still running. The usual caveat survives: shutdown-time finalizers are still only reached on a *normal* exit. `os._exit`, an unhandled terminating signal or a fatal error skip them exactly as they skip everything else, so `weakref.finalize` improves reliability against programmer error, not against process death. ### How it compares with the other exit hooks A handler registered with `atexit.register` is bound to the *process*: it runs once at normal shutdown, whether or not the object it cares about is still relevant, and it holds whatever it captures alive for the whole run. A `__del__` method is bound to the *type*: it runs on every instance, on the deallocation path, and cannot be cancelled. `weakref.finalize` is bound to the *instance*, from the outside, and covers both endings — the object being collected mid-run and the process ending with the object still live. That is why it is the hook to reach for when the thing being released belongs to one object rather than to the program as a whole. ### When to reach for it Use it for a non-memory resource with a real release step — a temporary directory, an OS handle, a native allocation from an extension module, a registration in some external table — where you want an explicit close, a guarantee against double-release, and a net for callers who forget. Do not use it as a general memory-management tool: ordinary objects need no finalizer at all.