What problem does `typing.TypeGuard` solve that a plain `isinstance` check cannot?

## Where the built-in check stops `isinstance(x, C)` asks a single question: is this object an instance of that class (or of a subclass, or of something registered with that abstract base class). It is a runtime check about a runtime class, and Python's generic parameters are not runtime data. `list[str]` and `list[int]` are the same class at runtime — `list` — with the parameter living only in the annotation. The language is explicit about it rather than silently wrong: ```python >>> isinstance(["dark-mode"], list[str]) TypeError: isinstance() argument 2 cannot be a parameterized generic ``` So if a function is handed a `list[object]` decoded from a configuration payload and needs a `list[str]` for the rest of the body, no built-in check can get it there. A type checker cannot bridge the gap either, and this is the part candidates usually miss: even after you have proved every element is a `str`, `list[str]` is not assignable to `list[object]`, because `list` is *invariant* — a `list[str]` cannot stand in for a `list[object]`, since something holding the wider type would be entitled to append an `int` to it. The narrowing you want is not a subtype relationship at all. ## What TypeGuard adds `typing.TypeGuard[T]` (Python 3.10, PEP 647) lets a function you wrote perform an arbitrary check and then tell the checker the conclusion: ```python from typing import TypeGuard def is_str_list(vals: list[object]) -> TypeGuard[list[str]]: return all(isinstance(v, str) for v in vals) ``` Inside `if is_str_list(flags):` the checker treats `flags` as `list[str]`, so `str.join`, `.upper()` on the elements and anything else `str`-shaped type-checks. `TypeGuard` deliberately imposes **no** relationship between the parameter type and the narrowed type, which is exactly what the invariant-container case needs. Its two-way sibling `typing.TypeIs` (3.13, PEP 742) *does* require the narrowed type to be assignable to the declared parameter type, so `TypeIs[list[str]]` on a `list[object]` parameter is rejected — the invariance that motivated the whole exercise blocks it. ## The other conclusions isinstance cannot express Parameterized containers are the headline case, but the same limit shows up wherever the interesting property is not a class: * A decoded `dict[str, object]` that matches a `TypedDict` shape: the required keys are present with the right value types. A `TypedDict` has no runtime class of its own to test. * A tuple of exactly three elements, so it can be treated as a fixed-length structure. * A `str` that matched a validation pattern and can therefore be treated as a distinct alias for identifiers. * A union member selected by a discriminator field rather than by class, common with payloads that carry a kind or event field. In every one of these, the check itself is easy to write in ordinary Python; what was missing was a way to communicate its result to the checker. ## When you do not need it A predicate is not an improvement over an inline check that the checker already understands. `if isinstance(x, str):` narrows perfectly well on its own, and so do `x is None`, `assert isinstance(...)`, an early return, and `type(x) is C`. Wrapping any of those in a one-line predicate adds a function call, a name, and an unverified assertion in exchange for nothing. Reach for a predicate when the test is non-trivial, when it is repeated across modules, or when the conclusion cannot be spelled as a class. ## The cost you are accepting The checker does not verify the loop inside the predicate. It sees the signature and believes it. That makes a predicate the same category of construct as `typing.cast`: a place where you, not the tool, are responsible for soundness. Two practical consequences follow. Keep the body total — every path that could be false must actually return False, including the empty-container case, whose truth is usually vacuous and usually correct. And remember it is real work: `all(isinstance(v, str) for v in vals)` is O(n) on every call, so run it once at the decoding boundary and pass the narrowed value inward rather than re-asking in a loop. ## Version notes `typing.TypeGuard` requires Python 3.10 or newer; `typing.TypeIs` requires 3.13 or newer. The `isinstance` restriction on parameterized generics is not new and has not changed in 3.14 — it is a consequence of parameters being erased at runtime, not a temporary limitation.