Types¶

none¶

The None object is serialized as nil.

bool¶

bool instances are serialized as booleans.

int¶

Instances of int and of subclasses of int are serialized as integers. The minimum and maximum representable values are -9223372036854775807 and 18446744073709551615, respectively.

float¶

float instances are serialized as IEEE 754 double precision floating point numbers.

str¶

Instances of str and of subclasses of str are serialized as strings.

bytes¶

bytes, bytearray and memoryview instances are serialized as binary objects.

list¶

Instances of list and of subclasses of list are serialized as arrays.

tuple¶

tuple instances are serialized as arrays.

dict¶

Instances of dict and of subclasses of dict are serialized as maps.

dataclass¶

dataclasses are serialized as maps. The fields are serialized in the order they are defined in the class. All variants of dataclasses are supported, including dataclasses with object.__slots__, frozen dataclasses and dataclasses with descriptor-typed fields.

>>> import ormsgpack, dataclasses
>>> @dataclasses.dataclass
... class Group:
...     name: str
...     uid: int
...
>>> @dataclasses.dataclass
... class User:
...     name: str
...     uid: int
...     groups: list[Group]
...     active: bool = True
...
>>> ormsgpack.packb(
...     User(name="a", uid=0, groups=[Group(name="b", uid=1)]),
... )
b'\x84\xa4name\xa1a\xa3uid\x00\xa6groups\x91\x82\xa4name\xa1b\xa3uid\x01\xa6active\xc3'
>>> ormsgpack.unpackb(_)
{'name': 'a', 'uid': 0, 'groups': [{'name': 'b', 'uid': 1}], 'active': True}

date¶

datetime.date instances are serialized as RFC 3339 strings.

>>> import ormsgpack, datetime
>>> ormsgpack.packb(datetime.date(1900, 1, 2))
b'\xaa1900-01-02'
>>> ormsgpack.unpackb(_)
'1900-01-02'

time¶

Naive datetime.time instances are serialized as RFC 3339 strings. Aware datetime.time instances are not supported.

>>> import ormsgpack, datetime
>>> ormsgpack.packb(datetime.time(12, 0, 15, 290))
b'\xaf12:00:15.000290'
>>> ormsgpack.unpackb(_)
'12:00:15.000290'

datetime¶

Naive datetime.datetime instances are serialized as RFC 3339 strings. Aware datetime.datetime instances are serialized as RFC 3339 strings or alternatively as MessagePack timestamp extension objects, by using the ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT option.

>>> import ormsgpack, datetime, zoneinfo
>>> tzinfo = zoneinfo.ZoneInfo("Asia/Tokyo")
>>>
>>> ormsgpack.packb(datetime.datetime(2018, 12, 1, 2, 3))
b'\xb32018-12-01T02:03:00'
>>> ormsgpack.unpackb(_)
'2018-12-01T02:03:00'
>>>
>>> ormsgpack.packb(datetime.datetime(2018, 12, 1, 2, 3, tzinfo=tzinfo))
b'\xb92018-12-01T02:03:00+09:00'
>>> ormsgpack.unpackb(_)
'2018-12-01T02:03:00+09:00'
>>>
>>> ormsgpack.packb(
...     datetime.datetime(2018, 12, 1, 2, 3, tzinfo=tzinfo),
...     option=ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT,
... )
b'\xd6\xff\\\x01mD'
>>> ormsgpack.unpackb(_, option=ormsgpack.OPT_DATETIME_AS_TIMESTAMP_EXT)
datetime.datetime(2018, 11, 30, 17, 3, tzinfo=datetime.timezone.utc)

Errors with datetime.datetime.tzinfo result in ormsgpack.MsgpackEncodeError being raised.

The serialization can be customized using the ormsgpack.OPT_NAIVE_UTC, ormsgpack.OPT_OMIT_MICROSECONDS, and ormsgpack.OPT_UTC_Z options.

enum¶

Enum members are serialized as their values. Options apply to their values. All subclasses of enum.Enum are supported.

>>> import ormsgpack, enum
>>> class Action(enum.Enum):
...     ALLOW = 1
...     DENY = 2
...
>>> ormsgpack.packb(Action.ALLOW)
b'\x01'
>>> ormsgpack.unpackb(_)
1

uuid¶

uuid.UUID instances are serialized as RFC 4122 strings.

>>> import ormsgpack, uuid
>>> ormsgpack.packb(uuid.uuid5(uuid.NAMESPACE_DNS, "python.org"))
b'\xd9$886313e1-3b8a-5372-9b90-0c9aee199e5d'
>>> ormsgpack.unpackb(_)
'886313e1-3b8a-5372-9b90-0c9aee199e5d'

numpy¶

numpy.bool, numpy.float16, numpy.float32, numpy.float64, numpy.int8, numpy.int16, numpy.int32, numpy.int64, numpy.intp, numpy.uint8, numpy.uint16, numpy.uint32, numpy.uint64, numpy.uintp instances are serialized as the corresponding builtin types.

numpy.datetime64 instances are serialized as RFC 3339 strings. The serialization can be customized using the ormsgpack.OPT_NAIVE_UTC, ormsgpack.OPT_OMIT_MICROSECONDS, and ormsgpack.OPT_UTC_Z options.

numpy.ndarray instances are serialized as arrays. The array must be a C-contiguous array (C_CONTIGUOUS) and of a supported data type. Unsupported arrays can be serialized using default, by converting the array to a list with the numpy.ndarray.tolist() method.

The serialization of numpy types is disabled by default and can be enabled by using the ormsgpack.OPT_SERIALIZE_NUMPY option.

>>> import ormsgpack, numpy
>>> ormsgpack.packb(
...     numpy.array([[1, 2, 3], [4, 5, 6]]),
...     option=ormsgpack.OPT_SERIALIZE_NUMPY,
... )
b'\x92\x93\x01\x02\x03\x93\x04\x05\x06'
>>> ormsgpack.unpackb(_)
[[1, 2, 3], [4, 5, 6]]

pydantic¶

pydantic.BaseModel instances are serialized as maps, with duck-typing. This is equivalent to serializing model.model_dump(serialize_as_any=True) with Pydantic V2 or model.dict()with Pydantic V1.

The serialization of pydantic models is disabled by default and can be enabled by using the ormsgpack.OPT_SERIALIZE_PYDANTIC option.

>>> import ormsgpack, pydantic
>>> class Group(pydantic.BaseModel):
...     name: str
...     uid: int
...
>>> class User(pydantic.BaseModel):
...     name: str
...     uid: int
...     groups: list[Group]
...     active: bool = True
...
>>> ormsgpack.packb(
...     User(name="a", uid=0, groups=[Group(name="b", uid=1)]),
...     option=ormsgpack.OPT_SERIALIZE_PYDANTIC,
... )
b'\x84\xa4name\xa1a\xa3uid\x00\xa6groups\x91\x82\xa4name\xa1b\xa3uid\x01\xa6active\xc3'
>>> ormsgpack.unpackb(_)
{'name': 'a', 'uid': 0, 'groups': [{'name': 'b', 'uid': 1}], 'active': True}