In statically typed Python projects, code often starts with broad values and must prove that they belong to a more specific type. Built-in isinstance() checks cover many cases, but custom helper functions do not always narrow types automatically. typing.TypeGuard lets a Boolean function declare that it is a type predicate: when the function returns True, the checker treats the argument as the indicated type.
This guide explains how to write safe TypeGuards, validate lists, dictionaries, and objects, combine narrowing with Protocol, TypedDict, and Literal, avoid dishonest predicates, and decide when a regular isinstance() check is enough.
Why a Boolean helper may not narrow
from typing import Any
def is_string_list(value: list[Any]) -> bool:
return all(isinstance(item, str) for item in value)
data: list[object] = ["a", "b"]
if is_string_list(data):
first = data[0]
# a checker may still see objectThe function is correct at runtime, but its signature communicates only that it receives a list and returns a Boolean. It does not describe the relationship between the successful result and the argument type.
Declaring a TypeGuard
from typing import TypeGuard
def is_string_list(value: list[object]) -> TypeGuard[list[str]]:
return all(isinstance(item, str) for item in value)
if is_string_list(data):
print(data[0].upper())Inside the true branch, data is treated as list[str]. At runtime, the function still returns only True or False; TypeGuard affects static analysis.
A TypeGuard is a trusted promise
The checker does not execute your predicate to verify its logic. It trusts the return annotation. A faulty implementation can therefore make unsafe operations appear valid.
def is_integer(value: object) -> TypeGuard[int]:
return True # incorrectAfter this call succeeds, the checker permits integer operations even if the value is a string, list, or unrelated object. Treat TypeGuard as a trust boundary and test every predicate carefully.
Narrowing a union
from dataclasses import dataclass
from typing import TypeGuard
@dataclass
class Success:
value: str
@dataclass
class Failure:
error: str
Result = Success | Failure
def is_success(result: Result) -> TypeGuard[Success]:
return isinstance(result, Success)
def process(result: Result) -> None:
if is_success(result):
print(result.value)
else:
print(result.error)This pattern gives the caller an expressive domain-level predicate and keeps the identification rule in one place.
Validating a TypedDict
JSON and API data commonly arrive as dict[str, object]. A TypeGuard can validate the shape before typed key access is allowed.
from typing import TypedDict, TypeGuard
class User(TypedDict):
id: int
name: str
active: bool
def is_user(value: object) -> TypeGuard[User]:
if not isinstance(value, dict):
return False
return (
isinstance(value.get("id"), int)
and isinstance(value.get("name"), str)
and isinstance(value.get("active"), bool)
)The predicate must validate every required key and its value type. Checking only one key is not enough when the annotation promises the complete structure.
Optional fields and extra keys
For a TypedDict with optional fields, validate required keys and verify optional fields whenever they are present. Extra keys can be accepted or rejected according to the application contract. Document that policy because the static type alone does not express every runtime validation rule.
TypeGuard with Protocol
A Protocol describes structural behavior. A TypeGuard can identify objects that expose selected attributes or methods.
from typing import Protocol, TypeGuard
class Savable(Protocol):
def save(self) -> None: ...
def is_savable(value: object) -> TypeGuard[Savable]:
return callable(getattr(value, "save", None))This check proves only that a callable attribute named save exists. It does not fully inspect the method signature. For critical contracts, use explicit validation, abstract base classes, or stronger tests.
Homogeneous sequences
from collections.abc import Sequence
def is_integer_sequence(
values: Sequence[object],
) -> TypeGuard[Sequence[int]]:
return all(isinstance(value, int) for value in values)Read-only interfaces such as Sequence reduce mutation risks. Narrowing a mutable list can be dangerous if another reference inserts an incompatible item after validation.
Mutation and invariance
list is invariant. A list[str] is not freely substitutable for list[object] when writes are possible, because the broader reference could insert an integer. TypeGuard can express narrowing relationships that normal subtyping would reject, so the implementation and later code must preserve the container’s invariant.
When a predicate only reads values, accepting Sequence[object] is often safer. When code mutates a narrowed collection, ensure that no uncontrolled alias can add invalid values.
Filtering collections
def is_string(value: object) -> TypeGuard[str]:
return isinstance(value, str)
items: list[object] = ["a", 1, "b"]
texts = [item for item in items if is_string(item)]Modern checkers can infer list[str] for this comprehension. Results for higher-order APIs such as filter() may depend on the checker and available type stubs.
Combining TypeGuard and Literal
from typing import Literal, TypeGuard
Mode = Literal["read", "write"]
def is_mode(value: str) -> TypeGuard[Mode]:
return value in {"read", "write"}This is useful for command-line options, environment variables, and configuration files. The guide to Python Literal shows how exact values improve overloads and typed APIs.
A generic TypeGuard
from typing import TypeGuard, TypeVar
T = TypeVar("T")
def contains_no_none(values: list[T | None]) -> TypeGuard[list[T]]:
return all(value is not None for value in values)After the check, the list may be treated as list[T]. Mutation still matters: a different reference could insert None later, invalidating the assumption.
Negative narrowing
TypeGuard is primarily designed to narrow the true branch. The else branch may not become as precise as you expect. Modern Python also provides TypeIs, which represents a stricter subtype relationship and can narrow both branches.
Choose TypeGuard when you need flexible narrowing, including relationships that are not ordinary subtyping. Choose TypeIs when the predicate identifies a genuine subtype or intersection and the negative branch should exclude it.
TypeGuard versus cast
from typing import cast
user = cast(User, data)cast() performs no runtime validation. It only tells the checker to trust the programmer. TypeGuard connects a real Boolean check to static narrowing. Prefer it at external boundaries, and reserve casts for invariants already guaranteed by another mechanism.
TypeGuard versus isinstance
When the target is a concrete class or tuple of classes, isinstance() already narrows correctly in most checkers. TypeGuard becomes valuable for internal structure, collection contents, combinations of attributes, and domain-specific validation.
Testing the predicate
Write positive and negative tests covering boundaries, subclasses, empty collections, missing keys, and values that look similar. For integer fields, remember that bool is a subclass of int. If Boolean values must be rejected, prefer type(value) is int instead of isinstance(value, int).
Common mistakes
- Returning True without complete validation: the promised type may be false.
- Ignoring mutation: a collection can change after the check.
- Using TypeGuard where isinstance is enough: this adds complexity without value.
- Checking only part of a TypedDict: an incomplete mapping does not meet the contract.
- Confusing narrowing with conversion: TypeGuard does not transform a value.
- Expecting perfect narrowing in else: that depends on the relationship and checker.
Complete API payload example
from typing import TypedDict, TypeGuard
class Product(TypedDict):
id: int
name: str
price: float
def is_product(value: object) -> TypeGuard[Product]:
if not isinstance(value, dict):
return False
id_value = value.get("id")
name = value.get("name")
price = value.get("price")
return (
type(id_value) is int
and isinstance(name, str)
and isinstance(price, (int, float))
and not isinstance(price, bool)
)
def load(payload: object) -> Product:
if not is_product(payload):
raise ValueError("invalid product")
return payloadThe loader returns a typed Product only after validation. In production systems, consider structured error reports or schema libraries when callers need details about multiple validation failures.
Best practices
Keep predicates small, pure, and deterministic. Use names that clearly describe the condition. Make the parameter type match the actual accepted inputs. Avoid side effects during validation. Centralize boundary rules, and run both runtime tests and a checker such as mypy or pyright in continuous integration.
Conclusion
typing.TypeGuard connects Boolean validation and static type narrowing. It is especially helpful for external data, homogeneous collections, TypedDict, Protocol, and domain rules that cannot be represented by isinstance() alone.
The official Python TypeGuard documentation defines its semantics. Treat each predicate as an auditable promise: validate everything the type claims, test hostile inputs, and prefer read-only interfaces when narrowing collections.
