`umsgpack` – MessagePack encoding and decoding¶

Version:: 2.8.0
Author:: vsergeev / Ivan (Vanya) A. Sergeev
Source:: https://github.com/vsergeev/u-msgpack-python
License:: MIT

Overview¶

u-msgpack-python is a lightweight MessagePack serializer and deserializer module that is:

Compatible with both Python 2 and 3
Compatible with CPython and PyPy implementations
Fully compliant with the latest MessagePack specification
Supports binary, UTF-8 string, and application extension types

The module provides a simple API for serializing Python objects to MessagePack format and deserializing MessagePack data back to Python objects.

Quick Start¶

import umsgpack

# Serialize a Python object to bytes
packed = umsgpack.packb({"compact": True, "schema": 0})

# Deserialize MessagePack bytes back to Python object
unpacked = umsgpack.unpackb(packed)

# Work with files
with open('data.msgpack', 'wb') as f:
    umsgpack.pack({"hello": "world"}, f)

with open('data.msgpack', 'rb') as f:
    data = umsgpack.unpack(f)

Installation¶

The module is a single Python file. Simply download umsgpack.py and import it in your project.

API Reference¶

Main Functions¶

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

Serialize a Python object into MessagePack format and write to a file-like object.

Parameters:

obj – Python object to serialize
fp – File-like object with a .write() method
**options – Additional packing options (see below)

Raises:

UnsupportedTypeException – Object type not supported for packing

umsgpack.packb(obj, **options)¶

Serialize a Python object into MessagePack bytes.

Parameters:

obj – Python object to serialize
**options – Additional packing options (see below)

Returns:

Serialized MessagePack bytes

Raises:

UnsupportedTypeException – Object type not supported for packing

umsgpack.unpack(fp, **options)¶

Deserialize MessagePack data from a file-like object into a Python object.

Parameters:

fp – File-like object with a .read() method
**options – Additional unpacking options (see below)

Returns:

Deserialized Python object

Raises:

UnpackException – Various unpacking errors (see Exceptions section)

umsgpack.unpackb(s, **options)¶

Deserialize MessagePack bytes into a Python object.

Parameters:

s – Serialized MessagePack bytes (bytes or bytearray)
**options – Additional unpacking options (see below)

Returns:

Deserialized Python object

Raises:

UnpackException – Various unpacking errors (see Exceptions section)

Aliases¶

For convenience, the module provides aliases that match the pickle module API:

dump = pack
dumps = packb
load = unpack
loads = unpackb

Configuration Variables¶

umsgpack.compatibility¶

Compatibility mode boolean.

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

Default: False

umsgpack.compatibility = True
packed = umsgpack.packb(["some string", b"some bytes"])
# Both strings and bytes are packed as raw type
unpacked = umsgpack.unpackb(packed)
# Both are returned as bytes

umsgpack.version¶: Module version tuple (2, 8, 0)

umsgpack.__version__¶: Module version string “2.8.0”

Extension Types¶

Extension Types System¶

u-msgpack-python supports MessagePack’s extension types through two mechanisms:

Manual handling using the Ext class
Automatic registration using the ext_serializable decorator

class umsgpack.Ext(type, data)¶

Container for MessagePack extension type objects.

Parameters:

type – Application-defined type integer (-128 to 127)
data – Application-defined data byte array

Raises:

TypeError – Type is not integer or data has wrong type
ValueError – Type is out of range

__init__(type, data)¶: Construct a new Ext object.

__eq__(other)¶: Compare Ext objects for equality.

__str__()¶: String representation of the Ext object.

__hash__()¶: Provide a hash of the Ext object.

umsgpack.ext_serializable(ext_type)¶

Decorator to register a class for automatic packing and unpacking.

Parameters:

ext_type – Application-defined Ext type code (-128 to 127)

Returns:

Decorator function

Raises:

TypeError – Ext type is not integer
ValueError – Ext type out of range or already registered

The decorated class must implement:

A packb() method that returns serialized bytes
An unpackb() class/static method that accepts bytes and returns an instance

@umsgpack.ext_serializable(5)
class MyClass:
    def __init__(self, value):
        self.value = value

    def packb(self):
        return str(self.value).encode('utf-8')

    @staticmethod
    def unpackb(data):
        return MyClass(int(data.decode('utf-8')))

# Now MyClass instances are automatically serialized/deserialized
obj = MyClass(42)
packed = umsgpack.packb(obj)
unpacked = umsgpack.unpackb(packed)

Packing Options¶

The following keyword arguments can be passed to packing functions:

ext_handlers

Dictionary mapping custom types to callables that pack instances into Ext objects.

def pack_myobj(obj):
    return umsgpack.Ext(10, obj.serialize())

umsgpack.packb(myobj, ext_handlers={MyClass: pack_myobj})

force_float_precision

Force specific float precision:

"single": IEEE-754 single-precision (32-bit) floats
"double": IEEE-754 double-precision (64-bit) floats

Default: Auto-detected based on system

Unpacking Options¶

The following keyword arguments can be passed to unpacking functions:

