Unpacking
Example
>>> umsgpack.unpackb(b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3\
foo\xc4\x03\x80\x01\x02\xa3bar\x94\x01\x02\x03\x81\xa1a\x94\x01\x02\
\x03\x80\xff\xcb@\x00\xfc\xd3Z\x85\x87\x94')
[1, True, False, 4294967295, {'foo': b'\x80\x01\x02', \
'bar': [1, 2, 3, {'a': [1, 2, 3, {}]}]}, -1, 2.12345]
>>>
API
- umsgpack.unpackb(s, **options)
Deserialize MessagePack bytes into a Python object.
- Parameters:
s (bytes, bytearray) – serialized MessagePack bytes
- Keyword Arguments:
ext_handlers (dict) – dictionary of Ext handlers, mapping integer Ext type to a callable that unpacks an instance of Ext into an object
use_ordered_dict (bool) – unpack maps into OrderedDict, instead of dict (default False)
use_tuple (bool) – unpacks arrays into tuples, instead of lists (default False)
allow_invalid_utf8 (bool) – unpack invalid strings into instances of
InvalidString, for access to the bytes (default False)max_depth (int) – maximum nesting depth of arrays/maps to unpack; when exceeded,
MaximumDepthExceptionis raised. If None (default), depth is bounded only by the interpreter’s recursion limit.
- Returns:
Python object
- Raises:
TypeError – Packed data type is neither ‘bytes’ nor ‘bytearray’.
InsufficientDataException(UnpackException) – Insufficient data to unpack the serialized object.
InvalidStringException(UnpackException) – Invalid UTF-8 string encountered during unpacking.
UnsupportedTimestampException(UnpackException) – Unsupported timestamp format encountered during unpacking.
ReservedCodeException(UnpackException) – Reserved code encountered during unpacking.
UnhashableKeyException(UnpackException) – Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.
DuplicateKeyException(UnpackException) – Duplicate key encountered during map unpacking.
MaximumDepthException(UnpackException) – Maximum nesting depth exceeded while unpacking a deeply-nested object, or the configured limit was exceeded (when
max_depthis set).
Example
>>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00') {'compact': True, 'schema': 0}
Also available under the umsgpack.loads() alias.
Options
Ext Handlers
See the Extension Types section.
Ordered Dictionaries
The unpacking functions provide a use_ordered_dict option to unpack
MessagePack maps into the collections.OrderedDict type, rather than the
unordered dict type, to preserve the order of deserialized MessagePack maps.
Note that as of Python 3.6, dictionaries are insertion ordered by default.
>>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00')
{'compact': True, 'schema': 0}
>>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00', use_ordered_dict=True)
OrderedDict([('compact', True), ('schema', 0)])
>>>
Tuples
The unpacking functions provide a use_tuple option to unpack MessagePack
arrays into tuples, rather than lists.
>>> umsgpack.unpackb(b'\x93\xa1a\xc3\x92\x01\x92\x02\x03')
['a', True, [1, [2, 3]]]
>>> umsgpack.unpackb(b'\x93\xa1a\xc3\x92\x01\x92\x02\x03', use_tuple=True)
('a', True, (1, (2, 3)))
>>>
Invalid UTF-8 Strings
The unpacking functions provide an allow_invalid_utf8 option to unpack
MessagePack strings with invalid UTF-8 into the umsgpack.InvalidString type,
instead of throwing an exception. The umsgpack.InvalidString type is a
subclass of bytes, and can be used like any other bytes object.
>>> # Attempt to unpack invalid UTF-8 string
... umsgpack.unpackb(b'\xa4\x80\x01\x02\x03')
...
umsgpack.InvalidStringException: unpacked string is invalid utf-8
>>> umsgpack.unpackb(b'\xa4\x80\x01\x02\x03', allow_invalid_utf8=True)
b'\x80\x01\x02\x03'
>>>
Maximum Nesting Depth
The unpacking functions provide a max_depth option to limit the nesting depth
of unpacked MessagePack arrays and maps. When the limit is exceeded, a
umsgpack.MaximumDepthException is raised. If max_depth is unspecified, the
nesting depth is bounded by the interpreter’s recursion limit.
>>> umsgpack.unpackb(b'\x91\x91\x91\x91\x91\xc0')
[[[[[None]]]]]
>>> umsgpack.unpackb(b'\x91\x91\x91\x91\x91\xc0', max_depth=3)
...
umsgpack.MaximumDepthException: maximum nesting depth exceeded
>>>
Exceptions
If a non-byte-string argument is passed to umsgpack.unpackb(), it will raise
a TypeError exception. If an error occurs during unpacking, u-msgpack-python
will raise an exception derived from umsgpack.UnpackException. Possible
unpacking exceptions are described below.
TypeError
Packed data is not type str (Python 2), or not type bytes (Python 3).
# Attempt to unpack non-str type data in Python 2
>>> umsgpack.unpackb(u"no good")
...
TypeError: packed data must be type 'str' or 'bytearray'
>>>
# Attempt to unpack non-bytes type data in Python 3
>>> umsgpack.unpackb("no good")
...
TypeError: packed data must be type 'bytes' or 'bytearray'
>>>
InsufficientDataException
- exception umsgpack.InsufficientDataException[source]
Insufficient data to unpack the serialized object.
# Attempt to unpack a cut-off serialized 32-bit unsigned int
>>> umsgpack.unpackb(b"\xce\xff\xff\xff")
...
umsgpack.InsufficientDataException
>>>
# Attempt to unpack an array of length 2 missing the second item
>>> umsgpack.unpackb(b"\x92\xc2")
...
umsgpack.InsufficientDataException
>>>
InvalidStringException
- exception umsgpack.InvalidStringException[source]
Invalid UTF-8 string encountered during unpacking.
String bytes are strictly decoded with UTF-8. This exception is thrown if UTF-8
decoding of string bytes fails. Use the allow_invalid_utf8 option to unpack
invalid MessagePack strings into byte strings.
# Attempt to unpack invalid UTF-8 string
>>> umsgpack.unpackb(b"\xa2\x80\x81")
...
umsgpack.InvalidStringException: unpacked string is invalid utf-8
>>>
UnsupportedTimestampException
- exception umsgpack.UnsupportedTimestampException[source]
Unsupported timestamp format encountered during unpacking.
The official timestamp extension type supports 32-bit, 64-bit and 96-bit formats. This exception is thrown if a timestamp extension type with an unsupported format is encountered.
# Attempt to unpack invalid timestamp
>>> umsgpack.unpackb(b"\xd5\xff\x01\x02")
...
umsgpack.UnsupportedTimestampException: unsupported timestamp with data length 2
>>>
ReservedCodeException
- exception umsgpack.ReservedCodeException[source]
Reserved code encountered during unpacking.
# Attempt to unpack reserved code 0xc1
>>> umsgpack.unpackb(b"\xc1")
...
umsgpack.ReservedCodeException: encountered reserved code: 0xc1
>>>
UnhashableKeyException
- exception umsgpack.UnhashableKeyException[source]
Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.
Python dictionaries only support keys that are instances of
collections.abc.Hashable, so while the map { { u'abc': True } : 5 } has a
MessagePack serialization, it cannot be unpacked into a valid Python
dictionary.
# Attempt to unpack { {} : False }
>>> umsgpack.unpackb(b"\x81\x80\xc2")
...
umsgpack.UnhashableKeyException: encountered unhashable key: "{}" (<class 'dict'>)
>>>
DuplicateKeyException
- exception umsgpack.DuplicateKeyException[source]
Duplicate key encountered during map unpacking.
Python dictionaries do not support duplicate keys, but MessagePack maps may be serialized with duplicate keys.
# Attempt to unpack { 1: True, 1: False }
>>> umsgpack.unpackb(b"\x82\x01\xc3\x01\xc2")
...
umsgpack.DuplicateKeyException: encountered duplicate key: "1" (<class 'int'>)
>>>
MaximumDepthException
- exception umsgpack.MaximumDepthException[source]
Maximum nesting depth exceeded during unpacking.
This exception is thrown when the maximum nesting depth of unpacked arrays and
maps is exceeded, either by the max_depth option or by the interpreter’s
recursion limit.
# Attempt to unpack a deeply nested array
>>> umsgpack.unpackb(b'\x91' * 1000 + b'\xc0')
...
umsgpack.MaximumDepthException: maximum nesting depth exceeded
>>> umsgpack.unpackb(b'\x91\x91\x91\x91\x91\xc0', max_depth=3)
...
umsgpack.MaximumDepthException: maximum nesting depth exceeded
>>>
NotImplementedError
Ext serializable class is missing implementation of unpackb().
>>> @umsgpack.ext_serializable(0x50)
... class Point(collections.namedtuple('Point', ['x', 'y'])):
... pass
...
>>> umsgpack.unpackb(b'\xd7\x50\x00\x00\x00\x01\x00\x00\x00\x02')
...
NotImplementedError: Ext serializable class <class '__main__.Point'> is missing implementation of unpackb()
>>>