API

Packing

umsgpack.packb(obj, **options)

Serialize a Python object into MessagePack bytes.

Parameters:

obj – a Python object

Keyword Arguments:

• ext_handlers (dict) – dictionary of Ext handlers, mapping a custom type to a callable that packs an instance of the type into an Ext object

• force_float_precision (str) – “single” to force packing floats as IEEE-754 single-precision floats, “double” to force packing floats as IEEE-754 double-precision floats

Returns:

Serialized MessagePack bytes

Return type:

bytes

Raises:

UnsupportedTypeException(PackException) – Object type not supported for packing.

Example

>>> umsgpack.packb({u"compact": True, u"schema": 0})
b'\x82\xa7compact\xc3\xa6schema\x00'

Also available under the umsgpack.dumps() alias.

umsgpack.pack(obj, fp, **options)

Serialize a Python object into MessagePack bytes.

Parameters:

• obj – a Python object

• fp – a .write()-supporting file-like object

Keyword Arguments:

• ext_handlers (dict) – dictionary of Ext handlers, mapping a custom type to a callable that packs an instance of the type into an Ext object

• force_float_precision (str) – “single” to force packing floats as IEEE-754 single-precision floats, “double” to force packing floats as IEEE-754 double-precision floats

Returns:

None

Raises:

UnsupportedTypeException(PackException) – Object type not supported for packing.

Example

>>> f = open('test.bin', 'wb')
>>> umsgpack.pack({u"compact": True, u"schema": 0}, f)

Also available under the umsgpack.dump() alias.

Unpacking

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)

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.

Example

>>> umsgpack.unpackb(b'\x82\xa7compact\xc3\xa6schema\x00')
{'compact': True, 'schema': 0}

Also available under the umsgpack.loads() alias.

umsgpack.unpack(fp, **options)

Deserialize MessagePack bytes into a Python object.

Parameters:

fp – a .read()-supporting file-like object

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)

Returns:

Python object

Raises:

• 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.

Example

>>> f = open('test.bin', 'rb')
>>> umsgpack.unpackb(f)
{'compact': True, 'schema': 0}

Also available under the umsgpack.load() alias.

Packing Exceptions

exception umsgpack.PackException

Base class for exceptions encountered during packing.

exception umsgpack.UnsupportedTypeException

Object type not supported for packing.

Unpacking Exceptions

exception umsgpack.UnpackException

Base class for exceptions encountered during unpacking.

exception umsgpack.InsufficientDataException

Insufficient data to unpack the serialized object.

exception umsgpack.InvalidStringException

Invalid UTF-8 string encountered during unpacking.

exception umsgpack.UnsupportedTimestampException

Unsupported timestamp format encountered during unpacking.

exception umsgpack.ReservedCodeException

Reserved code encountered during unpacking.

exception umsgpack.UnhashableKeyException

Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.

exception umsgpack.DuplicateKeyException

Duplicate key encountered during map unpacking.

Ext Class

class umsgpack.Ext(type, data)

The Ext class facilitates creating a serializable extension object to store an application-defined type and data byte array.

__init__(type, data)

Construct a new Ext object.

Parameters:

• type (int) – application-defined type integer

• data (bytes) – application-defined data byte array

Raises:

• TypeError – Type is not an integer.

• ValueError – Type is out of range of -128 to 127.

• TypeError – Data is not type ‘bytes’ (Python 3) or not type ‘str’ (Python 2).

Example

>>> foo = umsgpack.Ext(5, b"\x01\x02\x03")
>>> umsgpack.packb({u"special stuff": foo, u"awesome": True})
'\x82\xa7awesome\xc3\xadspecial stuff\xc7\x03\x05\x01\x02\x03'
>>> bar = umsgpack.unpackb(_)
>>> print(bar["special stuff"])
Ext Object (Type: 5, Data: 01 02 03)

__eq__(other)

Compare this Ext object with another for equality.

__ne__(other)

Compare this Ext object with another for inequality.

__str__()

String representation of this Ext object.

__hash__()

Provide a hash of this Ext object.

Ext Serializable Decorator

@umsgpack.ext_serializable

Return a decorator to register a class for automatic packing and unpacking with the specified Ext type code. The application class should implement a packb() method that returns serialized bytes, and an unpackb() class method or static method that accepts serialized bytes and returns an instance of the application class.

Parameters:

ext_type (int) – application-defined Ext type code

Raises:

• TypeError – Ext type is not an integer.

• ValueError – Ext type is out of range of -128 to 127.

• ValueError – Ext type or class already registered.

Invalid String Class

class umsgpack.InvalidString

Subclass of bytes to hold invalid UTF-8 strings.

Attributes

umsgpack.compatibility = False

Compatibility mode boolean.

When compatibility mode is enabled, u-msgpack-python will serialize both unicode strings and bytes into the old “raw” msgpack type, and deserialize the “raw” msgpack type into bytes. This provides backwards compatibility with the old MessagePack specification.

Example

>>> umsgpack.compatibility = True
>>> umsgpack.packb([u"some string", b"some bytes"])
b'\x92\xabsome string\xaasome bytes'
>>> umsgpack.unpackb(_)
[b'some string', b'some bytes']

Constants

umsgpack.version = (2, 8, 0)

Module version tuple

umsgpack.__version__ = '2.8.0'

Module version string