Beartype

Warnings

• gotcha Type-checking might be inadvertently disabled when `PYTHONOPTIMIZE=1` or the `-O` flag is used with the Python interpreter in versions prior to `0.22.5`.
  Fix: Upgrade to `beartype` 0.22.5 or higher. Alternatively, avoid running Python with `PYTHONOPTIMIZE=1` or the `-O` flag if runtime type-checking is critical for these older versions.
• breaking Version `0.22.3` introduced a `pyproject.toml` `requires-python` syntax that caused installation failures with `Poetry` and `pipenv` due to their non-standard parsing behavior.
  Fix: Upgrade to `beartype` 0.22.4 or higher, which addressed these compatibility issues.
• gotcha Synchronous generator functions decorated with `@beartype` could lose their `inspect.isgeneratorfunction()` property, causing issues with frameworks like Gradio. This was an issue in `0.22.6` and subsequent patches.
  Fix: Upgrade to `beartype` 0.22.8 or higher, which restored `inspect.isgeneratorfunction()`-ness for decorated synchronous generator functions.
• gotcha Beartype has known incompatibilities with `Pydantic` due to `Pydantic`'s non-standard handling of `if TYPE_CHECKING:` blocks and forward references, which can break runtime type-checking. Beartype internally 'blacklists' `Pydantic` to prevent crashes.
  Fix: Be aware of potential issues when combining `beartype` with `Pydantic` models. While `beartype` attempts to mitigate conflicts, complex interactions might still arise. Consider using `beartype.door.is_bearable()` or `die_if_unbearable()` for manual checks on Pydantic objects if direct decoration causes problems.
• gotcha While `beartype` offers O(1) worst-case type-checking performance, users might perceive a minor overhead when compared to entirely untyped Python code. This is primarily due to the inherent cost of Python's function call stack frames and decorator mechanics, not `beartype`'s specific implementation.
  Fix: Understand that `beartype`'s efficiency refers to the type-checking logic itself, which is highly optimized. The minimal overhead observed is generally a baseline of Python's execution model when decorators are applied, rather than a performance flaw in `beartype`.

Install

• pip install beartype Install latest stable version

Imports

• beartype

  from beartype import beartype

  This is the primary decorator for runtime type-checking of individual functions and methods.
• beartype_this_package

  from beartype.claw import beartype_this_package

  Used to implicitly apply runtime type-checking across all annotated classes, callables, and variable assignments within an entire Python package. Typically called at the top of a package's `__init__.py`.
• Is

  from beartype.vale import Is
  from typing import Annotated

  Used in conjunction with `typing.Annotated` (Python >= 3.9) to define custom runtime validators for more complex type-checking scenarios.

Quickstart

This quickstart demonstrates the core usage of the `@beartype` decorator. It shows a function `quote_wiggum` annotated with standard type hints. When called with valid parameters (a list of strings), it executes normally. When called with invalid parameters (a list of bytes), `beartype` intercepts the call and raises a `BeartypeCallHintPepParamException`, providing a clear error message about the type violation.

from beartype import beartype

@beartype
def quote_wiggum(lines: list[str]) -> None:
    print('“{}”\n\t— Police Chief Wiggum'.format("\n ".join(lines)))

# Valid call
quote_wiggum(["Okay, folks. Show's over!", "Nothing to see here."])

# Invalid call (will raise BeartypeCallHintPepParamException)
try:
    quote_wiggum([b"Oh, my God! A horrible plane crash!"])
except Exception as e:
    print(f"Caught expected error: {e.__class__.__name__}: {e}")