How do you write Python annotations that reference a class in a module you cannot import at runtime?

## The situation Split a subscription-billing system into modules and this appears within a day. `invoices.py` has a function that takes a `Ledger`; `ledger.py` has a method that returns an `Invoice`. Each module needs the other's class *only to name it in an annotation*, and importing both ways is a circular import. Nothing here is a real runtime dependency — no code in either module calls into the other at import time — so paying for a genuine restructuring would be overkill. ## The mechanism `typing.TYPE_CHECKING` is a module-level constant whose runtime value is `False`. Type checkers special-case it: when they analyse your source they behave as though it were `True`. So a block guarded by it is fully visible to the checker and completely absent from the running program. ```python from typing import TYPE_CHECKING if TYPE_CHECKING: from decimal import Decimal def prorate(amount: "Decimal", days: int) -> "Decimal": return amount prorate.__annotations__ # {'amount': 'Decimal', 'days': <class 'int'>, 'return': 'Decimal'} ``` The checker sees a real import and validates every use of the class. The interpreter sees a `False` branch, imports nothing, and stores the annotation as a string it never tries to interpret. ## Why the annotation is quoted Because the name truly is not bound at runtime, and a quoted annotation is never looked up at all. On **Python 3.14** an unquoted annotation would survive the definition, since annotations are no longer evaluated when the `def` executes — but the failure has only moved: ```python from typing import TYPE_CHECKING if TYPE_CHECKING: from decimal import Decimal def prorate(amount: Decimal) -> Decimal: return amount prorate(1) # fine — calling never touches annotations prorate.__annotations__ # NameError: name 'Decimal' is not defined ``` On 3.13 and earlier the same code raises at import time. Either way, quoting is what keeps the annotation inert, which is exactly what you want for a name that will never exist. ## The trade-off a senior is expected to name This pattern makes the annotation unresolvable at runtime *on purpose*, and that is a real cost, not a free win. Any consumer that walks `__annotations__` — a decorator that builds a constructor from a class's fields, a serializer, a validation layer that turns annotations into checks, or a framework that inspects a callable's parameters — will look for `Decimal` in that module's namespace and not find it. The failure is late and confusing: the module imports fine, the code runs fine, and then something reads the annotations and raises `NameError`. In a six-hour nightly billing run, the natural place for that to surface is at hour five, in the one code path that finally introspected the model. So the decision rule is: - **Annotation-only dependency, no runtime introspection** → `TYPE_CHECKING` guard plus a quoted annotation. Cheap, standard, zero import cost. - **Something resolves these annotations at runtime** → you need a real import. Then break the cycle structurally: move the shared type (a `Money` or a `LineItem`) into a third module that both sides import, or invert the direction so only one module knows about the other. ## Related honesty The guard fixes an *annotation-only* cycle. It does nothing for a genuine one where module A calls a function in module B at import time and B does the same to A — for that, deferring the import into the function body, or extracting the shared code, is the fix. Candidates who reach for `TYPE_CHECKING` as a general circular-import cure are treating a symptom, and it is worth saying which of the two problems you actually have before you pick the tool. ## Cost and hygiene The guarded import is free at runtime, which is a small side benefit: a heavy module used only for typing is never imported by production processes. The price is that the module's annotations no longer stand on their own, so any team convention that lets code introspect annotations must be stated alongside this pattern rather than discovered by an exception.