Dict Dispatch Tables

## The two things that make a dispatch table work A dict dispatch table rests on two ordinary Python facts, and the `handler` vs `handler()` question is really asking whether you know both. The first is that **functions are first-class objects**. A `def` statement does two things: it builds a function object and it binds that object to a name. The name is not special — you can pass it to another function, put it in a list, return it, or store it as a dict value. `start` is a reference to the object; `start()` is an expression that *invokes* the object and evaluates to whatever it returned. The second is that **a dict display evaluates eagerly**. `{"a": f(), "b": g()}` is not a lazy description of a mapping. It is an expression that is evaluated left to right, right now: `f()` runs, `g()` runs, and the resulting values are stored. Python has no implicit thunking; nothing about being a dict value defers anything. So the buggy table calls every handler at construction time — which is exactly the moment you were trying to avoid calling them — and stores their return values. ## What the bug looks like in practice ```python handlers = {"start": start(), "stop": stop()} # both already ran handlers["start"]() # TypeError: 'NoneType' object is not callable ``` Because most handler functions return `None`, the usual symptom is `TypeError: 'NoneType' object is not callable` at the first dispatch, plus side effects that fired far too early. If the handlers happen to return something callable the failure is subtler still. The fix is to remove the parentheses at build time and add them at call time: ```python handlers = {"start": start, "stop": stop} handlers["start"]() ``` ## Handlers that need arguments The uncalled-callable rule is why `functools.partial` shows up so often next to dispatch tables. If several keys should run the same function with different pre-bound arguments, `partial(write, "warehouse.orders")` produces a new callable with that argument already applied, without invoking `write`. A `lambda` does the same thing, with one classic trap: a lambda closes over the *name*, not the value, so building handlers in a `for` loop with `lambda: work(name)` makes every entry see the loop variable's final value. Bind it explicitly (`lambda name=name: work(name)`) or use `partial`, which captures the value at creation. ## Where and when the table is built Since the values are just references, constructing the dict is cheap — a few dict inserts — but it is not free, and it is not something to redo on every call. A table built inside the dispatch function is rebuilt on each invocation; a table built at module level is built once at import. Module level is the normal choice, with one ordering constraint: every name you reference must already be bound when the module body reaches that line, so the table goes *below* the handler definitions. If a handler must live above the table for readability, or the set of handlers is discovered dynamically, build the dict in a small factory function and call it once. A module-level dict is also mutable global state: any importer can add or replace an entry. That is sometimes the point — it is how plugin registration is often done — but when it is not, wrapping the table in `types.MappingProxyType` gives a read-only view that raises on mutation. ## Signature discipline The table is only useful if every value can be called the same way, because the call site knows the key, not which function it found. Decide on one signature — all handlers take the record, or all take no arguments and read from a closure — and use `partial` to reshape any handler that does not fit. Handlers whose signatures diverge push the branching back into the call site, which defeats the table. ## What the table does and does not buy you The lookup itself is a hash lookup, so it does not scan the entries the way a chain of comparisons would. That is a real property, but it is rarely the reason to write one — with a handful of keys the difference is noise. The reason is structural: the mapping from key to behaviour becomes data you can inspect, iterate, extend and test, and the handlers become independently testable functions. And the lookup being fast says nothing about the handlers: dispatch cost is a hash and a call, and everything expensive is inside the function you just found.