marshal - Python 内部对象序列化

此模块包含可以用二进制格式读写 Python 值的函数。该格式特定于 Python，但独立于机器体系结构问题（例如，您可以将 Python 值写入 PC 上的文件，将文件传输到 Mac，然后在那里读回）。格式的细节故意没有记录；它可能会在 Python 版本之间发生变化（尽管很少发生）。[1]

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

警告

marshal 模块并非旨在防止错误或恶意构造的数据。切勿解组从不受信任或未经身份验证的来源接收的数据。

并非所有 Python 对象类型都受支持；通常，只有值独立于 Python 特定调用的对象才能被此模块写入和读取。支持以下类型：布尔值、整数、浮点数、复数、字符串、字节、字节数组、元组、列表、集合、冻结集合、字典和代码对象，其中应该理解元组、列表、集合、冻结集合和字典只有在其包含的值本身受支持时才受支持。单例 None、Ellipsis 和 StopIteration 也可以被编组和解组。对于低于 3 的格式 *版本*，不能写入递归列表、集合和字典（见下文）。

有一些函数可以读/写文件，以及对类字节对象进行操作的函数。

该模块定义了以下函数

marshal.dump(value, file[, version])

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

如果该值具有（或包含具有）不受支持的类型的对象，则会引发 ValueError 异常 - 但垃圾数据也会被写入文件。该对象将无法通过 load() 正确读回。

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

引发带有参数 value、version 的 审计事件 marshal.dumps。

marshal.load(file)

从打开的文件中读取一个值并返回它。如果没有读取到有效值（例如，因为数据具有不同 Python 版本的不兼容 marshal 格式），则引发 EOFError、ValueError 或 TypeError。该文件必须是可读的 二进制文件。

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

注意

如果包含不受支持类型的对象已使用 dump() 进行编组，则 load() 将使用 None 替换不可编组的类型。

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

marshal.dumps(value[, version])

返回 dump(value, file) 将写入文件的字节对象。该值必须是受支持的类型。如果 value 具有（或包含具有）不受支持的类型的对象，则引发 ValueError 异常。

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

引发带有参数 value、version 的 审计事件 marshal.dumps。

marshal.loads(bytes)

将 类字节对象 转换为值。如果未找到有效值，则引发 EOFError、ValueError 或 TypeError。输入中的额外字节将被忽略。

引发带有参数 bytes 的 审计事件 marshal.loads。

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

此外，还定义了以下常量

marshal.version

指示模块使用的格式。版本 0 是历史格式，版本 1 共享内联字符串，版本 2 对浮点数使用二进制格式。版本 3 增加了对对象实例化和递归的支持。当前版本为 4。

脚注