API Reference¶

ormsgpack.packb(obj, /, default=None, option=None)¶

Serializes a Python object to a binary object in MessagePack format.

The global interpreter lock (GIL) is held for the duration of the call.

The serialization is based on the mappings defined in section Types.

Parameters:

obj (Any) – The object to serialize
default (Callable[[Any], Any] | None) – if set, a callable object for serializing objects that are not serializable. default is called with one argument, an object to serialize, and its return value is used as the serializable representation of the object. If the return value is not serializable, default is called recursively, up to 254 times
option (int | None) – if set, one of the OPT_* integer constants or a combination of them using the bitwise OR operator

Raises:

MsgpackEncodeError – if an object is not serializable
MsgpackEncodeError – if a str instance contains surrogate code points and OPT_REPLACE_SURROGATES is not specified
MsgpackEncodeError – if a dict key is not a str instance and OPT_NON_STR_KEYS is not specified
MsgpackEncodeError – if default is called recursively more than 254 times
MsgpackEncodeError – if an object contains a circular reference
MsgpackEncodeError – if a datetime.datetime.tzinfo attribute is of an unsupported type

Return type:

bytes

ormsgpack.unpackb(obj, /, *, ext_hook=None, option=None)¶

Deserializes a binary object in MessagePack format to a Python object.

The global interpreter lock (GIL) is held for the duration of the call.

The deserialization is based on the following mappings:

nil is deserialized as the None object
boolean objects are deserialized as bool instances
integer objects are deserialized as int instances
float objects are deserialized as float instances
string objects are deserialized as str instances
binary objects are deserialized as bytes instances
array objects are deserialized as tuple instances, if the object is a map key, and as list instances otherwise
map objects are deserialized as dict instances
timestamp extension objects are deserialized as UTC datetime.datetime instances, if OPT_DATETIME_AS_TIMESTAMP_EXT is specified

Parameters:

obj (bytes | bytearray | memoryview) – The object to deserialize
ext_hook (Callable[[int, bytes], Any] | None) – if set, a callable object for deserializing extension types. ext_hook is called with two arguments, the extension type and value, and its return value is used as the deserialized object
option (int | None) – if set, OPT_DATETIME_AS_TIMESTAMP_EXT, OPT_NON_STR_KEYS or their combination using the bitwise OR operator

Raises:

MsgpackDecodeError – if the object is of an invalid type or is not valid MessagePack
MsgpackDecodeError – if a map key is not a string and OPT_NON_STR_KEYS is not specified

Return type:

Any

exception ormsgpack.MsgpackEncodeError¶: a subclass of TypeError

exception ormsgpack.MsgpackDecodeError¶: a subclass of ValueError

ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT¶

In packb(), serialize aware datetime.datetime instances as timestamp extension objects

In unpackb(), deserialize timestamp extension objects to UTC datetime.datetime instances

ormsgpack.OPT_NAIVE_UTC¶

Serialize naive datetime.datetime objects and numpy.datetime64 objects as UTC. This has no effect on aware datetime.datetime objects.

>>> import ormsgpack, datetime
>>> ormsgpack.packb(
...     datetime.datetime(1970, 1, 1, 0, 0, 0),
... )
b'\xb31970-01-01T00:00:00'
>>> ormsgpack.unpackb(_)
'1970-01-01T00:00:00'
>>> ormsgpack.packb(
...     datetime.datetime(1970, 1, 1, 0, 0, 0),
...     option=ormsgpack.OPT_NAIVE_UTC,
... )
b'\xb91970-01-01T00:00:00+00:00'
>>> ormsgpack.unpackb(_)
'1970-01-01T00:00:00+00:00'

ormsgpack.OPT_NON_STR_KEYS¶

In packb(), serialize dict keys of type None, bool, int, float, str, bytes, datetime.date, datetime.time, datetime.datetime, enum.Enum, and uuid.UUID. All options other than the passthrough ones are supported. dict keys of unsupported types are not handled using default and result in MsgpackEncodeError being raised.

In unpackb(), deserialize map keys of type other than string. Be aware that this option is considered unsafe and disabled by default in msgpack due to the possibility of a Hash DoS.

>>> import ormsgpack
>>>
>>> ormsgpack.packb(
...     {0: [1, 2], 1.0: [3, 4]},
... )
TypeError: Dict key must be str
>>> ormsgpack.packb(
...     {0: [1, 2], 1.0: [3, 4]},
...     option=ormsgpack.OPT_NON_STR_KEYS,
... )
b'\x82\x00\x92\x01\x02\xcb?\xf0\x00\x00\x00\x00\x00\x00\x92\x03\x04'
>>> ormsgpack.unpackb(_, option=ormsgpack.OPT_NON_STR_KEYS)
{0: [1, 2], 1.0: [3, 4]}

