0
# Exception Handling
1
2
Comprehensive exception and warning hierarchy for different types of type-checking failures and configuration errors. The `beartype.roar` module provides detailed exception classes for precise error handling and debugging of type violations.
3
4
## Capabilities
5
6
### Base Exception Classes
7
8
Root exception classes that all beartype errors inherit from.
9
10
```python { .api }
11
class BeartypeException(Exception):
12
"""
13
Base exception for all beartype-related errors.
14
15
Root exception class from which all other beartype exceptions inherit.
16
Provides common functionality for beartype error handling.
17
"""
18
19
class BeartypeHintViolation(BeartypeException):
20
"""
21
Base class for type hint violations.
22
23
Root class for all exceptions raised during runtime type checking
24
when objects fail to satisfy their type hints.
25
"""
26
```
27
28
### Runtime Call Violations
29
30
Exceptions raised during function or method calls when type checking fails.
31
32
```python { .api }
33
class BeartypeCallHintViolation(BeartypeHintViolation):
34
"""
35
Type hint violation during callable invocation.
36
37
Raised when parameters or return values violate their type hints
38
during function or method calls.
39
"""
40
41
class BeartypeCallHintParamViolation(BeartypeCallHintViolation):
42
"""
43
Parameter type hint violation.
44
45
Raised when a parameter value doesn't match its declared type hint
46
during function invocation.
47
"""
48
49
class BeartypeCallHintReturnViolation(BeartypeCallHintViolation):
50
"""
51
Return value type hint violation.
52
53
Raised when a function's return value doesn't match its declared
54
return type hint.
55
"""
56
```
57
58
Usage examples:
59
60
```python
61
from beartype import beartype
62
from beartype.roar import (
63
BeartypeCallHintParamViolation,
64
BeartypeCallHintReturnViolation
65
)
66
67
@beartype
68
def divide(x: int, y: int) -> float:
69
return x / y
70
71
try:
72
divide("10", 2) # String instead of int
73
except BeartypeCallHintParamViolation as e:
74
print(f"Parameter error: {e}")
75
76
@beartype
77
def get_name() -> str:
78
return 42 # Should return string
79
80
try:
81
get_name()
82
except BeartypeCallHintReturnViolation as e:
83
print(f"Return type error: {e}")
84
```
85
86
### Decorator and Configuration Exceptions
87
88
Exceptions related to decorator usage and configuration.
89
90
```python { .api }
91
class BeartypeDecorException(BeartypeException):
92
"""
93
Decorator-related exception.
94
95
Base class for errors that occur during decorator application
96
or wrapper function generation.
97
"""
98
99
class BeartypeDecorHintException(BeartypeDecorException):
100
"""
101
Type hint decoration exception.
102
103
Raised when there are issues with type hints during decorator
104
application, such as invalid or unsupported type hints.
105
"""
106
107
class BeartypeConfException(BeartypeException):
108
"""
109
Configuration-related exception.
110
111
Raised when BeartypeConf objects are created with invalid
112
parameters or used incorrectly.
113
"""
114
115
class BeartypeConfParamException(BeartypeConfException):
116
"""
117
Configuration parameter exception.
118
119
Raised when invalid parameters are passed to BeartypeConf
120
constructor or configuration methods.
121
"""
122
```
123
124
Usage examples:
125
126
```python
127
from beartype import beartype, BeartypeConf
128
from beartype.roar import BeartypeConfParamException
129
130
try:
131
# Invalid configuration parameter
132
conf = BeartypeConf(strategy="invalid_strategy")
133
except BeartypeConfParamException as e:
134
print(f"Configuration error: {e}")
135
136
# Invalid type hint usage
137
try:
138
@beartype
139
def bad_function(x: "invalid_forward_ref") -> int:
140
return x
141
except BeartypeDecorHintException as e:
142
print(f"Type hint error: {e}")
143
```
144
145
### Import Hook Exceptions
146
147
Exceptions related to the import hook system in `beartype.claw`.
148
149
```python { .api }
150
class BeartypeClawException(BeartypeException):
151
"""
152
Import hook exception.
153
154
Base class for errors in the beartype.claw import hook system.
155
"""
156
157
class BeartypeClawHookException(BeartypeClawException):
158
"""
159
Hook installation exception.
160
161
Raised when there are errors installing or managing import hooks.
162
"""
163
164
class BeartypeClawImportException(BeartypeClawException):
165
"""
166
Import processing exception.
167
168
Raised when errors occur while processing imports through
169
beartype import hooks.
170
"""
171
```
172
173
### DOOR API Exceptions
174
175
Exceptions related to the object-oriented type introspection API.
176
177
```python { .api }
178
class BeartypeDoorException(BeartypeException):
179
"""
180
DOOR API exception.
181
182
Base class for errors in the beartype.door object-oriented API.
183
"""
184
185
class BeartypeDoorHintViolation(BeartypeHintViolation):
186
"""
187
DOOR type hint violation.
188
189
Raised by DOOR API functions when objects fail type validation.
190
"""
191
192
class BeartypeDoorPepException(BeartypeDoorException):
193
"""
194
PEP compliance exception in DOOR API.
195
196
Raised when type hints don't conform to expected PEP standards
197
in DOOR API operations.
198
"""
199
```
200
201
Usage examples:
202
203
```python
204
from beartype.door import die_if_unbearable, is_bearable
205
from beartype.roar import BeartypeDoorHintViolation
206
from typing import List
207
208
try:
209
die_if_unbearable("not a list", List[int])
210
except BeartypeDoorHintViolation as e:
211
print(f"DOOR validation error: {e}")
212
213
# Check type compatibility safely
214
if not is_bearable(42, str):
215
print("Type mismatch detected")
216
```
217
218
### Validator Exceptions
219
220
Exceptions related to custom validators in `beartype.vale`.
221
222
```python { .api }
223
class BeartypeValeException(BeartypeException):
224
"""
225
Validator exception.
226
227
Base class for errors in the beartype.vale validator system.
228
"""
229
230
class BeartypeValeValidationException(BeartypeValeException):
231
"""
232
Validation failure exception.
233
234
Raised when custom validators fail to validate objects.
235
"""
236
237
class BeartypeValeSubscriptionException(BeartypeValeException):
238
"""
239
Validator subscription exception.
240
241
Raised when validator factories are subscripted with invalid parameters.
242
"""
243
```
244
245
Usage examples:
246
247
```python
248
from beartype import beartype
249
from beartype.vale import Is
250
from beartype.roar import BeartypeValeValidationException
251
from typing import Annotated
252
253
PositiveInt = Annotated[int, Is[lambda x: x > 0]]
254
255
@beartype
256
def process_positive(value: PositiveInt) -> int:
257
return value * 2
258
259
try:
260
process_positive(-5)
261
except BeartypeValeValidationException as e:
262
print(f"Validator error: {e}")
263
```
264
265
### Warning Hierarchy
266
267
Non-fatal warnings for various beartype operations.
268
269
```python { .api }
270
class BeartypeWarning(UserWarning):
271
"""
272
Base warning class for beartype.
273
274
Root warning class for all beartype-related warnings.
275
"""
276
277
class BeartypeDecorHintWarning(BeartypeWarning):
278
"""
279
Type hint decoration warning.
280
281
Emitted for non-fatal issues with type hints during decoration.
282
"""
283
284
class BeartypeClawWarning(BeartypeWarning):
285
"""
286
Import hook warning.
287
288
Emitted for non-fatal issues in the import hook system.
289
"""
290
291
class BeartypeConfWarning(BeartypeWarning):
292
"""
293
Configuration warning.
294
295
Emitted for non-fatal configuration issues.
296
"""
297
```
298
299
### PEP-Specific Exceptions
300
301
Exceptions for specific PEP standard violations.
302
303
```python { .api }
304
class BeartypePepException(BeartypeException):
305
"""Base class for PEP standard violations."""
306
307
class BeartypeDecorHintPep484Exception(BeartypeDecorHintException):
308
"""PEP 484 (typing) standard violation."""
309
310
class BeartypeDecorHintPep585Exception(BeartypeDecorHintException):
311
"""PEP 585 (generic aliases) standard violation."""
312
313
class BeartypeDecorHintPep593Exception(BeartypeDecorHintException):
314
"""PEP 593 (Annotated) standard violation."""
315
316
class BeartypeDecorHintPep604Exception(BeartypeDecorHintException):
317
"""PEP 604 (union operator |) standard violation."""
318
```
319
320
### Exception Handling Patterns
321
322
#### Specific Error Handling
323
324
```python
325
from beartype import beartype
326
from beartype.roar import (
327
BeartypeCallHintParamViolation,
328
BeartypeCallHintReturnViolation,
329
BeartypeDecorHintException
330
)
331
332
@beartype
333
def robust_function(x: int, y: str) -> float:
334
return float(len(y) + x)
335
336
def safe_call():
337
try:
338
return robust_function("not int", "valid string")
339
except BeartypeCallHintParamViolation as e:
340
print(f"Invalid parameter: {e}")
341
return None
342
except BeartypeCallHintReturnViolation as e:
343
print(f"Invalid return value: {e}")
344
return None
345
```
346
347
#### Generic Error Handling
348
349
```python
350
from beartype import beartype
351
from beartype.roar import BeartypeException, BeartypeHintViolation
352
353
@beartype
354
def risky_operation(data: list[int]) -> int:
355
return sum(data)
356
357
def safe_operation(data):
358
try:
359
return risky_operation(data)
360
except BeartypeHintViolation as e:
361
# Handle type hint violations specifically
362
print(f"Type violation: {e}")
363
return 0
364
except BeartypeException as e:
365
# Handle other beartype errors
366
print(f"Beartype error: {e}")
367
return 0
368
```
369
370
#### Warning Handling
371
372
```python
373
import warnings
374
from beartype.roar import BeartypeWarning
375
376
# Filter beartype warnings
377
warnings.filterwarnings("ignore", category=BeartypeWarning)
378
379
# Or handle them specifically
380
def warning_handler(message, category, filename, lineno, file=None, line=None):
381
if issubclass(category, BeartypeWarning):
382
print(f"Beartype warning: {message}")
383
384
warnings.showwarning = warning_handler
385
```