ext_handlers

Dictionary mapping integer Ext types to callables that unpack Ext instances.

def unpack_myext(ext):
    return MyClass.deserialize(ext.data)

umsgpack.unpackb(data, ext_handlers={10: unpack_myext})

use_ordered_dict

Unpack maps into collections.OrderedDict instead of regular dict.

Default: False

use_tuple

Unpack arrays into tuples instead of lists.

Default: False

allow_invalid_utf8

Unpack invalid UTF-8 strings into InvalidString instances (subclass of bytes) instead of raising InvalidStringException.

Default: False

Supported Data Types¶

The following Python types are supported for serialization:

Basic Types¶

None (serialized as nil)
bool
int (including Python 2 long)
float
str (UTF-8 strings)
bytes (binary data)

Collections¶

list
tuple (serialized as array)
dict

Special Types¶

datetime.datetime (serialized as timestamp extension)
umsgpack.Ext (extension types)

Exceptions¶

All exceptions inherit from either PackException or UnpackException.

Packing Exceptions¶

exception umsgpack.PackException¶: Base class for packing exceptions.

exception umsgpack.UnsupportedTypeException(PackException)¶: Object type not supported for packing.

Unpacking Exceptions¶

exception umsgpack.UnpackException¶: Base class for unpacking exceptions.

exception umsgpack.InsufficientDataException(UnpackException)¶: Insufficient data to unpack the serialized object.

exception umsgpack.InvalidStringException(UnpackException)¶: Invalid UTF-8 string encountered during unpacking.

exception umsgpack.UnsupportedTimestampException(UnpackException)¶: Unsupported timestamp format encountered during unpacking.

exception umsgpack.ReservedCodeException(UnpackException)¶: Reserved code encountered during unpacking.

exception umsgpack.UnhashableKeyException(UnpackException)¶: Unhashable key encountered during map unpacking.

exception umsgpack.DuplicateKeyException(UnpackException)¶: Duplicate key encountered during map unpacking.

Backwards Compatibility¶

For compatibility with older code:

KeyNotPrimitiveException = UnhashableKeyException
KeyDuplicateException = DuplicateKeyException

Examples¶

Basic Usage¶

import umsgpack

# Simple serialization
data = {
    "name": "John Doe",
    "age": 30,
    "hobbies": ["reading", "hiking", "coding"],
    "metadata": {
        "created": datetime.datetime.now(),
        "version": 1.0
    }
}

# Serialize to bytes
packed = umsgpack.packb(data)

# Deserialize back
unpacked = umsgpack.unpackb(packed)

Working with Files¶

import umsgpack

# Write to file
with open('data.msgpack', 'wb') as f:
    umsgpack.pack({"test": [1, 2, 3]}, f)

# Read from file
with open('data.msgpack', 'rb') as f:
    data = umsgpack.unpack(f)

Custom Types with Extension System¶

import umsgpack
import datetime

# Manual extension handling
class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def pack(self):
        return struct.pack('>ii', self.x, self.y)

    @classmethod
    def unpack(cls, data):
        x, y = struct.unpack('>ii', data)
        return cls(x, y)

# Pack with manual handler
def pack_point(obj):
    return umsgpack.Ext(1, obj.pack())

point = Point(10, 20)
packed = umsgpack.packb(point, ext_handlers={Point: pack_point})

# Unpack with manual handler
def unpack_point(ext):
    return Point.unpack(ext.data)

unpacked = umsgpack.unpackb(packed, ext_handlers={1: unpack_point})

Notes¶

The module automatically handles timezone-aware and naive datetime objects
When using compatibility mode, all strings are returned as bytes
For maximum performance with large data, use the file-based API (pack/unpack)
Extension type codes -128 to 127 are available for application use
Type code -1 is reserved for timestamp extension

`umsgpack` – MessagePack encoding and decoding¶

Overview¶

Quick Start¶

Installation¶

API Reference¶

Main Functions¶

Aliases¶

Configuration Variables¶

Extension Types¶

Extension Types System¶

Packing Options¶

Unpacking Options¶

Supported Data Types¶

Basic Types¶

Collections¶

Special Types¶

Exceptions¶

Packing Exceptions¶

Unpacking Exceptions¶

Backwards Compatibility¶

Examples¶

Basic Usage¶

Working with Files¶

Custom Types with Extension System¶

Notes¶

See Also¶

Table of Contents

Previous topic

Next topic

This Page

umsgpack – MessagePack encoding and decoding¶

Overview¶

Quick Start¶

Installation¶

API Reference¶

Main Functions¶

Aliases¶

Configuration Variables¶

Extension Types¶

Extension Types System¶

Packing Options¶

Unpacking Options¶

Supported Data Types¶

Basic Types¶

Collections¶

Special Types¶

Exceptions¶

Packing Exceptions¶

Unpacking Exceptions¶

Backwards Compatibility¶

Examples¶

Basic Usage¶

Working with Files¶

Custom Types with Extension System¶

Notes¶

See Also¶

`umsgpack` – MessagePack encoding and decoding¶