This option is not compatible with OPT_SORT_KEYS.

ormsgpack.OPT_OMIT_MICROSECONDS¶

Do not serialize the microsecond component of datetime.datetime, datetime.time and numpy.datetime64 instances.

>>> import ormsgpack, datetime
>>> ormsgpack.packb(
...     datetime.datetime(1970, 1, 1, 0, 0, 0, 1),
... )
b'\xba1970-01-01T00:00:00.000001'
>>> ormsgpack.unpackb(_)
'1970-01-01T00:00:00.000001'
>>> ormsgpack.packb(
...     datetime.datetime(1970, 1, 1, 0, 0, 0, 1),
...     option=ormsgpack.OPT_OMIT_MICROSECONDS,
... )
b'\xb31970-01-01T00:00:00'
>>> ormsgpack.unpackb(_)
'1970-01-01T00:00:00'

ormsgpack.OPT_PASSTHROUGH_BIG_INT¶

Enable passthrough of int instances smaller than -9223372036854775807 or larger than 18446744073709551615 to default.

>>> import ormsgpack
>>> def default(obj):
...     if isinstance(obj, int):
...         return ormsgpack.Ext(0, obj.to_bytes(9))
...     raise TypeError
...
>>> ormsgpack.packb(2**65)
TypeError: Integer exceeds 64-bit range
>>> ormsgpack.packb(
...     2**65,
...     option=ormsgpack.OPT_PASSTHROUGH_BIG_INT,
...     default=default,
... )
b'\xc7\t\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00'

ormsgpack.OPT_PASSTHROUGH_DATACLASS¶: Enable passthrough of dataclasses to default.

ormsgpack.OPT_PASSTHROUGH_DATETIME¶: Enable passthrough of datetime.datetime, datetime.date, and datetime.time instances to default.

ormsgpack.OPT_PASSTHROUGH_ENUM¶: Enable passthrough of enum members to default.

ormsgpack.OPT_PASSTHROUGH_SUBCLASS¶: Enable passthrough of subclasses of str, int, dict and list to default.

ormsgpack.OPT_PASSTHROUGH_TUPLE¶: Enable passthrough of tuple instances to default.

ormsgpack.OPT_PASSTHROUGH_UUID¶: Enable passthrough of uuid.UUID instances to default.

ormsgpack.OPT_REPLACE_SURROGATES¶: Serialize str instances that contain surrogate code points by replacing the surrogates with the ? character.

ormsgpack.OPT_SERIALIZE_NUMPY¶: Serialize instances of numpy types.

ormsgpack.OPT_SERIALIZE_PYDANTIC¶: Serialize pydantic.BaseModel instances.

ormsgpack.OPT_SORT_KEYS¶

Serialize dict keys and pydantic model fields in sorted order. The default is to serialize in an unspecified order.

This can be used to ensure the order is deterministic for hashing or tests. It has a substantial performance penalty and is not recommended in general.

>>> import ormsgpack
>>> ormsgpack.packb({"b": 1, "c": 2, "a": 3})
b'\x83\xa1b\x01\xa1c\x02\xa1a\x03'
>>> ormsgpack.packb({"b": 1, "c": 2, "a": 3}, option=ormsgpack.OPT_SORT_KEYS)
b'\x83\xa1a\x03\xa1b\x01\xa1c\x02'

The sorting is not collation/locale-aware:

>>> import ormsgpack
>>> ormsgpack.packb({"a": 1, "ä": 2, "A": 3}, option=ormsgpack.OPT_SORT_KEYS)
b'\x83\xa1A\x03\xa1a\x01\xa2\xc3\xa4\x02'

This option is not supported for dataclasses.

ormsgpack.OPT_UTC_Z¶

Serialize a UTC timezone on datetime.datetime and numpy.datetime64 instances as Z instead of +00:00.

>>> import ormsgpack, datetime
>>> ormsgpack.packb(
...     datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc),
... )
b'\xb91970-01-01T00:00:00+00:00'
>>> ormsgpack.packb(
...     datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=datetime.timezone.utc),
...     option=ormsgpack.OPT_UTC_Z,
... )
b'\xb41970-01-01T00:00:00Z'

class ormsgpack.Ext(tag: int, data: bytes)¶: A class whose Instances are serialized as MessagePack extension types. The instantiation arguments are an integer in the range [0, 127] and a bytes object, defining the type and value, respectively