What does a function annotated `-> typing.TypeGuard[list[str]]` return at runtime?

## A predicate is a normal function with a promise attached A *type predicate* is an ordinary Python function that answers a yes/no question about a value: is this list made only of strings, is this decoded payload shaped like a mapping of service names to their dependencies. Written without any typing machinery it is just: ```python def is_str_list(vals): return all(isinstance(v, str) for v in vals) ``` A static type checker cannot learn anything from that. It sees a function returning `bool`, and after `if is_str_list(flags):` the variable `flags` still has whatever type it was declared with. `typing.TypeGuard[list[str]]` as the return annotation is the mechanism for saying: *this boolean is not just a boolean — a True result means the first positional argument is a `list[str]`.* ## What actually happens when you call it Nothing new. The interpreter does not read the annotation, does not verify the returned value, and does not convert anything. `is_str_list(["a"])` evaluates the body and returns `True`; `type(...)` on the result is `bool`. Checkers additionally require every `return` in the body to produce a boolean-compatible value, but that is a static rule, not an interpreter rule — CPython will happily let such a function return a string, and only the checker complains. The annotation object itself does exist: reading `is_str_list.__annotations__["return"]` gives back `typing.TypeGuard[list[str]]`. From Python 3.14 annotations are evaluated lazily (PEP 649), so that subscripted form is not even constructed at `def` time — it is built on first access to `__annotations__`, or fetched in other formats through the `annotationlib` module. That laziness changes when the expression is evaluated; it does not give the annotation any runtime power it did not have before. ## The trust is unconditional, and that is the whole design This is the point interviewers are usually probing. A checker verifies most of your code, but it does **not** verify a predicate body. `TypeGuard` and its 3.13 sibling `TypeIs` are, from the checker's point of view, a `typing.cast` with a nicer face: you assert the conclusion and the tool believes you. ```python from typing import TypeGuard def is_str_list(vals: list[object]) -> TypeGuard[list[str]]: return True # a lie no checker can catch flags: list[object] = [17, 42] if is_str_list(flags): print([name.upper() for name in flags]) # AttributeError at runtime ``` The checker accepts `name.upper()` because it was told the elements are strings. The failure surfaces at runtime, far from the lie, as an `AttributeError`. That is why a predicate body should be short, total, and boring: it is the one place where the type system's guarantees rest entirely on you being right. ## The narrowed parameter is the first positional one The annotation says nothing about *which* argument it describes; the rule is fixed. Checkers narrow the first positional parameter of the predicate, or the first one after `self`/`cls` for a method. Extra parameters may influence the answer but are never narrowed by it, and a predicate declared with no positional parameter at all is rejected — there is nothing for the annotation to be about. ## Why this matters in practice Because the runtime is uninvolved, three habits follow. First, keep the check real: the `isinstance` loop, the length test, the key inspection must actually be there, or the annotation is a lie. Second, test the predicate like any other function, with values that should pass and near-miss values that should fail; unit tests are the only thing standing behind the assertion. Third, remember the cost is real even though the type is not: a predicate that walks a large decoded structure runs that walk on every call, and the checker has no idea how expensive its truth was to establish. ## The version story in one line `typing.TypeGuard` landed in Python 3.10 (PEP 647), `typing.TypeIs` in 3.13 (PEP 742); on 3.9 and older neither exists in the standard library. Python 3.14 changed only when annotations are evaluated (PEP 649), not what they mean — both remain purely static, and both still return a plain `bool` at runtime.