引言

在 Python 2.2 中 pickling 新式对象的方式有些笨拙，与旧式类实例相比，会导致 pickle 大小膨胀。本 PEP 详细介绍了一个新的 pickle 协议，该协议将在 Python 2.3 中引入，可以解决这个问题以及许多其他 pickle 问题。

指定新的 pickle 协议有两个方面：需要指定构成 pickled 数据的字节流，以及需要指定对象与 pickling 和 unpickling 引擎之间的接口。本 PEP 侧重于 API 问题，尽管有时也会提及字节流格式细节来解释某种选择。pickle 字节流格式由标准库模块 pickletools.py 正式记录（该模块已在 Python 2.3 的 CVS 中提交）。

本 PEP 试图完整地记录 pickled 对象与 pickling 过程之间的接口，通过指定“本 PEP 新增”来突出新内容。（除了用于指定 pickler 的 pickling 协议的 API 更改外，不完全涵盖用于调用 pickling 或 unpickling 的接口。）

动机

Pickling 新式对象会导致 pickle 大小严重膨胀。例如

class C(object): # Omit "(object)" for classic class
    pass
x = C()
x.foo = 42
print len(pickle.dumps(x, 1))

旧式对象的二进制 pickle 占用了 33 字节，新式对象则占用了 86 字节。

膨胀的原因很复杂，但主要归因于新式对象需要 __reduce__ 才能进行 pickling。经过充分考虑，我们得出结论，减少新式对象 pickle 大小的唯一方法是向 pickle 协议添加新的操作码。最终结果是，使用新协议，上述示例中的 pickle 大小为 35（开头使用了两个额外的字节来指示协议版本，尽管这并非严格必需）。

协议版本

以前，pickling（但不是 unpickling）区分文本模式和二进制模式。根据设计，二进制模式是文本模式的超集，unpickler 不需要提前知道传入的 pickle 是使用文本模式还是二进制模式。用于 unpickling 的虚拟机在模式上是相同的；某些操作码在文本模式下根本不使用。

追溯性地，文本模式现在称为协议 0，二进制模式称为协议 1。新协议称为协议 2。遵循 pickling 协议的传统，协议 2 是协议 1 的超集。但为了避免未来的 pickling 协议需要成为最旧协议的超集，协议 2 pickle 的开头插入了一个新的操作码，指示它使用的是协议 2。到目前为止，Python 的每个版本都能够读取所有先前版本编写的 pickle。当然，在协议 N 下编写的 pickle 无法被引入协议 N 之前的 Python 版本读取。

用于 pickling 的几个函数、方法和构造函数以前接受一个名为‘bin’的位置参数，这是一个标志，默认为 0，表示二进制模式。此参数已重命名为‘protocol’，现在给出协议编号，仍默认为 0。

碰巧，在以前的 Python 版本中，将 2 作为‘bin’参数具有与将 1 作为参数相同的效果。尽管如此，这里添加了一个特殊情况：传递负数会选择特定实现支持的最高协议版本。这在以前的 Python 版本中也有效，因此可以用来选择最高可用协议，且兼顾向后和向前兼容。此外，pickle 和 cPickle 模块都提供了一个新的模块常量 HIGHEST_PROTOCOL，它等于模块可以读取的最高协议编号。这比传递 -1 更清晰，但在 Python 2.3 之前无法使用。

pickle.py 模块一直支持将‘bin’值作为关键字参数而不是位置参数传递。（不推荐这样做，因为 cPickle 只接受位置参数，但它有效……）将‘bin’作为关键字参数传递已被弃用，在这种情况下会发出 PendingDeprecationWarning 警告。您必须使用 -Wa 或其变体来调用 Python 解释器才能看到 PendingDeprecationWarning 消息。在 Python 2.4 中，警告类可能会升级为 DeprecationWarning。

安全问题

在以前的 Python 版本中，unpickling 会对某些操作进行“安全检查”，拒绝调用未通过“可安全 unpickling”标记的函数或构造函数，这些标记是通过具有 __safe_for_unpickling__ 属性设置为 1，或在全局注册表 copy_reg.safe_constructors 中注册来实现的。

