or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-type-checking.mddoor-api.mdexceptions.mdimport-hooks.mdindex.mdtyping-compatibility.mdvalidators.md
tile.json

tessl/pypi-beartype

Unbearably fast near-real-time hybrid runtime-static type-checking in pure Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/beartype@0.21.x

To install, run

npx @tessl/cli install tessl/pypi-beartype@0.21.0

index.mddocs/

Beartype

A pure-Python runtime type-checking library that provides near-real-time hybrid runtime-static type checking capabilities. Beartype emphasizes efficiency, portability, and PEP compliance while requiring zero mandatory runtime dependencies. It offers comprehensive type validation for Python applications through decorators and runtime checks, supporting modern Python type hints and annotations.

Package Information

  • Package Name: beartype
  • Language: Python
  • Installation: pip install beartype

Core Imports

from beartype import beartype

Common configuration and utilities:

from beartype import beartype, BeartypeConf, BeartypeStrategy

Import hooks for automatic decoration:

from beartype.claw import beartype_this_package, beartype_all

Basic Usage

from beartype import beartype
from typing import List, Optional

@beartype
def process_items(items: List[str], limit: Optional[int] = None) -> int:
    """Process a list of string items with optional limit."""
    if limit is not None:
        items = items[:limit]
    return len(items)

# Type checking happens automatically at runtime
result = process_items(["hello", "world"], 5)  # ✓ Valid
# process_items([1, 2, 3], 5)  # ✗ Raises BeartypeCallHintParamViolation

Package-wide automatic decoration:

from beartype.claw import beartype_this_package

# Apply beartype to all functions in your package automatically
beartype_this_package()

# Now all annotated functions are automatically type-checked
def multiply(x: int, y: int) -> int:
    return x * y

result = multiply(3, 4)  # ✓ Valid
# multiply("3", 4)  # ✗ Raises type violation

Architecture

Beartype uses a multi-layered approach for efficient runtime type checking:

  • Decorator Layer: The @beartype decorator wraps functions with type-checking logic
  • Configuration Layer: BeartypeConf allows fine-grained control over type-checking behavior
  • Import Hooks: beartype.claw provides automatic decoration of entire packages
  • Object-Oriented API: beartype.door offers introspective type hint classes
  • Validators: beartype.vale enables custom validation logic beyond basic type checking

The design allows constant-time type checking algorithms (O(1)) for maximum performance while providing detailed error reporting for type violations.

Capabilities

Core Type Checking

Primary decorator and configuration for runtime type validation of functions and classes.

def beartype(func_or_conf=None, **kwargs): ...
class BeartypeConf: ...
class BeartypeStrategy: ...
class BeartypeViolationVerbosity: ...

Core Type Checking

Import Hooks

Automatic decoration of packages and modules using PEP 302/451-compliant import hooks.

def beartype_all(conf=None): ...
def beartype_package(package_name, conf=None): ...
def beartype_packages(*package_names, conf=None): ...
def beartype_this_package(conf=None): ...
def beartyping(conf=None): ...

Import Hooks

Object-Oriented Type Introspection

DOOR (Decidedly Object-Oriented Runtime-checking) API for advanced type hint manipulation and introspection.

class TypeHint: ...
class UnionTypeHint(TypeHint): ...
class AnnotatedTypeHint(TypeHint): ...
def is_bearable(obj, hint): ...
def die_if_unbearable(obj, hint): ...
def infer_hint(obj): ...

Object-Oriented API

Custom Validators

Data validation beyond basic type checking using composable validator factories.

class Is: ...
class IsAttr: ...
class IsEqual: ...
class IsInstance: ...
class IsSubclass: ...

Custom Validators

Exception Handling

Comprehensive exception hierarchy for different types of type-checking failures and configuration errors.

class BeartypeException(Exception): ...
class BeartypeCallHintViolation(BeartypeException): ...
class BeartypeCallHintParamViolation(BeartypeCallHintViolation): ...
class BeartypeCallHintReturnViolation(BeartypeCallHintViolation): ...

Exception Handling

Typing Compatibility

Enhanced typing module compatibility layer with optimizations and forward compatibility features.

# All standard typing attributes plus optimized versions
from beartype.typing import List, Dict, Optional, Union, Protocol

Typing Compatibility

Types

Configuration

class BeartypeConf:
    def __new__(
        cls,
        *,
        strategy: BeartypeStrategy = BeartypeStrategy.O1,
        is_debug: bool = False,
        is_color: Optional[bool] = None,
        violation_type: Optional[type] = None,
        # ... additional parameters
    ): ...

class BeartypeDecorationPosition(Enum):
    FIRST = "FIRST"  # First (bottom-most) decorator position
    LAST = "LAST"    # Last (top-most) decorator position

class BeartypeStrategy(Enum):
    O0 = "O0"  # Disable type-checking
    O1 = "O1"  # Constant-time type-checking
    Ologn = "Ologn"  # Logarithmic-time type-checking
    On = "On"  # Linear-time type-checking

class BeartypeViolationVerbosity(Enum):
    MINIMAL = "MINIMAL"
    DEFAULT = "DEFAULT"
    MAXIMAL = "MAXIMAL"

Utility Types

class FrozenDict(dict):
    """Immutable dictionary implementation."""
    def __init__(self, *args, **kwargs): ...
    def __setitem__(self, key, value): ...  # Raises TypeError
    def __delitem__(self, key): ...  # Raises TypeError