typeguard

typeguard provides run-time type checking for Python code annotated with PEP 484 type hints. It complements static type checkers like mypy by catching type violations that only surface at run time, validating function arguments, return values, and arbitrary objects against their declared annotations.

It offers several strategies to fit different workflows: a direct check_type function that works like a checked isinstance, a @typechecked decorator for individual functions, and an import hook that transparently instruments entire modules so their annotated functions and local variables are validated automatically. A bundled pytest plugin makes it easy to enable checking during test runs.

What You Get

• A check_type function that validates any value against an arbitrary type annotation
• A @typechecked decorator that checks a function’s arguments and return values at run time
• An import hook that automatically instruments whole modules on import
• Support for generators, async functions, and annotated local variables
• A pytest plugin for enabling run-time type checks during testing

Common Use Cases

• Catching type violations at run time that static type checkers cannot prove
• Validating external or dynamically produced data against typed function signatures
• Adding a checked alternative to isinstance for complex generic annotations
• Hardening test suites by instrumenting modules with the import hook or pytest plugin

Under The Hood

Architecture - The package under src/typeguard is organized around a set of private modules: _checkers.py holds the type-checking logic for the many supported annotation forms, _decorators.py implements @typechecked, _transformer.py and _importhook.py power AST-level code instrumentation via an import hook, and _functions.py exposes the public check_type entry point. A _pytest_plugin.py integrates checking into test runs, and _config.py/_suppression.py manage global configuration and temporary suppression.

Tech Stack - Pure Python (typed, ships py.typed) built with a modern pyproject.toml. It leans on the standard library’s typing, inspect, and ast modules to introspect annotations and rewrite code, with backport dependencies used to support the full range of typing features across Python versions.

Code Quality - The project is mature and well-tested, with an extensive tests/ suite covering checkers, functions, the import hook, instrumentation, and mypy integration, plus CI running tests and coverage reporting. Clear module boundaries and dedicated exception types reflect a disciplined, long-maintained codebase.

API Design - The public surface is small and approachable: check_type(value, SomeType) mirrors isinstance, @typechecked drops onto functions with no configuration, and install_import_hook() enables module-wide checking in one call. The three strategies are documented with explicit trade-offs, and the ReadTheDocs site plus README examples keep the learning curve modest despite the sophistication of the underlying instrumentation.