此功能给人一种虚假的安全感：没有人进行过必要的、广泛的代码审计来证明 unpickling 不受信任的 pickle 不会调用不希望的代码，事实上 Python 2.2 pickle.py 模块中的错误使得绕过这些安全措施变得容易。

我们坚信，在互联网上，知道自己正在使用一个不安全的协议比信任一个未经充分检查其实现而声称安全的协议要好。即使是广泛使用的协议的高质量实现，也经常会发现存在缺陷；Python 的 pickle 实现如果没有更多的时间投入，根本无法做出这样的保证。因此，从 Python 2.3 开始，所有 unpickling 上的安全检查都被正式移除，并替换为此警告：

尽管存在安全检查，但同样的警告也适用于以前的 Python 版本。

扩展的 __reduce__ API

类可以利用几个 API 来控制 pickling。其中最受欢迎的可能是 __getstate__ 和 __setstate__；但最强大的是 __reduce__。（还有一个 __getinitargs__，我们将在下面添加 __getnewargs__。）

有几种方法可以提供 __reduce__ 功能：类可以实现 __reduce__ 方法或 __reduce_ex__ 方法（见下一节），或者可以在 copy_reg 中声明一个 reduce 函数（copy_reg.dispatch_table 将类映射到函数）。虽然返回值被完全相同地解释，我们将它们统称为 __reduce__。

重要提示： pickling 旧式类实例时，不会查找 __reduce__ 或 __reduce_ex__ 方法，也不会在 copy_reg 分派表中查找 reduce 函数，因此旧式类无法在此意义上提供 __reduce__ 功能。旧式类必须使用 __getinitargs__ 和/或 __getstate__ 来自定义 pickling。这些将在下面介绍。

__reduce__ 必须返回一个字符串或一个元组。如果返回一个字符串，则表示一个对象，其状态不被 pickling，而是引用一个同等对象，该对象通过名称进行引用。令人惊讶的是，__reduce__ 返回的字符串应该是对象的本地名称（相对于其模块）；pickle 模块会搜索模块命名空间来确定对象的模块。

本节其余部分将讨论 __reduce__ 返回的元组。它是一个可变长度元组，长度为 2 到 5。前两个项（函数和参数）是必需的。其余项是可选的，可以从末尾省略；为可选项的值提供 None 与省略它们的效果相同。最后两项是本 PEP 中新增的。各项的顺序是：

Unpickling 调用 function(*arguments) 来创建一个初始对象，下面称为 *obj*。如果省略了其余项，则 unpickling 对此对象的处理就结束了，*obj* 就是结果。否则，*obj* 在 unpickling 时会根据指定的每一项进行修改，如下所示。

obj.__dict__.update(state)

for k, v in state.items():
    setattr(obj, k, v)

注意：在 Python 2.2 及更早版本中，使用 cPickle 时，如果状态存在，即使它是 None 也会被 pickling；避免 __setstate__ 调用唯一安全的方法是从 __reduce__ 返回一个二元元组。（但 pickle.py 不会 pickling None 状态。）在 Python 2.3 中，当 __reduce__ 在 pickling 时返回值为 None 的状态时，__setstate__ 在 unpickling 时永远不会被调用。

一个 __reduce__ 实现，如果需要同时在 Python 2.2 和 Python 2.3 下工作，可以检查变量 pickle.format_version 来确定是使用 *listitems* 和 *dictitems* 功能。如果此值 >= "2.0"，则支持它们。如果不支持，则任何列表或字典项都应以某种方式包含在“state”返回值中，并且 __setstate__ 方法应准备好接受列表或字典项作为状态的一部分（如何实现取决于应用程序）。

__reduce_ex__ API

有时了解协议版本对于实现 __reduce__ 很有用。这可以通过实现一个名为 __reduce_ex__ 的方法而不是 __reduce__ 来完成。__reduce_ex__ 存在时，优先于 __reduce__ 调用（为向后兼容，您仍然可以提供 __reduce__）。__reduce_ex__ 方法将使用一个整数参数调用，即协议版本。

