0
# Exceptions
1
2
Comprehensive exception hierarchy for robust error handling during MessagePack serialization and deserialization operations. These exceptions provide detailed information about various failure modes and enable precise error recovery strategies.
3
4
## Capabilities
5
6
### Base Exception Classes
7
8
Root exception types that serve as base classes for more specific MessagePack errors.
9
10
```python { .api }
11
class UnpackException(Exception):
12
"""
13
Base class for some exceptions raised while unpacking.
14
15
Note: unpack may raise exception other than subclass of
16
UnpackException. If you want to catch all errors, catch
17
Exception instead.
18
"""
19
```
20
21
### Buffer Management Exceptions
22
23
Exceptions related to internal buffer state and capacity limits during streaming operations.
24
25
```python { .api }
26
class BufferFull(UnpackException):
27
"""
28
Raised when internal buffer exceeds size limits.
29
30
This exception occurs when the unpacker's internal buffer
31
reaches the configured max_buffer_size limit.
32
"""
33
34
class OutOfData(UnpackException):
35
"""
36
Raised when buffer contains incomplete data.
37
38
This exception occurs during streaming unpacking when
39
the current buffer doesn't contain enough data to
40
complete the requested operation.
41
"""
42
```
43
44
### Format Validation Exceptions
45
46
Exceptions that indicate problems with MessagePack binary format compliance.
47
48
```python { .api }
49
class FormatError(ValueError, UnpackException):
50
"""
51
Invalid msgpack format.
52
53
Raised when the binary data doesn't conform to the
54
MessagePack specification or contains corrupted data.
55
"""
56
57
class StackError(ValueError, UnpackException):
58
"""
59
Too nested data structure.
60
61
Raised when unpacking data with nesting levels that
62
exceed the recursion limits, preventing stack overflow.
63
"""
64
```
65
66
### Data Integrity Exceptions
67
68
Exceptions that handle cases where unpacking succeeds but additional data is present.
69
70
```python { .api }
71
class ExtraData(UnpackValueError):
72
"""
73
ExtraData is raised when there is trailing data.
74
75
This exception is raised during one-shot (not streaming)
76
unpack operations when the input contains more data
77
than expected after successfully unpacking an object.
78
"""
79
80
unpacked: object
81
"""The successfully unpacked object"""
82
83
extra: bytes
84
"""The extra bytes that were not consumed"""
85
86
def __init__(self, unpacked, extra):
87
"""
88
Initialize ExtraData exception.
89
90
Parameters:
91
- unpacked: object, the successfully unpacked data
92
- extra: bytes, the remaining unconsumed data
93
"""
94
95
def __str__(self):
96
"""Return error message string."""
97
```
98
99
### Legacy Exception Aliases
100
101
Backward compatibility aliases for deprecated exception names.
102
103
```python { .api }
104
UnpackValueError = ValueError
105
"""Deprecated. Use ValueError instead."""
106
107
PackException = Exception
108
"""Deprecated. Use Exception instead to catch all packing exceptions."""
109
110
PackValueError = ValueError
111
"""Deprecated. Use ValueError instead."""
112
113
PackOverflowError = OverflowError
114
"""Deprecated. Use OverflowError instead."""
115
```
116
117
## Usage Examples
118
119
### Basic Error Handling
120
121
```python
122
import msgpack
123
124
try:
125
data = msgpack.unpackb(b'\x81\xa4name\xa5Alice')
126
print(data) # {'name': 'Alice'}
127
except msgpack.FormatError as e:
128
print(f"Invalid MessagePack format: {e}")
129
except msgpack.UnpackException as e:
130
print(f"Unpacking error: {e}")
131
```
132
133
### Handling Extra Data
134
135
```python
136
import msgpack
137
138
# Data with extra bytes at the end
139
data_with_extra = msgpack.packb('hello') + msgpack.packb('world')
140
141
try:
142
result = msgpack.unpackb(data_with_extra)
143
except msgpack.ExtraData as e:
144
print(f"Unpacked: {e.unpacked}") # 'hello'
145
print(f"Extra bytes: {len(e.extra)}") # Length of packed 'world'
146
147
# Process the extra data
148
remaining = msgpack.unpackb(e.extra)
149
print(f"Remaining: {remaining}") # 'world'
150
```
151
152
### Streaming Error Recovery
153
154
```python
155
import msgpack
156
157
unpacker = msgpack.Unpacker(max_buffer_size=1024)
158
159
while True:
160
try:
161
chunk = receive_data() # Get data from network/file
162
unpacker.feed(chunk)
163
164
while True:
165
try:
166
obj = unpacker.unpack()
167
process_object(obj)
168
except msgpack.OutOfData:
169
# Need more data, break inner loop
170
break
171
172
except msgpack.BufferFull:
173
print("Buffer full, clearing and restarting")
174
unpacker = msgpack.Unpacker(max_buffer_size=1024)
175
176
except msgpack.FormatError as e:
177
print(f"Format error: {e}")
178
# Skip corrupted data or reset connection
179
unpacker = msgpack.Unpacker(max_buffer_size=1024)
180
181
except ConnectionError:
182
print("Connection lost")
183
break
184
```
185
186
### Security-Focused Error Handling
187
188
```python
189
import msgpack
190
191
def safe_unpack(data, max_size=1024*1024):
192
"""Safely unpack data with comprehensive error handling."""
193
try:
194
return msgpack.unpackb(
195
data,
196
max_buffer_size=max_size,
197
strict_map_key=True,
198
raw=False
199
)
200
except msgpack.BufferFull:
201
raise ValueError(f"Data exceeds size limit of {max_size} bytes")
202
except msgpack.FormatError:
203
raise ValueError("Invalid or corrupted MessagePack data")
204
except msgpack.StackError:
205
raise ValueError("Data structure too deeply nested")
206
except msgpack.ExtraData as e:
207
# Log warning but return the valid data
208
print(f"Warning: {len(e.extra)} extra bytes ignored")
209
return e.unpacked
210
211
# Usage
212
try:
213
obj = safe_unpack(untrusted_data)
214
process_trusted_object(obj)
215
except ValueError as e:
216
print(f"Unsafe data rejected: {e}")
217
```
218
219
### Comprehensive Exception Catching
220
221
```python
222
import msgpack
223
224
def robust_msgpack_operation(data):
225
"""Handle all possible MessagePack exceptions."""
226
try:
227
return msgpack.unpackb(data)
228
except msgpack.ExtraData as e:
229
# Handle extra data specifically
230
return e.unpacked
231
except msgpack.FormatError:
232
# Handle format errors
233
raise ValueError("Invalid MessagePack format")
234
except msgpack.StackError:
235
# Handle nesting errors
236
raise ValueError("Data too deeply nested")
237
except msgpack.BufferFull:
238
# Handle buffer overflow
239
raise ValueError("Data too large")
240
except msgpack.UnpackException:
241
# Catch any other unpacking errors
242
raise ValueError("Unknown unpacking error")
243
except Exception:
244
# Catch any other unexpected errors
245
raise ValueError("Unexpected error during unpacking")
246
```