get_type_hints Resolution

## The shape of the bug A webhook receiver registers handler functions and, at startup, walks the registry calling `typing.get_type_hints` on each one so it can build a payload decoder from each handler's parameter type. Most handlers resolve. One raises `NameError: name 'PaymentEvent' is not defined`, and the module it points at imports `PaymentEvent` perfectly clearly — inside an `if TYPE_CHECKING:` block. `typing.TYPE_CHECKING` is a plain module constant that is `False` when Python runs and that type checkers special-case to `True`. Everything under that guard is, at runtime, dead code. The annotation that names the guarded import is therefore a name with no binding in the module's globals, and since `get_type_hints` evaluates annotations against exactly those globals, resolution fails. The reason this reaches production is that every static signal is green: the checker sees the import and type-checks the handler correctly, code review sees an import statement, and the module imports without error because nothing evaluated the annotation. Only a runtime consumer of the hints triggers it — which on 3.14 can be a bare `__annotations__` access too, since PEP 649 evaluates annotations lazily rather than at `def` time. ## Diagnosing it quickly The traceback names the unresolved symbol; grep for it in the defining module and you will find it under the guard, or defined later in a file where the annotation was quoted. Confirm by checking whether the name is reachable from the defining module at runtime — not from the module doing the resolving, which is the most common wrong turn. Resolution follows the function's own `__globals__`; a name your framework can see is irrelevant unless you pass it in. ## The four honest fixes **Import it for real.** If the module is cheap and there is no cycle, the guard was premature optimization. Delete it. This is the right answer far more often than people expect, and it makes every downstream consumer work without special knowledge. **Supply the namespace at the call site.** `get_type_hints(handler, localns={"PaymentEvent": PaymentEvent})` resolves the name for that call without changing the module's import graph. `globalns` replaces the module globals wholesale, which is blunter; `localns` layers a few names on top and is what you usually want. This is the standard escape hatch when the guard exists to break a genuine import cycle. **Move the type.** If the guard exists because two modules import each other, the type usually belongs in a third module that neither one depends on. That fixes the cycle rather than routing around it, and it removes the guard as a side effect. **Do not force resolution.** If the consumer only needs to render the annotation — a log line, an error message, documentation — the unresolved text is fine and asking for objects buys you a failure you do not need. On 3.14 `annotationlib.get_annotations` exposes formats that return placeholder forward references instead of raising, and a string form, for exactly this class of consumer. What is not a fix: wrapping the call in `try/except NameError` and moving on with raw strings. A decoder built from a hint that silently failed to resolve is a decoder that does nothing, and the request that needed it fails much further away from the cause. ## Where the fix belongs A framework that requires runtime-resolvable annotations should say so and fail loudly at registration, listing the handler and the unresolved name, rather than at first request. Startup is the cheapest place to discover this: every handler is present, no traffic is in flight, and a failed boot is a clear signal. The same walk that resolves the hints is the natural place to validate them. It is also worth deciding once, per codebase, whether `TYPE_CHECKING` guards are allowed on types that appear in annotations that something resolves at runtime. Guards are legitimate — for genuine cycles and genuinely expensive imports — but they impose a contract on every runtime consumer of those annotations, and that contract is invisible at the point where someone adds the guard. ## Caching and concurrency One related trap: because resolution is not cached, teams often memoize the resolved hints in a dict shared by worker threads and fill it lazily on first use. The dict itself is not the problem; the check-then-act pattern around it is, so two workers can resolve the same handler concurrently and a reader can observe a half-populated mapping built key by key. Resolving everything at registration, before workers start, removes the race and the latency spike at once.