{"id":466,"library":"beartype","title":"Beartype","description":"Beartype is an open-source, pure-Python, PEP-compliant, near-real-time runtime-static type-checker. It emphasizes efficiency, portability, and readability, ensuring O(1) non-amortized worst-case runtime complexity with negligible constant factors. The library has no runtime dependencies and is actively maintained with frequent patch releases addressing compatibility and bug fixes, as evidenced by its rapid `0.22.x` release cycle.","status":"active","version":"0.22.9","language":"python","source_language":"en","source_url":"https://github.com/beartype/beartype","tags":["type-checking","runtime","performance","annotations","decorators","quality assurance","pep-compliant"],"install":[{"cmd":"pip install beartype","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"note":"This is the primary decorator for runtime type-checking of individual functions and methods.","symbol":"beartype","correct":"from beartype import beartype"},{"note":"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`.","symbol":"beartype_this_package","correct":"from beartype.claw import beartype_this_package"},{"note":"Used in conjunction with `typing.Annotated` (Python >= 3.9) to define custom runtime validators for more complex type-checking scenarios.","symbol":"Is","correct":"from beartype.vale import Is\nfrom typing import Annotated"}],"quickstart":{"code":"from beartype import beartype\n\n@beartype\ndef quote_wiggum(lines: list[str]) -> None:\n    print('“{}”\\n\\t— Police Chief Wiggum'.format(\"\\n \".join(lines)))\n\n# Valid call\nquote_wiggum([\"Okay, folks. Show's over!\", \"Nothing to see here.\"])\n\n# Invalid call (will raise BeartypeCallHintPepParamException)\ntry:\n    quote_wiggum([b\"Oh, my God! A horrible plane crash!\"])\nexcept Exception as e:\n    print(f\"Caught expected error: {e.__class__.__name__}: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"gotcha","affected_versions":"<0.22.5"},{"fix":"Upgrade to `beartype` 0.22.4 or higher, which addressed these compatibility issues.","message":"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.","severity":"breaking","affected_versions":"0.22.3"},{"fix":"Upgrade to `beartype` 0.22.8 or higher, which restored `inspect.isgeneratorfunction()`-ness for decorated synchronous generator functions.","message":"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.","severity":"gotcha","affected_versions":"0.22.6, 0.22.7"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when used with Pydantic"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all function arguments strictly adhere to their specified type hints. Review the traceback to identify the specific argument causing the violation and correct the type of the passed value.","message":"Beartype raises `BeartypeCallHintParamViolation` when arguments passed to a decorated function do not conform to their declared type hints. This is `beartype`'s intended behavior for enforcing runtime type validation, catching type mismatches such as passing bytes where str is expected.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:02:34.550Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure that the arguments passed to the `@beartype`-decorated function conform to their specified type hints. For the example, `data` should contain only `float` instances.","cause":"This error occurs when a function decorated with `@beartype` receives a parameter whose runtime type does not match the annotated type hint, indicating a type-checking violation at call time.","error":"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."},{"fix":"Correct the stringified forward reference to accurately reflect the type, ensuring it's a valid identifier or path to the target class, often by only stringifying the yet-to-be-defined class (e.g., `List[\"MyCls\"]`) or using `from __future__ import annotations` if applicable.","cause":"This exception is raised at decoration time when a forward reference (a type hint specified as a string) is syntactically malformed or incorrectly references a type that cannot be resolved by `beartype`.","error":"BeartypeDecorHintForwardRefException: Forward reference \"__main__. List[MyCls]\" syntactically invalid as module attribute name."},{"fix":"Replace imports like `from typing import List` with the direct use of built-in generic types (e.g., `list[str]`) or use `from __future__ import annotations` (which effectively enables built-in generics in older Python versions).","cause":"This error typically occurs in Python 3.9+ when trying to import generic types like `List`, `Dict`, or `Tuple` from the `typing` module, as PEP 585 (Python 3.9+) and PEP 604 (Python 3.10+) made built-in generics (e.g., `list`, `dict`) the standard for type hints. `beartype` often warns about this impending breakage in older Python versions.","error":"ImportError: cannot import name 'List' from 'typing'"},{"fix":"Replace `ByteString` with the built-in `bytes` type, as `bytes` is the appropriate type hint for byte strings.","cause":"This error arises in Python 3.14 and newer versions because `typing.ByteString` (and its corresponding `collections.abc.ByteString`) has been deprecated and subsequently removed.","error":"ImportError: cannot import name 'ByteString' from 'collections.abc'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":8.2,"disk_size":"26.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":8.2,"disk_size":"27M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.38,"mem_mb":8.8,"disk_size":"29.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.3,"mem_mb":8.8,"disk_size":"30M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":8.6,"disk_size":"20.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":8.6,"disk_size":"21M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":8.5,"disk_size":"20.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":8.5,"disk_size":"21M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":8,"disk_size":"26.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":8,"disk_size":"27M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}