Beartype: Fast, Efficient Runtime Type Checking for Python

Khuyen Tran Beartype vs Static Type Checking Static type checkers like mypy perform type checking only during development/compile time. This means that type errors may not be caught until runtime, potentially causing issues. Let’s consider the following example: # typehint.py def calculate_statistics(data: list[float]) -> dict[str, float]: return { "mean": sum(data) / len(data), "first": data[0] } numbers = [1, "a", 3] # mypy error, but code will run result = calculate_statistics(numbers) # Fails at runtime during sum() Running mypy on this code will raise an error, but the code will still run. $ mypy typehint.py typehint.py:8: error: Argument 1 to "calculate_statistics" has incompatible type "list[object]"; expected "list[float]" [arg-type] Found 1 error in 1 file (checked 1 source file) However, running the code will raise a TypeError at runtime. $ python typehint.py Traceback (most recent call last): File "typehint.py", line 8, in <module> > result = calculate_statistics(numbers) # Fails at runtime during sum() > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | numbers = [1, 'a', 3] File "typehint.py", line 3, in calculate_statistics > "mean": sum(data) / len(data), > ^^^^^^^^^ | data = [1, 'a', 3] TypeError: unsupported operand type(s) for +: 'int' and 'str' Beartype is a runtime type checker that enhances type safety by performing type verification at runtime. This catches issues that static analysis might overlook. from beartype import beartype @beartype def calculate_statistics(data: list[float]) -> dict[str, float]: return { "mean": sum(data) / len(data), "first": data[0] } # Fast runtime checking with clear errors numbers = [1, "a", 3] result = calculate_statistics(numbers) --------------------------------------------------------------------------- BeartypeCallHintParamViolation Traceback (most recent call last) Cell In[15], line 12 10 # Fast runtime checking with clear errors 11 numbers = [1, "a", 3] ---> 12 result = calculate_statistics(numbers) BeartypeCallHintParamViolation: Function calculate_statistics() parameter data=[1, 'a', 3] violates type hint list[float], as list index 0 item int 1 not instance of float. Beartype vs Pydantic Pydantic is another popular library for runtime type checking. However, it adds overhead during model creation and validation. from pydantic import BaseModel from typing import List class StatisticsInput(BaseModel): data: List[float] class StatisticsOutput(BaseModel): mean: float first: float def calculate_statistics(input_data: StatisticsInput) -> StatisticsOutput: return StatisticsOutput( mean=sum(input_data.data) / len(input_data.data), first=input_data.data[0] ) # Validates during model creation, but adds overhead numbers = [1, "a", 3] input_model = StatisticsInput(data=numbers) --------------------------------------------------------------------------- ValidationError Traceback (most recent call last) Cell In[14], line 19 17 # Validates during model creation, but adds overhead 18 numbers = [1, "a", 3] ---> 19 input_model = StatisticsInput(data=numbers) ValidationError: 1 validation error for StatisticsInput data.1 Input should be a valid number, unable to parse string as a number [type=float_parsing, input_value='a', input_type=str] Beartype offers efficient runtime type checking with constant time complexity. Its dynamic wrappers around functions and methods enable flexible and efficient type-checking, making it a great choice for ensuring type safety in your code. Link to Beartype. Favorite