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
```