marshal --- Python 内部对象序列化

此模块包含的函数可以读写二进制格式的 Python 值。该格式是 Python 特有的，但与机器架构无关（例如，你可以在 PC 上将一个 Python 值写入文件，将文件传输到 Mac，然后再在那里读回）。此格式的细节有意不作文档说明；它可能在不同 Python 版本之间发生变化（尽管很少这样做）。[1]

这不是一个通用的“持久化”模块。对于通用的持久化和通过 RPC 调用传输 Python 对象，请参阅 pickle 和 shelve 模块。marshal 模块的存在主要是为了支持读写 Python 模块的 .pyc 文件中的“伪编译”代码。因此，Python 维护者保留在需要时以向后不兼容的方式修改 marshal 格式的权利。代码对象的格式在 Python 版本之间不兼容，即使格式的版本号相同。在不正确的 Python 版本中反序列化代码对象的行为是未定义的。如果你要序列化和反序列化 Python 对象，请改用 pickle 模块——性能相当，保证版本独立性，并且 pickle 支持的对象范围比 marshal 广泛得多。

警告

警告：marshal 模块不具备抵御错误或恶意构造的数据的安全性。切勿 unmarshal 来自不受信任或未经身份验证来源的数据。

该模块提供了读写文件的函数以及操作类字节对象的函数。

并非所有 Python 对象类型都受支持；通常，只有那些其值与 Python 的特定调用无关的对象才能被此模块写入和读取。支持以下类型：

在 3.4 版本发生变更

  • 增加了格式版本 3，支持序列化递归的列表、集合和字典。

  • 添加了格式版本 4，支持短字符串的高效表示。

在 3.14 版本发生变更: 添加了格式版本 5，允许序列化切片。

该模块定义了以下函数

marshal.dump(value, file, version=version, /, *, allow_code=True)

将值写入打开的文件中。该值必须是受支持的类型。文件必须是可写的二进制文件。

如果值包含（或其内部包含的对象包含）不支持的类型，则会引发 ValueError 异常——但垃圾数据也会被写入文件。该对象将无法通过 load() 正确读回。代码对象仅在 *allow_code* 为真时受支持。

*version* 参数指明了 dump 应该使用的数据格式（见下文）。

引发一个附带参数 value, version 的审计事件 marshal.dumps。

在 3.13 版本发生变更: 添加了 *allow_code* 形参。

marshal.load(file, /, *, allow_code=True)

从打开的文件中读取一个值并返回。如果未读取到有效值（例如，因为数据是不同 Python 版本的不兼容 marshal 格式），则引发 EOFError、ValueError 或 TypeError。代码对象仅在 *allow_code* 为真时受支持。文件必须是可读的二进制文件。

引发一个不带参数的审计事件 marshal.load。

备注

如果一个包含不支持类型的对象被 dump() 序列化，load() 将会用 None 来替代那个无法被 unmarshal 的类型。

在 3.10 版本发生变更: 此调用过去会为每个代码对象引发一个 code.__new__ 审计事件。现在它会为整个加载操作引发一个 marshal.load 事件。

在 3.13 版本发生变更: 添加了 *allow_code* 形参。

marshal.dumps(value, version=version, /, *, allow_code=True)

返回 dump(value, file) 将会写入文件的字节对象。值必须是受支持的类型。如果值包含（或其内部包含的对象包含）不支持的类型，则引发 ValueError 异常。代码对象仅在 *allow_code* 为真时受支持。

*version* 参数指明了 dumps 应该使用的数据格式（见下文）。

引发一个附带参数 value, version 的审计事件 marshal.dumps。

在 3.13 版本发生变更: 添加了 *allow_code* 形参。

marshal.loads(bytes, /, *, allow_code=True)

将类字节对象转换为一个值。如果找不到有效值，则引发 EOFError、ValueError 或 TypeError。代码对象仅在 *allow_code* 为真时受支持。输入中多余的字节将被忽略。

引发一个附带参数 bytes 的审计事件 marshal.loads。

在 3.10 版本发生变更: 此调用过去会为每个代码对象引发一个 code.__new__ 审计事件。现在它会为整个加载操作引发一个 marshal.loads 事件。

在 3.13 版本发生变更: 添加了 *allow_code* 形参。

此外，还定义了以下常量：

marshal.version

指示模块使用的格式。版本 0 是历史上的第一个版本；后续版本增加了新功能。通常，新版本在引入时成为默认版本。

版本

始于

新特性

1

Python 2.4

共享驻留字符串

2

Python 2.5

浮点数的二进制表示

3

Python 3.4

支持对象实例化和递归

4

Python 3.4

短字符串的高效表示

5

Python 3.14

支持 slice 对象

脚注