marshal — 内部 Python 对象序列化

此模块包含可以读写二进制格式的 Python 值的函数。该格式是 Python 特有的，但与机器架构问题无关（例如，您可以将 Python 值写入 PC 上的文件，将文件传输到 Mac，然后在那里读取回来）。该格式的详细信息是有意未公开的；它可能会在 Python 版本之间更改（尽管很少发生）。[1]

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

警告

marshal 模块并非旨在安全地抵御错误或恶意构造的数据。切勿反序列化来自不受信任或未经身份验证的来源的数据。

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

有一些读取/写入文件的函数以及处理类似字节对象的函数。

该模块定义了这些函数

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

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

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

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

使用参数 value、version 引发 审计事件 marshal.dumps。

在 3.13 版本中更改：添加了 allow_code 参数。

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

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

引发没有参数的 审计事件 marshal.load。

注意

如果使用 dump() 封送了包含不受支持类型的对象，则 load() 将用 None 替换无法反序列化的类型。

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

在 3.13 版本中更改：添加了 allow_code 参数。

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

返回通过 dump(value, file) 写入文件的字节对象。该值必须是受支持的类型。如果该值具有（或包含具有）不受支持的类型，则引发 ValueError 异常。代码对象 仅在 allow_code 为 true 时才受支持。

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

使用参数 value、version 引发 审计事件 marshal.dumps。

在 3.13 版本中更改：添加了 allow_code 参数。

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

将bytes-like object转换为一个值。 如果找不到有效的值，则引发 EOFError、 ValueError 或 TypeError。 仅当 allow_code 为 true 时，才支持代码对象。 输入中多余的字节将被忽略。

使用参数 bytes 引发 审计事件 marshal.loads。

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

在 3.13 版本中更改：添加了 allow_code 参数。

此外，还定义了以下常量

marshal.version

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

脚注