Repolode
Submit
agronholm

agronholm/typeguard

Run-time type checker for Python that validates PEP 484 annotations on functions, arbitrary objects, and local variables.

View on GitHub
Stars
1,793
Forks
154
Open issues
59
Last commit
10 days ago

What is it?

Typeguard checks Python type annotations while the program runs, catching violations that static checkers such as mypy cannot see. It can be used as a stricter alternative to isinstance() that understands arbitrary type hints, or as a cast() replacement that actually verifies the value.

For automatic checking, Typeguard offers two instrumentation routes. The @typechecked decorator recompiles individual functions with checks injected for arguments, return values, annotated local variable assignments, and yield and send values in generators. The import hook, installed with install_import_hook(), instruments target modules on import without changing their source, though it must be installed before those modules load.

The library also provides check_argument_types() and check_return_type() for a lighter, debugger-friendly approach, with the caveat that it is less reliable with dynamically defined hints such as those in nested functions. Instrumentation requires the original source code of the modules to be accessible.

Key features

  • 01Checks function arguments and return values against PEP 484 annotations at run time.
  • 02Works with arbitrary type annotations as a more capable isinstance() or cast() replacement.
  • 03Instruments individual functions via the @typechecked decorator.
  • 04Offers an import hook that checks targeted modules without source changes.
  • 05Checks yield and send values for regular and async generators.

Use cases

  • Adding an extra layer of type safety to Python code alongside a static type checker.
  • Validating data at boundaries where annotations alone do not guarantee correct types.
  • Debugging type mismatches that only appear during execution.
  • Enforcing type hints in test suites or a staging environment.

Quick start

  1. 1

    Install the package from PyPI

    pip install typeguard
  2. 2

    Use check_type to validate a value at run time

Things to know

  • The README does not state a license; metadata lists it as NOASSERTION, so check the license file before use.
  • Code instrumentation requires the original source code of the instrumented modules to be accessible.
  • The import hook may clash with other import hooks.

In collections

Testing frameworks & test automation tools

Topics

#python#type-checking#type-hints#pep-484#runtime-validation#testing

FAQ

What is typeguard?
Run-time type checker for Python that validates PEP 484 annotations on functions, arbitrary objects, and local variables. Typeguard checks Python type annotations while the program runs, catching violations that static checkers such as mypy cannot see. It can be used as a stricter alternative to isinstance() that understands arbitrary type hints, or as a cast() replacement that actually verifies the value.
Is typeguard free to use? What license does it have?
typeguard is open source under the Other license. Check the license terms before using it in commercial products.
Is typeguard still maintained?
Actively maintained. The last commit to typeguard was on Oct 29, 2026.
What can I use typeguard for?
Adding an extra layer of type safety to Python code alongside a static type checker. Validating data at boundaries where annotations alone do not guarantee correct types. Debugging type mismatches that only appear during execution. Enforcing type hints in test suites or a staging environment.
How do I install typeguard?
Install the package from PyPI: pip install typeguard Use check_type to validate a value at run time
Where can I get typeguard?
The source code and installation instructions are on GitHub: https://github.com/agronholm/typeguard

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects