MessagePack for Python

这是什么

MessagePack 是一种高效的二进制序列化格式。它允许您在多种语言之间交换数据，就像JSON一样。但它的速度更快，体积更小。此软件包提供用于读取和写入MessagePack数据的CPython绑定。

安装

$ pip install msgpack

纯Python实现

msgpack中的扩展模块（msgpack._cmsgpack）不支持PyPy。

但是msgpack为PyPy提供了一个纯Python实现（msgpack.fallback）。

Windows

当您无法使用二进制发行版时，您需要在Windows上安装Visual Studio或Windows SDK。没有扩展，CPython上使用纯Python实现会运行得较慢。

如何使用

一次性打包和解包

使用packb进行打包，使用unpackb进行解包。msgpack提供dumps和loads作为与json和pickle兼容的别名。

pack和dump将数据打包到文件对象。unpack和load从文件对象解包。

>>> import msgpack
>>> msgpack.packb([1, 2, 3])
'\x93\x01\x02\x03'
>>> msgpack.unpackb(_)
[1, 2, 3]

阅读文档字符串以获取选项。

流式解包

Unpacker 是一种 "流式解包器"。它可以从一个流（或通过其 feed 方法提供的字节）中解包多个对象。

import msgpack
from io import BytesIO

buf = BytesIO()
for i in range(100):
   buf.write(msgpack.packb(i))

buf.seek(0)

unpacker = msgpack.Unpacker(buf)
for unpacked in unpacker:
    print(unpacked)

自定义数据类型的打包/解包

还可以对自定义数据类型进行打包/解包。以下是一个关于 datetime.datetime 的示例。

import datetime
import msgpack

useful_dict = {
    "id": 1,
    "created": datetime.datetime.now(),
}

def decode_datetime(obj):
    if '__datetime__' in obj:
        obj = datetime.datetime.strptime(obj["as_str"], "%Y%m%dT%H:%M:%S.%f")
    return obj

def encode_datetime(obj):
    if isinstance(obj, datetime.datetime):
        return {'__datetime__': True, 'as_str': obj.strftime("%Y%m%dT%H:%M:%S.%f")}
    return obj


packed_dict = msgpack.packb(useful_dict, default=encode_datetime)
this_dict_again = msgpack.unpackb(packed_dict, object_hook=decode_datetime)

Unpacker 的 object_hook 回调函数接收一个字典；可以使用 object_pairs_hook 回调函数接收键值对列表。

注意：msgpack 目前可以将带有 tzinfo 的 datetime 编码为标准的扩展类型。请参阅 Packer 文档字符串中的 datetime 选项。

扩展类型

还可以使用 ext 类型来打包/解包自定义数据类型。

>>> import msgpack
>>> import array
>>> def default(obj):
...     if isinstance(obj, array.array) and obj.typecode == 'd':
...         return msgpack.ExtType(42, obj.tostring())
...     raise TypeError("Unknown type: %r" % (obj,))
...
>>> def ext_hook(code, data):
...     if code == 42:
...         a = array.array('d')
...         a.fromstring(data)
...         return a
...     return ExtType(code, data)
...
>>> data = array.array('d', [1.2, 3.4])
>>> packed = msgpack.packb(data, default=default)
>>> unpacked = msgpack.unpackb(packed, ext_hook=ext_hook)
>>> data == unpacked
True

高级解包控制

作为迭代的一种替代方法，Unpacker 对象提供了 unpack、skip、read_array_header 和 read_map_header 方法。前两种方法分别从流中读取整个消息，分别反序列化和返回结果，或忽略它。后两种方法返回即将到来的容器中的元素数量，因此可以单独解包或跳过数组中的每个元素或映射中的键值对。

备注

旧版 msgpack 规范中的字符串和二进制类型

msgpack 的早期版本没有区分字符串和二进制类型。表示字符串和二进制类型的类型被命名为 raw。

您可以使用 use_bin_type=False 和 raw=True 选项将数据打包到旧规范并从中解包。

>>> import msgpack
>>> msgpack.unpackb(msgpack.packb([b'spam', 'eggs'], use_bin_type=False), raw=True)
[b'spam', b'eggs']
>>> msgpack.unpackb(msgpack.packb([b'spam', 'eggs'], use_bin_type=True), raw=False)
[b'spam', 'eggs']

ext 类型

要使用 ext 类型，请将 msgpack.ExtType 对象传递给打包器。

>>> import msgpack
>>> packed = msgpack.packb(msgpack.ExtType(42, b'xyzzy'))
>>> msgpack.unpackb(packed)
ExtType(code=42, data='xyzzy')

您可以使用它与 default 和 ext_hook 一起使用。请参见下文。

安全性

为了解包从不可靠来源接收的数据，msgpack 提供了两个安全选项。

max_buffer_size（默认值：100*1024*1024）限制内部缓冲区大小。它还用于限制预分配的列表大小。

strict_map_key（默认值：True）限制映射键的类型为字节和 str。虽然 msgpack 规范没有限制映射键的类型，但存在 hashdos 的风险。如果您需要支持映射键的其他类型，请使用 strict_map_key=False。

性能提示

CPython 的 GC 在分配对象增长时开始。这意味着解包可能会引起无用的 GC。在解包大消息时，您可以使用 gc.disable()。

列表是 Python 的默认序列类型。但元组比列表轻。在性能重要时解包时，您可以使用 use_list=False。

历史上的重大变更

msgpack 0.5

PyPI 上的包名从 msgpack-python 更改为 msgpack 从 0.5。

在从 msgpack-0.4 或更早版本升级之前，请先执行 pip uninstall msgpack-python，然后执行 pip install -U msgpack。

msgpack 1.0

• Python 2 支持

  • 扩展模块不再支持 Python 2。对于 Python 2，使用纯 Python 实现（《msgpack.fallback》）。

  • msgpack 1.0.6 放弃了对 Python 2.7 的官方支持，因为 pip 和 GitHub Action（setup-python）不再支持 Python 2.7。

• Packer

  • Packer 默认使用 use_bin_type=True。字节在 msgpack 中以二进制类型编码。
  • 已删除 encoding 选项。始终使用 UTF-8。

• Unpacker

  • Unpacker 默认使用 raw=False。它假定 str 类型是有效的 UTF-8 字符串并将它们解码为 Python str（unicode）对象。
  • 已删除 encoding 选项。您可以使用 raw=True 来支持旧格式（例如，解包到字节而不是 str）。
  • max_buffer_size 的默认值已从 0 更改为 100 MiB，以避免 DoS 攻击。如果您有大型但安全的数据，则需要传递 max_buffer_size=0。
  • strict_map_key 的默认值已更改为 True，以避免 hashdos。如果您有包含非字节或 str 类型的映射键的数据，则需要传递 strict_map_key=False。