Welcome to AMsgPack’s documentation!

It’s like JSON. but fast and small.

>>> from amsgpack import packb, unpackb
>>> packb({"compact": True, "schema": 0})
b'\x82\xa7compact\xc3\xa6schema\x00'
>>> unpackb(b'\x82\xa7compact\xc3\xa6schema\x00')
{'compact': True, 'schema': 0}
class amsgpack.Ext(code, data)

Ext type from MessagePack specification

>>> from amsgpack import Ext, packb
>>> packb(Ext(code=95, data=b'amsgpack'))
b'\xd7_amsgpack'
code

Ext code (int)

data

Ext data (bytes)

default()

Returns datetime.datetime object, when code equals -1 and data size is 4, 8 or 12

is_timestamp()

Returns True when code equals -1 and data’s size is 4, 8 or 12

to_datetime()

Converts data to datetime.datetime

to_timestamp()

Converts data to amsgpack.Timestamp

class amsgpack.FileUnpacker(file, read_size, tuple=False, ext_hook=None)

Iteratively unpack binary stream to python objects:

>>> from amsgpack import FileUnpacker
>>> from io import BytesIO
>>> for data in FileUnpacker(BytesIO(b'\x00\x01\x02')):
...     print(data)
...
0
1
2
class amsgpack.Packer(default=None)

Class for holding default callback for unpackb() to use. The amsgpack.packb function is created using:

packb = Packer().packb

Default callback example:

>>> from typing import Any
>>> from amsgpack import Ext, Packer
>>> from array import array
>>>
>>> def default(value: Any) -> Ext:
...     if isinstance(value, array):
...         return Ext(1, value.tobytes())
...     raise ValueError(f"Unserializable object: {value}")
...
>>> packb = Packer(default=default).packb
>>> packb(array('I', [0xBA, 0xDE]))
b'\xd7\x01\xba\x00\x00\x00\xde\x00\x00\x00'
packb(obj, /)

Serialize obj to a MessagePack formatted bytes.

class amsgpack.Raw(data)

Raw type for packb(). When packer sees Raw type, it inserts its data as is.

>>> from amsgpack import Raw, packb
>>> packb(Raw(b'Hello'))
b'Hello'
data

Raw data (bytes)

class amsgpack.Timestamp(seconds, nanoseconds)

Timestamp extension type from MessagePack specification:

>>> from amsgpack import Timestamp, packb
>>> ts = Timestamp(seconds=1752955664)
>>> ts
Timestamp(seconds=1752955664, nanoseconds=0)
>>> packb(ts)
b'\xd6\xffh{\xfb\x10'
>>> unpackb(packb(ts))
datetime.datetime(2025, 7, 19, 20, 7, 44, tzinfo=datetime.timezone.utc)

See ext_hook on how to return Timestamp instead of datetime.datetime

nanoseconds

32-bit unsigned int

seconds

64-bit signed int

class amsgpack.Unpacker(tuple=False, ext_hook=None)

Unpack bytes to python objects.

The optional tuple argument tells the Unpacker to output sequences as tuple instead of list. The amsgpack.unpackb function is created using:

unpackb = Unpacker().unpackb

ext_hook example:

>>> from amsgpack import Ext, Unpacker
>>> from array import array
>>>
>>> def ext_hook(ext: Ext):
...     if ext.code == 1:
...         return array("I", ext.data)
...     return ext.default()
...
>>> Unpacker(ext_hook=ext_hook).unpackb(
...     b"\xd7\x01\xba\x00\x00\x00\xde\x00\x00\x00"
... )
array('I', [186, 222])
feed(bytes, /)

Append bytes to internal queue.

reset()

Cleans up internal queue, that was filled by feed() method and and cleans up stack, that might’ve been filled by __next__()

unpackb(data, /)

Deserialize data (a bytes object) to a Python object. By calling ‘__next__’ one time and ensuring there’s no more data

amsgpack.packb(obj, /)

Serialize obj to a MessagePack formatted bytes.

amsgpack.unpackb(data, /)

Deserialize data (a bytes object) to a Python object. By calling ‘__next__’ one time and ensuring there’s no more data

Indices and tables