API reference

msgpack.pack(o, stream, **kwargs)

Pack object o and write it to stream

See Packer for options.

dump() is alias for pack()

msgpack.packb(o, **kwargs)

Pack object o and return packed bytes

See Packer for options.

dumps() is alias for packb()

msgpack.unpack(stream, **kwargs)

Unpack an object from stream.

Raises ExtraData when stream contains extra bytes. See Unpacker for options.

load() is alias for unpack()

msgpack.unpackb(packed, **kwargs)

Unpack an object from packed.

Raises ExtraData when packed contains extra bytes. Raises ValueError when packed is incomplete. Raises FormatError when packed is not valid msgpack. Raises StackError when packed contains too nested. Other exceptions can be raised during unpacking.

See Unpacker for options.

loads() is alias for unpackb()

class msgpack.Packer(default=None, encoding=None, unicode_errors=None, use_single_float=False, autoreset=True, use_bin_type=False, strict_types=False)

MessagePack Packer

usage:

packer = Packer() astream.write(packer.pack(a)) astream.write(packer.pack(b))

Packer’s constructor has some keyword arguments:

Parameters:
  • default (callable) – Convert user type to builtin type that Packer supports. See also simplejson’s document.
  • use_single_float (bool) – Use single precision float type for float. (default: False)
  • autoreset (bool) – Reset buffer after each pack and return its content as bytes. (default: True). If set this to false, use bytes() to get content and .reset() to clear buffer.
  • use_bin_type (bool) – Use bin type introduced in msgpack spec 2.0 for bytes. It also enables str8 type for unicode.
  • strict_types (bool) – If set to true, types will be checked to be exact. Derived classes from serializeable types will not be serialized and will be treated as unsupported type and forwarded to default. Additionally tuples will not be serialized as lists. This is useful when trying to implement accurate serialization for python types.
  • encoding (str) – (deprecated) Convert unicode to bytes with this encoding. (default: ‘utf-8’)
  • unicode_errors (str) – Error handler for encoding unicode. (default: ‘strict’)
bytes()

Return internal buffer contents as bytes object

getbuffer()

Return view of internal buffer.

reset()

Reset internal buffer.

This method is usaful only when autoreset=False.

class msgpack.Unpacker(file_like=None, read_size=0, use_list=True, raw=True, strict_map_key=False, object_hook=None, object_pairs_hook=None, list_hook=None, encoding=None, unicode_errors=None, max_buffer_size=0, ext_hook=<class 'msgpack.ExtType'>, max_str_len=1048576, max_bin_len=1048576, max_array_len=131072, max_map_len=32768, max_ext_len=1048576)

Streaming unpacker.

arguments:

Parameters:
  • file_like – File-like object having .read(n) method. If specified, unpacker reads serialized data from it and feed() is not usable.
  • read_size (int) – Used as file_like.read(read_size). (default: min(16*1024, max_buffer_size))
  • use_list (bool) – If true, unpack msgpack array to Python list. Otherwise, unpack to Python tuple. (default: True)
  • raw (bool) –

    If true, unpack msgpack raw to Python bytes (default). Otherwise, unpack to Python str (or unicode on Python 2) by decoding with UTF-8 encoding (recommended). Currently, the default is true, but it will be changed to false in near future. So you must specify it explicitly for keeping backward compatibility.

    encoding option which is deprecated overrides this option.

  • strict_map_key (bool) – If true, only str or bytes are accepted for map (dict) keys. It’s False by default for backward-compatibility. But it will be True from msgpack 1.0.
  • object_hook (callable) – When specified, it should be callable. Unpacker calls it with a dict argument after unpacking msgpack map. (See also simplejson)
  • object_pairs_hook (callable) – When specified, it should be callable. Unpacker calls it with a list of key-value pairs after unpacking msgpack map. (See also simplejson)
  • encoding (str) – Encoding used for decoding msgpack raw. If it is None (default), msgpack raw is deserialized to Python bytes.
  • unicode_errors (str) – (deprecated) Used for decoding msgpack raw with encoding. (default: ‘strict’)
  • max_buffer_size (int) – Limits size of data waiting unpacked. 0 means system’s INT_MAX (default). Raises BufferFull exception when it is insufficient. You should set this parameter when unpacking data from untrusted source.
  • max_str_len (int) – Limits max length of str. (default: 1024*1024)
  • max_bin_len (int) – Limits max length of bin. (default: 1024*1024)
  • max_array_len (int) – Limits max length of array. (default: 128*1024)
  • max_map_len (int) – Limits max length of map. (default: 32*1024)
  • max_ext_len (int) – Limits max size of ext type. (default: 1024*1024)

example of streaming deserialize from file-like object:

unpacker = Unpacker(file_like, raw=False)
for o in unpacker:
    process(o)

example of streaming deserialize from socket:

unpacker = Unpacker(raw=False)
while True:
    buf = sock.recv(1024**2)
    if not buf:
        break
    unpacker.feed(buf)
    for o in unpacker:
        process(o)

Raises ExtraData when packed contains extra bytes. Raises OutOfData when packed is incomplete. Raises FormatError when packed is not valid msgpack. Raises StackError when packed contains too nested. Other exceptions can be raised during unpacking.

class msgpack.ExtType

ExtType represents ext type in msgpack.

exceptions

These exceptions are accessible via msgpack package. (For example, msgpack.OutOfData is shortcut for msgpack.exceptions.OutOfData)

exception msgpack.exceptions.BufferFull

Bases: msgpack.exceptions.UnpackException

exception msgpack.exceptions.ExtraData(unpacked, extra)

Bases: ValueError

ExtraData is raised when there is trailing data.

This exception is raised while only one-shot (not streaming) unpack.

exception msgpack.exceptions.FormatError

Bases: ValueError, msgpack.exceptions.UnpackException

Invalid msgpack format

exception msgpack.exceptions.OutOfData

Bases: msgpack.exceptions.UnpackException

exception msgpack.exceptions.StackError

Bases: ValueError, msgpack.exceptions.UnpackException

Too nested

exception msgpack.exceptions.UnpackException

Bases: Exception

Base class for some exceptions raised while unpacking.

NOTE: unpack may raise exception other than subclass of UnpackException. If you want to catch all error, catch Exception instead.