Typeguard

4.5.1 · active · verified Sat Mar 28

Typeguard is a Python library that provides run-time type checking for functions and methods defined with PEP 484 type annotations, as well as for arbitrary objects. It acts as an additional layer of type safety alongside static type checkers like MyPy, catching type violations that can only be detected at run time. Currently at version 4.5.1, the library is actively maintained with regular updates.

Warnings

breaking Version 4.5.0 introduced a breaking change where `check_argument_types()` started receiving an unexpected keyword argument 'memo', causing issues in downstream libraries.
Fix: If encountering `TypeError: check_argument_types() got an unexpected keyword argument 'memo'`, consider downgrading to `typeguard==4.4.1` or refactoring code to use `@typechecked` or `check_type` which are less susceptible to this specific issue.
gotcha The `@typechecked` decorator becomes a no-op when Python is run in optimized mode (`python -O` or by setting the `PYTHONOPTIMIZE` environment variable). This can lead to silent disabling of runtime type checks in production environments.
Fix: Be aware of this behavior and explicitly configure type checking for production if it's critical. If you need runtime checks in optimized mode, you would need to use `check_type()` explicitly or ensure the import hook is installed in a way that bypasses this optimization behavior (which is not the default for `@typechecked`).
deprecated Direct use of `check_argument_types()` and `check_return_type()` has limitations, such as not working reliably with dynamically defined type hints (e.g., in nested functions) and being less comprehensive than the `@typechecked` decorator.
Fix: Prefer using the `@typechecked` decorator for functions and methods, or the `check_type()` function for individual value checks, as these provide more robust and reliable runtime type enforcement.
breaking Typeguard has dropped support for Python 3.8 in recent major versions (e.g., in the 4.x series).
Fix: Ensure your project runs on Python 3.9 or newer to use the latest versions of Typeguard. The `requires_python` metadata on PyPI reflects this, currently `>=3.9`.

Install

pip install typeguard Install stable version

Imports

typechecked
```
from typeguard import typechecked
```
check_type
```
from typeguard import check_type
```

install_import_hook

from typeguard import install_import_hook

suppress_type_checks

from typeguard import suppress_type_checks

typeguard_ignore
```
from typeguard import typeguard_ignore
```
check_argument_types
```
from typeguard import check_argument_types
```
While still available, `check_argument_types()` has limitations (e.g., cannot check return values, doesn't reliably work with dynamic type hints, and had a breaking change in 4.5.0). The `@typechecked` decorator or `check_type` function are generally preferred for more robust and comprehensive runtime type enforcement.

Quickstart

This quickstart demonstrates using the `@typechecked` decorator on both functions and methods. It shows successful type checking and how `typeguard` raises a `TypeError` when type annotations are violated at runtime.

from typeguard import typechecked
from typing import List

@typechecked
def process_data(data: List[int], multiplier: float) -> List[float]:
    """Processes a list of integers, multiplies each by a float, and returns a list of floats."""
    return [item * multiplier for item in data]

@typechecked
class MyCalculator:
    def __init__(self, offset: int):
        self.offset = offset

    def add(self, a: int, b: int) -> int:
        return a + b + self.offset


# --- Successful usage ---
print(f"Processed data: {process_data([1, 2, 3], 2.5)}") # Expected: [2.5, 5.0, 7.5]
calculator = MyCalculator(offset=10)
print(f"Calculator sum: {calculator.add(5, 7)}") # Expected: 22

# --- Intentional type errors (will raise TypeError) ---
try:
    process_data([1, '2', 3], 2.5) # data contains a string instead of int
except TypeError as e:
    print(f"Caught expected error (list item type): {e}")

try:
    process_data([1, 2, 3], '2.5') # multiplier is a string instead of float
except TypeError as e:
    print(f"Caught expected error (argument type): {e}")

try:
    calculator.add(5, 'seven') # b is a string instead of int
except TypeError as e:
    print(f"Caught expected error (method argument type): {e}")

view raw JSON →