How do you cancel a weakref.finalize callback, run it early, or check if it ran?

## The handle you get back `weakref.finalize(...)` returns a finalizer object. You do not need it for the callback to fire — the module keeps its own registry — but keeping it gives you control over the registration, and that is what turns `weakref.finalize` from a passive safety net into the backbone of a well-behaved resource class. ## Calling it: run the cleanup now The finalizer is callable with no arguments. Calling it: 1. removes the registration, 2. invokes `func(*args, **kwargs)`, 3. returns whatever `func` returned. Every subsequent call is a no-op returning `None`. That combination is precisely the contract of a well-written `close()`: it does the work once, and calling it twice is harmless. You get idempotence for free rather than hand-rolling a `self._closed` flag that someone will eventually forget to set on an error path. ```python import shutil, tempfile, weakref class Workspace: def __init__(self): self.dir = tempfile.mkdtemp() self._finalizer = weakref.finalize(self, shutil.rmtree, self.dir, True) def close(self): self._finalizer() @property def closed(self): return not self._finalizer.alive ``` This class now cleans up three ways: explicitly via `close()`, implicitly when the last reference goes, and as a last resort at interpreter exit — and never twice. ## detach(): cancel it `detach()` unregisters the finalizer *without* running the callback and returns the `(obj, func, args, kwargs)` tuple that was registered. After it, `.alive` is false and nothing will ever fire. Two real uses: * **Ownership transfer.** Your object hands its file descriptor, buffer or temp directory to a caller who now owns closing it. Detaching prevents a double close. * **Reconfiguration.** You detach the current registration, take the tuple it returns, and register a new finalizer with different arguments. If the referent has already been collected, `detach()` returns `None` — there was nothing left to hand back. ## peek(): look without touching `peek()` returns the same `(obj, func, args, kwargs)` tuple but leaves the registration intact, so it is the read-only sibling of `detach()`. Note that it hands back a **strong** reference to the referent for as long as you hold the tuple, which is fine for a debug print and a trap if you stash it somewhere long-lived. It is mostly a diagnostic: "what cleanup is this object still going to do?" ## .alive: is it still pending `.alive` is a read-only boolean property: true while the finalizer is registered, false once it has fired, been called, or been detached. It is the natural implementation of a public `closed` flag, and it is what a test asserts on after dropping a reference and calling `gc.collect()` to prove that the object was actually collectible. ```pycon >>> import weakref >>> class R: pass ... >>> r = R() >>> f = weakref.finalize(r, print, "cleanup") >>> f.alive True >>> f() cleanup >>> f.alive False >>> f() is None True ``` ## The fourth knob: .atexit There is one more attribute, and unlike the others it is writable. `.atexit` defaults to true and controls whether a still-live finalizer is invoked during the interpreter's shutdown pass. Set `f.atexit = False` for cleanup that is meaningless or actively harmful during shutdown — flushing to a service you are about to disconnect from, writing a "clean shutdown" marker, touching a resource the OS reclaims anyway. It is not a constructor argument: `weakref.finalize(obj, func, atexit=False)` would forward `atexit=False` to `func` as a keyword argument, because everything after `func` belongs to the callback. Set it on the returned object. ## Putting it together A resource class that owns something releasable should keep its finalizer private, expose `close()` as calling it, expose a `closed` property from `.alive`, implement `__enter__`/`__exit__` so callers can scope it in a `with` block, and use `detach()` on the one path where ownership leaves. That covers deterministic release, safe double release, and an eventual backstop, with no bookkeeping flags of its own.