How does `typing.TYPE_CHECKING` break an import cycle caused only by type annotations?

### The pattern ```python from typing import TYPE_CHECKING if TYPE_CHECKING: from planner import Route # never executed at run time def cost(route: Route) -> float: return route.distance * 1.4 ``` `typing.TYPE_CHECKING` is defined as `False` in the standard library. Type checkers special-case it and analyse the block as if it were `True`. So the checker sees the import and can resolve `Route`; the interpreter skips the block, `planner` is never imported here, and a cycle that existed only because of that annotation disappears. ### Why it works on 3.14 without quoting Before 3.14, annotations were ordinary expressions evaluated when the `def` or `class` statement executed. An unquoted `Route` that had never been imported at run time therefore raised `NameError` immediately, and the pattern required either a string annotation (`"Route"`) or a module-level `from __future__ import annotations` (PEP 563, available since 3.7), which turned all annotations into strings. Python 3.14 implements PEP 649/749: the compiler stores annotations in a separate `__annotate__` function and `__annotations__` is computed on first access. The name is not looked up when the function is defined, so the guarded pattern now works with plain, unquoted annotations. `from __future__ import annotations` still exists and still works on 3.14, but is no longer needed for this. ### The failure this pattern hands you The name is genuinely absent at run time, and anything that asks for annotation **values** will say so: ```python typing.get_type_hints(cost) # NameError: name 'Route' is not defined cost.__annotations__ # NameError, for the same reason ``` This is not a bug in the pattern; it is the pattern. Reach for the guard only when the import exists *solely* to satisfy the type checker. If the class is needed at run time — an `isinstance` check, a default value, a call to the constructor, a registry lookup — the guard is a lie and you must fix the dependency direction or defer the import into the function instead. ### Getting the annotations back without resolving them When a tool needs to inspect annotations of code that uses the guard, 3.14's `annotationlib` gives it formats that do not require the names to exist. `annotationlib.get_annotations(cost, format=annotationlib.Format.STRING)` returns `{'route': 'Route', 'return': 'float'}` — text, no lookup. `annotationlib.Format.FORWARDREF` returns unresolvable names as forward-reference objects rather than raising. Introspection libraries that build things from annotations at class-creation time are expected to move to those formats; on 3.14 a `dataclass` field whose annotation names a guard-only symbol already builds successfully for exactly this reason. ### Practical notes * Only the *import* goes inside the guard. The annotation stays where it is. * Because the block never runs, mistakes inside it are invisible until a checker runs. An import there that is wrong, or that stays behind after the annotation is deleted, will not fail any test. * String annotations remain valid and remain necessary if you must support 3.13 or earlier, where the guard alone is not enough. * The guard removes the *run-time* edge only. Your import graph still has the edge as far as a reader and a type checker are concerned, so if the cycle reflects genuinely tangled responsibilities, the guard silences the symptom rather than curing it. Extracting the shared type into a module both sides import is still the better answer when the type is shared, and where those boundaries belong is a design question in its own right. ### What to say in an interview Name the three things: `TYPE_CHECKING` is `False` at run time and `True` to the checker; on 3.14 annotations are lazily evaluated so unquoted names work, whereas 3.13 and earlier needed a string or the future import; and anything that resolves annotations at run time will raise `NameError`, which is the deliberate cost of the trick.