‘object’类同时实现了 __reduce__ 和 __reduce_ex__；然而，如果子类覆盖了 __reduce__ 但没有覆盖 __reduce_ex__，__reduce_ex__ 实现会检测到这种情况并调用 __reduce__。

在没有 __reduce__ 实现的情况下自定义 pickling

如果对于某个类没有可用的 __reduce__ 实现，则需要分别考虑三种情况，因为它们的处理方式不同：

1. 旧式类实例，所有协议
2. 新式类实例，协议 0 和 1
3. 新式类实例，协议 2

用 C 实现的类型被视为新式类。但是，除了常见的内置类型外，这些类型需要提供 __reduce__ 实现才能使用协议 0 或 1 进行 pickling。协议 2 还支持使用 __getnewargs__、__getstate__ 和 __setstate__ 的内置类型。

basestate = B(obj)

obj = B.__new__(D, basestate)
B.__init__(obj, basestate)

obj = C.__new__(C, *args)

__newobj__ unpickling 函数

当 __reduce__ 返回的 unpickling 函数（返回元组的第一个元素）名称为 __newobj__ 时，对于 pickle 协议 2 会发生特殊情况。一个名为 __newobj__ 的 unpickling 函数假定具有以下语义：

def __newobj__(cls, *args):
    return cls.__new__(cls, *args)

pickle 协议 2 特殊处理一个具有此名称的 unpickling 函数，并发出一个 pickling 操作码，该操作码接收‘cls’和‘args’，将返回 cls.__new__(cls, *args)，而无需 pickling __newobj__ 的引用（这是协议 2 为新式类实例在没有 __reduce__ 实现时使用的相同 pickling 操作码）。这也是协议 2 pickle 比旧式 pickle 小得多的主要原因。当然，pickling 代码无法验证名为 __newobj__ 的函数是否具有预期的语义。如果您使用的 unpickling 函数名为 __newobj__ 但返回不同的内容，那么您将自食其果。

在 Python 2.2 下使用此功能是安全的；__newobj__ 的推荐实现中没有任何内容依赖于 Python 2.3。

扩展注册表

协议 2 支持一种新的机制来减小 pickle 的大小。

当 pickling 类实例（旧式或新式）时，类的完整名称（包括包名称的模块名称和类名称）将被包含在 pickle 中。特别对于生成许多小型 pickle 的应用程序来说，这会产生大量开销，并且必须在每个 pickle 中重复。对于大型 pickle，在使用协议 1 时，对同一类名的重复引用会使用“memo”功能进行压缩；但每个类名必须在每个 pickle 中至少完整拼写一次，这会导致小型 pickle 的开销很大。

扩展注册表允许用小的整数来表示最常用的名称，这些整数的 pickling 非常高效：代码范围在 1-255 的扩展码只需要两个字节（包括操作码），范围在 256-65535 的扩展码只需要三个字节（包括操作码）。

pickle 协议的设计目标之一是使 pickle “无上下文”：只要您安装了包含 pickle 所引用的类的模块，就可以 unpickle 它，而无需提前导入任何这些类。

无限制地使用扩展码可能会危及 pickle 的这一理想属性。因此，扩展码的主要用途保留给将由某个标准化机构标准化的编码集。鉴于这是 Python，标准化机构是 PSF。PSF 将不时地决定一个映射表，将扩展码映射到类名（或偶尔的其他全局对象名称；函数也符合资格）。此表将包含在下一个 Python 发布版本中。

但是，对于某些应用程序，例如 Zope，无上下文 pickle 不是必需的，并且等待 PSF 标准化某些编码可能不切实际。为这类应用程序提供了两种解决方案。

首先，保留了一些扩展码范围供私人使用。任何应用程序都可以在这些范围内注册编码。在这些范围内交换使用编码的两个应用程序需要某种带外机制来就扩展码与名称之间的映射达成一致。

其次，一些大型 Python 项目（例如 Zope）可以被分配一个“私人使用”范围之外的扩展码范围，它们可以根据需要进行分配。

