0
# Beartype
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: beartype
7
- **Language**: Python
8
- **Installation**: `pip install beartype`
9

10
## Core Imports
11

12
```python
13
from beartype import beartype
14
```
15

16
Common configuration and utilities:
17

18
```python
19
from beartype import beartype, BeartypeConf, BeartypeStrategy
20
```
21

22
Import hooks for automatic decoration:
23

24
```python
25
from beartype.claw import beartype_this_package, beartype_all
26
```
27

28
## Basic Usage
29

30
```python
31
from beartype import beartype
32
from typing import List, Optional
33

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

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

46
Package-wide automatic decoration:
47

48
```python
49
from beartype.claw import beartype_this_package
50

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

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

58
result = multiply(3, 4)  # ✓ Valid
59
# multiply("3", 4)  # ✗ Raises type violation
60
```
61

62
## Architecture
63

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

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

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

74
## Capabilities
75

76
### Core Type Checking
77

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

80
```python { .api }
81
def beartype(func_or_conf=None, **kwargs): ...
82
class BeartypeConf: ...
83
class BeartypeStrategy: ...
84
class BeartypeViolationVerbosity: ...
85
```
86

87
[Core Type Checking](./core-type-checking.md)
88

89
### Import Hooks
90

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

93
```python { .api }
94
def beartype_all(conf=None): ...
95
def beartype_package(package_name, conf=None): ...
96
def beartype_packages(*package_names, conf=None): ...
97
def beartype_this_package(conf=None): ...
98
def beartyping(conf=None): ...
99
```
100

101
[Import Hooks](./import-hooks.md)
102

103
### Object-Oriented Type Introspection
104

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

107
```python { .api }
108
class TypeHint: ...
109
class UnionTypeHint(TypeHint): ...
110
class AnnotatedTypeHint(TypeHint): ...
111
def is_bearable(obj, hint): ...
112
def die_if_unbearable(obj, hint): ...
113
def infer_hint(obj): ...
114
```
115

116
[Object-Oriented API](./door-api.md)
117

118
### Custom Validators
119

120
Data validation beyond basic type checking using composable validator factories.
121

122
```python { .api }
123
class Is: ...
124
class IsAttr: ...
125
class IsEqual: ...
126
class IsInstance: ...
127
class IsSubclass: ...
128
```
129

130
[Custom Validators](./validators.md)
131

132
### Exception Handling
133

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

136
```python { .api }
137
class BeartypeException(Exception): ...
138
class BeartypeCallHintViolation(BeartypeException): ...
139
class BeartypeCallHintParamViolation(BeartypeCallHintViolation): ...
140
class BeartypeCallHintReturnViolation(BeartypeCallHintViolation): ...
141
```
142

143
[Exception Handling](./exceptions.md)
144

145
### Typing Compatibility
146

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

149
```python { .api }
150
# All standard typing attributes plus optimized versions
151
from beartype.typing import List, Dict, Optional, Union, Protocol
152
```
153

154
[Typing Compatibility](./typing-compatibility.md)
155

156
## Types
157

158
### Configuration
159

160
```python { .api }
161
class BeartypeConf:
162
    def __new__(
163
        cls,
164
        *,
165
        strategy: BeartypeStrategy = BeartypeStrategy.O1,
166
        is_debug: bool = False,
167
        is_color: Optional[bool] = None,
168
        violation_type: Optional[type] = None,
169
        # ... additional parameters
170
    ): ...
171

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

176
class BeartypeStrategy(Enum):
177
    O0 = "O0"  # Disable type-checking
178
    O1 = "O1"  # Constant-time type-checking
179
    Ologn = "Ologn"  # Logarithmic-time type-checking
180
    On = "On"  # Linear-time type-checking
181

182
class BeartypeViolationVerbosity(Enum):
183
    MINIMAL = "MINIMAL"
184
    DEFAULT = "DEFAULT"
185
    MAXIMAL = "MAXIMAL"
186
```
187

188
### Utility Types
189

190
```python { .api }
191
class FrozenDict(dict):
192
    """Immutable dictionary implementation."""
193
    def __init__(self, *args, **kwargs): ...
194
    def __setitem__(self, key, value): ...  # Raises TypeError
195
    def __delitem__(self, key): ...  # Raises TypeError
196
```