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, MaximumDepthException is raised. If None (default), depth is bounded only by the interpreter’s recursion limit.

Returns:

Python object

Raises:

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()
>>>