扩展注册表定义为扩展码与名称之间的映射。当 unpickle 一个扩展码时，它最终会产生一个对象，但这个对象是通过将名称解释为模块名称后跟类（或函数）名称来获取的。名称到对象的映射被缓存。某些名称可能无法导入；只要没有包含对这些名称引用的 pickle 需要 unpickle，这就不成问题。（对于协议 0 或 1 的 pickle 中的这些名称的直接引用，已经存在同样的问题。）

以下是拟议的扩展码范围的初始分配：

*MAX* 代表 2147483647，或 2**31-1。这是当前定义的协议的硬限制。

目前，还没有分配任何特定的扩展码。

copy 模块

传统上，copy 模块支持 pickling API 的扩展子集，用于自定义 copy() 和 deepcopy() 操作。

特别是，除了检查 __copy__ 或 __deepcopy__ 方法外，copy() 和 deepcopy() 始终查找 __reduce__，对于旧式类，则查找 __getinitargs__、__getstate__ 和 __setstate__。

在 Python 2.2 中，从‘object’继承的默认 __reduce__ 实现使得复制简单的新式类成为可能，但 slots 和各种其他特殊情况未被涵盖。

在 Python 2.3 中，对 copy 模块进行了几项更改：

• __reduce_ex__ 被支持（并且始终使用 2 作为协议版本参数调用）。
• 支持 __reduce__ 的四参数和五参数返回值。
• 在查找 __reduce__ 方法之前，会像 pickling 一样查询 copy_reg.dispatch_table。
• 当 __reduce__ 方法从 object 继承时，它会被（无条件地）替换为一个更好的实现，该实现使用与 pickle 协议 2 相同的 API：__getnewargs__、__getstate__ 和 __setstate__，并处理 list 和 dict 子类，以及处理 slots。

作为后一项更改的结果，某些在 Python 2.2 下可以复制的新式类在 Python 2.3 下将不再可复制。（这些类也无法使用 pickle 协议 2 进行 pickling。）此类的一个最小示例：

class C(object):
    def __new__(cls, a):
        return object.__new__(cls)

问题仅在覆盖 __new__ 并且除了类参数外至少有一个强制参数时才会发生。

为了解决这个问题，应添加一个 __getnewargs__ 方法，该方法返回适当的参数元组（不包括类）。

Pickling Python 长整数

在协议 0 和 1 中，pickling 和 unpickling Python 长整数所需时间与数字位数成二次方关系。在协议 2 下，新的操作码支持长整数的线性时间 pickling 和 unpickling。

Pickling 布尔值

协议 2 引入了新的操作码，用于直接 pickling True 和 False。在协议 0 和 1 下，布尔值被 pickling 为整数，利用 pickle 中整数表示的技巧，以便 unpickler 可以识别出意图是布尔值。该技巧每个 pickling 的布尔值消耗 4 字节。新的布尔操作码每个布尔值消耗 1 字节。

Pickling 小元组

协议 2 引入了新的操作码，用于更紧凑地 pickling 长度为 1、2 和 3 的元组。协议 1 以前引入了一个操作码，用于更紧凑地 pickling 空元组。

协议识别

协议 2 引入了一个新的操作码，所有协议 2 pickle 都以此开头，指示该 pickle 是协议 2。因此，在旧版本 Python 中尝试 unpickle 协议 2 pickle 将立即引发“未知操作码”异常。

Pickling 大列表和字典

协议 1 将大列表和字典“一次性”pickling，从而最大程度地减小 pickle 大小，但这要求 unpickling 创建一个与被 unpickling 对象一样大的临时对象。协议 2 的部分更改将大列表和字典分解为每个不超过 1000 个元素的小块，这样 unpickling 就不必创建大于容纳 1000 个元素所需大小的临时对象。然而，这并非协议 2 的一部分：生成的操作码仍属于协议 1。__reduce__ 实现返回可选的新列表项或字典项迭代器也受益于此 unpickling 临时空间优化。

版权

本文档已置于公共领域。