Python标准库pickle——Python对象序列化

数据流格式¶

pickle 所使用的数据格式仅可用于 Python。这样做的好处是没有外部标准给该格式强加限制，比如 JSON 或 XDR（不能表示共享指针）标准；但这也意味着非 Python 程序可能无法重新读取 pickle 打包的 Python 对象。

默认情况下，pickle 格式使用相对紧凑的二进制来存储。如果需要让文件更小，可以高效地 压缩 由 pickle 打包的数据。

pickletools 模块包含了相应的工具用于分析 pickle 生成的数据流。pickletools 源码中包含了对 pickle 协议使用的操作码的大量注释。

当前用于 pickling 的协议共有 5 种。使用的协议版本越高，读取生成的 pickle 所需的 Python 版本就要越新。

• v0 版协议是原始的“人类可读”协议，并且向后兼容早期版本的 Python。

• v1 版协议是较早的二进制格式，它也与早期版本的 Python 兼容。

• v2 版协议是在 Python 2.3 中引入的。它为存储 new-style class 提供了更高效的机制。欲了解有关第 2 版协议带来的改进，请参阅 PEP 307。

• v3 版协议添加于 Python 3.0。它具有对 bytes 对象的显式支持，且无法被 Python 2.x 打开。这是目前默认使用的协议，也是在要求与其他 Python 3 版本兼容时的推荐协议。

• v4 版协议添加于 Python 3.4。它支持存储非常大的对象，能存储更多种类的对象，还包括一些针对数据格式的优化。有关第 4 版协议带来改进的信息，请参阅 PEP 3154。

模块接口¶

要序列化某个包含层次结构的对象，只需调用 dumps() 函数即可。同样，要反序列化数据流，可以调用 loads() 函数。但是，如果要对序列化和反序列化加以更多的控制，可以分别创建 Pickler 或 Unpickler 对象。

pickle 模块包含了以下常量：

pickle.HIGHEST_PROTOCOL¶

整数，可用的最高 协议版本。此值可以作为 协议 值传递给 dump() 和 dumps() 函数，以及 Pickler 的构造函数。

pickle.DEFAULT_PROTOCOL¶

一个整数，表示封存操作使用的 协议版本。 它可能小于 HIGHEST_PROTOCOL。 当前默认协议版本为 3，它是一个为 Python 3 设计的新协议。

pickle 模块提供了以下方法，让打包过程更加方便。

pickle.dump(obj, file, protocol=None, *, fix_imports=True)¶

将打包好的对象 obj 写入已打开的 file objectfile。它等同于 Pickler(file,protocol).dump(obj)。

可选参数 protocol 是一个整数，告知 pickler 使用指定的协议，可选择的协议范围从 0 到 HIGHEST_PROTOCOL。如果没有指定，这一参数默认值为 DEFAULT_PROTOCOL。指定一个负数就相当于指定 HIGHEST_PROTOCOL。

参数 file 必须有一个 write() 方法，该 write() 方法要能接收字节作为其唯一参数。因此，它可以是一个打开的磁盘文件（用于写入二进制内容），也可以是一个 io.BytesIO 实例，也可以是满足这一接口的其他任何自定义对象。

如果 fix_imports 为 True 且 protocol 小于 3，pickle 将尝试将 Python 3 中的新名称映射到 Python 2 中的旧模块名称，因此 Python 2 也可以读取打包出的数据流。

pickle.dumps(obj, protocol=None, *, fix_imports=True)¶

将 obj 打包以后的对象作为 bytes 类型直接返回，而不是将其写入到文件。

参数 protocol 和 fix_imports 的含义与它们在 dump() 中的含义相同。

pickle.load(file, *, fix_imports=True, encoding="ASCII", errors="strict")¶

从已打开的 file object文件 中读取打包后的对象，重建其中特定对象的层次结构并返回。它相当于 Unpickler(file).load()。

Pickle 协议版本是自动检测出来的，所以不需要参数来指定协议。打包对象以外的其他字节将被忽略。

参数 file 必须有两个方法，其中 read() 方法接受一个整数参数，而 readline() 方法不需要参数。 两个方法都应返回字节串。 因此 file 可以是一个打开用于二进制读取的磁盘文件、一个 io.BytesIO 对象，或者任何满足此接口要求的其他自定义对象。

可选的关键字参数是 fix_imports, encoding 和 errors，用于控制由Python 2 生成的 pickle 流的兼容性。如果 fix_imports 为 true，则 pickle 将尝试将旧的 Python 2 名称映射到 Python 3 中对应的新名称。encoding 和 errors 参数告诉 pickle 如何解码 Python 2 存储的 8 位字符串实例；这两个参数默认分别为 'ASCII' 和 'strict'。 encoding 参数可置为 'bytes' 来将这些 8 位字符串实例读取为字节对象。读取 NumPy array 和 Python 2 存储的 datetime、date 和 time 实例时，请使用 encoding='latin1'。

pickle.loads(data, *, fix_imports=True, encoding="ASCII", errors="strict")¶

重建并返回一个对象的封存表示形式 data 的对象层级结构。 data 必须为 bytes-like object。

Pickle 协议版本是自动检测出来的，所以不需要参数来指定协议。打包对象以外的其他字节将被忽略。

可选的关键字参数是 fix_imports, encoding 和 errors，用于控制由Python 2 生成的 pickle 流的兼容性。如果 fix_imports 为 true，则 pickle 将尝试将旧的 Python 2 名称映射到 Python 3 中对应的新名称。encoding 和 errors 参数告诉 pickle 如何解码 Python 2 存储的 8 位字符串实例；这两个参数默认分别为 'ASCII' 和 'strict'。 encoding 参数可置为 'bytes' 来将这些 8 位字符串实例读取为字节对象。读取 NumPy array 和 Python 2 存储的 datetime、date 和 time 实例时，请使用 encoding='latin1'。

pickle 模块定义了以下 3 个异常：

exception pickle.PickleError¶

其他 pickle 异常的基类。它是 Exception 的一个子类。

exception pickle.PicklingError¶

当 Pickler 遇到无法解包的对象时抛出此错误。它是 PickleError 的子类。

参考 可以被打包/解包的对象 来了解哪些对象可以被打包。

exception pickle.UnpicklingError¶

当解包出错时抛出此异常，例如数据损坏或对象不安全。它是 PickleError 的子类。

注意，解包时可能还会抛出其他异常，包括（但不限于） AttributeError、EOFError、ImportError 和 IndexError。

pickle 模块可导出两个类，Pickler 和 Unpickler:

class pickle.Pickler(file, protocol=None, *, fix_imports=True)¶

它接受一个二进制文件用于写入 pickle 数据流。

可选参数 protocol 是一个整数，告知 pickler 使用指定的协议，可选择的协议范围从 0 到 HIGHEST_PROTOCOL。如果没有指定，这一参数默认值为 DEFAULT_PROTOCOL。指定一个负数就相当于指定 HIGHEST_PROTOCOL。

参数 file 必须有一个 write() 方法，该 write() 方法要能接收字节作为其唯一参数。因此，它可以是一个打开的磁盘文件（用于写入二进制内容），也可以是一个 io.BytesIO 实例，也可以是满足这一接口的其他任何自定义对象。

如果 fix_imports 为 True 且 protocol 小于 3，pickle 将尝试将 Python 3 中的新名称映射到 Python 2 中的旧模块名称，因此 Python 2 也可以读取打包出的数据流。

dump(obj)¶

将 obj 打包后的内容写入已打开的文件对象，该文件对象已经在构造函数中指定。

persistent_id(obj)¶

默认什么也不做。它存在是为了让子类可以重载它。

如果 persistent_id() 返回 None，obj 会被照常 pickle。如果返回其他值，Pickler 会将这个函数的返回值作为 obj 的持久化 ID（Pickler 本应得到序列化数据流并将其写入文件，若此函数有返回值，则得到此函数的返回值并写入文件）。这个持久化 ID 的解释应当定义在 Unpickler.persistent_load() 中（该方法定义还原对象的过程，并返回得到的对象）。注意，persistent_id() 的返回值本身不能拥有持久化 ID。

参阅 持久化外部对象 获取详情和使用示例。

dispatch_table¶

Pickler 对象的 dispatch 表是 copyreg.pickle() 中用到的 reduction 函数 的注册。dispatch 表本身是一个 class 到其 reduction 函数的映射键值对。一个 reduction 函数只接受一个参数，就是其关联的 class，函数行为应当遵守 __reduce__() 接口规范。

Pickler 对象默认并没有 dispatch_table 属性，该对象默认使用 copyreg 模块中定义的全局 dispatch 表。如果要为特定 Pickler 对象自定义序列化过程，可以将 dispatch_table 属性设置为类字典对象（dict-like object）。另外，如果 Pickler 的子类设置了 dispatch_table 属性，则该子类的实例会使用这个表作为默认的 dispatch 表。

参阅 Dispatch 表 获取使用示例。

3.3 新版功能.

fast¶

已弃用。设为 True 则启用快速模式。快速模式禁用了“备忘录” (memo) 的使用，即不生成多余的 PUT 操作码来加快打包过程。不应将其与自指 (self-referential) 对象一起使用，否则将导致 Pickler 无限递归。

如果需要进一步提高 pickle 的压缩率，请使用 pickletools.optimize()。

class pickle.Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict")¶

它接受一个二进制文件用于读取 pickle 数据流。

Pickle 协议版本是自动检测出来的，所以不需要参数来指定协议。

参数 file 必须有两个方法，其中 read() 方法接受一个整数参数，而 readline() 方法不需要参数。 两个方法都应返回字节串。 因此 file 可以是一个打开用于二进制读取的磁盘文件对象、一个 io.BytesIO 对象，或者任何满足此接口要求的其他自定义对象。

可选的关键字参数有 fix_imports, encoding 和 errors，它们用于控制由 Python 2 所生成 pickle 流的兼容性支持。 如果 fix_imports 为真值，则 pickle 将尝试把旧的 Python 2 名称映射到 Python 3 所使用的新名称。 encoding 和 errors 将告知 pickle 如何解码由 Python 2 所封存的 8 位字符串实例；这两个参数的默认值分别为 'ASCII' 和 'strict'。 encoding 可设为 'bytes' 以将这些 8 位字符串实例作为字节对象来读取。

load()¶

从构造函数中指定的文件对象里读取打包好的对象，重建其中特定对象的层次结构并返回。打包对象以外的其他字节将被忽略。

persistent_load(pid)¶

默认抛出 UnpicklingError 异常。

如果定义了此方法，persistent_load() 应当返回持久化 ID pid 所指定的对象。 如果遇到无效的持久化 ID，则应当引发 UnpicklingError。

参阅 持久化外部对象 获取详情和使用示例。

find_class(module, name)¶

如有必要，导入 module 模块并返回其中名叫 name 的对象，其中 module 和 name 参数都是 str 对象。注意，不要被这个函数的名字迷惑，find_class() 同样可以用来导入函数。

子类可以重载此方法，来控制加载对象的类型和加载对象的方式，从而尽可能降低安全风险。参阅 限制全局变量 获取更详细的信息。

可以被打包/解包的对象¶

下列类型可以被打包：

• None、True 和 False

• 整数、浮点数、复数

• str、byte、bytearray

• 只包含可打包对象的集合，包括 tuple、list、set 和 dict

• 定义在模块顶层的函数（使用 def 定义，lambda 函数则不可以）

• 定义在模块顶层的内置函数

• 定义在模块顶层的类

• 某些类实例，这些类的 __dict__ 属性值或 __getstate__() 函数的返回值可以被打包（详情参阅 打包类实例 这一段）。

尝试打包不能被打包的对象会抛出 PicklingError 异常，异常发生时，可能有部分字节已经被写入指定文件中。尝试打包递归层级很深的对象时，可能会超出最大递归层级限制，此时会抛出 RecursionError 异常，可以通过 sys.setrecursionlimit() 调整递归层级，不过请谨慎使用这个函数，因为可能会导致解释器崩溃。

注意，函数（内建函数或用户自定义函数）在被打包时，引用的是函数全名。2 这意味着只有函数所在的模块名，与函数名会被打包，函数体及其属性不会被打包。因此，在解包的环境中，函数所属的模块必须是可以被导入的，而且模块必须包含这个函数被打包时的名称，否则会抛出异常。3

同样的，类也只打包名称，所以在解包环境中也有和函数相同的限制。注意，类体及其数据不会被打包，所以在下面的例子中类属性 attr 不会存在于解包后的环境中：

classFoo:
attr='A class attribute'
picklestring=pickle.dumps(Foo)

这些限制决定了为什么必须在一个模块的顶层定义可打包的函数和类。

类似的，在打包类的实例时，其类体和类数据不会跟着实例一起被打包，只有实例数据会被打包。这样设计是有目的的，在将来修复类中的错误、给类增加方法之后，仍然可以载入原来版本类实例的打包数据来还原该实例。如果你准备长期使用一个对象，可能会同时存在较多版本的类体，可以为对象添加版本号，这样就可以通过类的 __setstate__() 方法将老版本转换成新版本。

打包类实例¶

在本节中，我们描述了可用于定义、自定义和控制如何打包和解包类实例的通用流程。

通常，使一个实例可被打包不需要附加任何代码。Pickle 默认会通过 Python 的内省机制获得实例的类及属性。而当实例解包时，它的 __init__() 方法通常 不会 被调用。其默认动作是：先创建一个未初始化的实例，然后还原其属性，下面的代码展示了这种行为的实现机制：

defsave(obj):
return(obj.__class__,obj.__dict__)
defload(cls,attributes):
obj=cls.__new__(cls)
obj.__dict__.update(attributes)
returnobj

类可以改变默认行为，只需定义以下一种或几种特殊方法：

object.__getnewargs_ex__()¶

对于使用第 2 版或更高版协议的 pickle，实现了 __getnewargs_ex__() 方法的类可以控制在解包时传给 __new__() 方法的参数。本方法必须返回一对 (args,kwargs) 用于构建对象，其中 args 是表示位置参数的 tuple，而 kwargs 是表示命名参数的 dict。它们会在解包时传递给 __new__() 方法。

如果类的 __new__() 方法只接受关键字参数，则应当实现这个方法。否则，为了兼容性，更推荐实现 __getnewargs__() 方法。

在 3.6 版更改: __getnewargs_ex__() 现在可用于第 2 和第 3 版协议。

object.__getnewargs__()¶

这个方法与上一个 __getnewargs_ex__() 方法类似，但仅支持位置参数。它要求返回一个 tuple 类型的 args，用于解包时传递给 __new__() 方法。

如果定义了 __getnewargs_ex__()，那么 __getnewargs__() 就不会被调用。

在 3.6 版更改: 在 Python 3.6 前，第 2、3 版协议会调用 __getnewargs__()，更高版本协议会调用 __getnewargs_ex__()。

object.__getstate__()¶

类还可以进一步控制其实例的打包过程。如果类定义了 __getstate__()，它就会被调用，其返回的对象是被当做实例内容来打包的，否则打包的是实例的 __dict__。如果 __getstate__() 未定义，实例的 __dict__ 会被照常打包。

object.__setstate__(state)¶

当解包时，如果类定义了 __setstate__()，就会在已解包状态下调用它。此时不要求实例的 state 对象必须是 dict。没有定义此方法的话，先前打包的 state 对象必须是 dict，且该 dict 内容会在解包时赋给新实例的 __dict__。

注解

如果 __getstate__() 返回 False，那么在解包时就不会调用 __setstate__() 方法。

参考 处理有状态的对象 一段获取如何使用 __getstate__() 和 __setstate__() 方法的更多信息。

可以看出，其实 pickle 并不直接调用上面的几个函数。事实上，这几个函数是复制协议的一部分，它们实现了 __reduce__() 这一特殊接口。复制协议提供了统一的接口，用于在打包或复制对象的过程中取得所需数据。4

尽管这个协议功能很强，但是直接在类中实现 __reduce__() 接口容易产生错误。因此，设计类时应当尽可能的使用高级接口（比如 __getnewargs_ex__()、__getstate__() 和 __setstate__()）。后面仍然可以看到直接实现 __reduce__() 接口的状况，可能别无他法，可能为了获得更好的性能，或者两者皆有之。

object.__reduce__()¶

该接口当前定义如下。__reduce__() 方法不带任何参数，并且应返回字符串或最好返回一个元组（返回的对象通常称为“reduce 值”）。

如果返回字符串，该字符串会被当做一个全局变量的名称。它应该是对象相对于其模块的本地名称，pickle 模块会搜索模块命名空间来确定对象所属的模块。这种行为常在单例模式使用。

当返回的是一个元组时，它的长度必须在二至五项之间。 可选项可以被省略或将值设为 None。 每项的语义分别如下所示：

• 一个可调用对象，该对象会在创建对象的最初版本时调用。

• 可调用对象的参数，是一个元组。如果可调用对象不接受参数，必须提供一个空元组。

• 可选元素，用于表示对象的状态，将被传给前述的 __setstate__() 方法。 如果对象没有此方法，则这个元素必须是字典类型，并会被添加至 __dict__ 属性中。

• 可选元素，一个返回连续项的迭代器（而不是序列）。这些项会被 obj.append(item) 逐个加入对象，或被 obj.extend(list_of_items) 批量加入对象。这个元素主要用于 list 的子类，也可以用于那些正确实现了 append() 和 extend() 方法的类。（具体是使用 append() 还是 extend() 取决于 pickle 协议版本以及待插入元素的项数，所以这两个方法必须同时被类支持。）

• 可选元素，一个返回连续键值对的迭代器（而不是序列）。这些键值对将会以 obj[key]=value 的方式存储于对象中。该元素主要用于 dict 子类，也可以用于那些实现了 __setitem__() 的类。

object.__reduce_ex__(protocol)¶

作为替代选项，也可以实现 __reduce_ex__() 方法。 此方法的唯一不同之处在于它应接受一个整型参数用于指定协议版本。 如果定义了这个函数，则会覆盖 __reduce__() 的行为。 此外，__reduce__() 方法会自动成为扩展版方法的同义词。 这个函数主要用于为以前的 Python 版本提供向后兼容的 reduce 值。

# Simple example presenting how persistent ID can be used to pickle
# external objects by reference.
importpickle
importsqlite3
fromcollectionsimportnamedtuple
# Simple class representing a record in our database.
MemoRecord=namedtuple("MemoRecord","key, task")
classDBPickler(pickle.Pickler):
defpersistent_id(self,obj):
# Instead of pickling MemoRecord as a regular class instance, we emit a
# persistent ID.
ifisinstance(obj,MemoRecord):
# Here, our persistent ID is simply a tuple, containing a tag and a
# key, which refers to a specific record in the database.
return("MemoRecord",obj.key)
else:
# If obj does not have a persistent ID, return None. This means obj
# needs to be pickled as usual.
returnNone
classDBUnpickler(pickle.Unpickler):
def__init__(self,file,connection):
super().__init__(file)
self.connection=connection
defpersistent_load(self,pid):
# This method is invoked whenever a persistent ID is encountered.
# Here, pid is the tuple returned by DBPickler.
cursor=self.connection.cursor()
type_tag,key_id=pid
iftype_tag=="MemoRecord":
# Fetch the referenced record from the database and return it.
cursor.execute("SELECT * FROM memos WHERE key=?",(str(key_id),))
key,task=cursor.fetchone()
returnMemoRecord(key,task)
else:
# Always raises an error if you cannot return the correct object.
# Otherwise, the unpickler will think None is the object referenced
# by the persistent ID.
raisepickle.UnpicklingError("unsupported persistent object")
defmain():
importio
importpprint
# Initialize and populate our database.
conn=sqlite3.connect(":memory:")
cursor=conn.cursor()
cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")
tasks=(
'give food to fish',
'prepare group meeting',
'fight with a zebra',
)
fortaskintasks:
cursor.execute("INSERT INTO memos VALUES(NULL, ?)",(task,))
# Fetch the records to be pickled.
cursor.execute("SELECT * FROM memos")
memos=[MemoRecord(key,task)forkey,taskincursor]
# Save the records using our custom DBPickler.
file=io.BytesIO()
DBPickler(file).dump(memos)
print("Pickled records:")
pprint.pprint(memos)
# Update a record, just for good measure.
cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")
# Load the records from the pickle data stream.
file.seek(0)
memos=DBUnpickler(file,conn).load()
print("Unpickled records:")
pprint.pprint(memos)
if__name__=='__main__':
main()

f=io.BytesIO()
p=pickle.Pickler(f)
p.dispatch_table=copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass]=reduce_SomeClass

classMyPickler(pickle.Pickler):
dispatch_table=copyreg.dispatch_table.copy()
dispatch_table[SomeClass]=reduce_SomeClass
f=io.BytesIO()
p=MyPickler(f)

copyreg.pickle(SomeClass,reduce_SomeClass)
f=io.BytesIO()
p=pickle.Pickler(f)

classTextReader:
"""Print and number lines in a text file."""
def__init__(self,filename):
self.filename=filename
self.file=open(filename)
self.lineno=0
defreadline(self):
self.lineno+=1
line=self.file.readline()
ifnotline:
returnNone
ifline.endswith('\n'):
line=line[:-1]
return"%i: %s"%(self.lineno,line)
def__getstate__(self):
# Copy the object's state from self.__dict__ which contains
# all our instance attributes. Always use the dict.copy()
# method to avoid modifying the original state.
state=self.__dict__.copy()
# Remove the unpicklable entries.
delstate['file']
returnstate
def__setstate__(self,state):
# Restore instance attributes (i.e., filename and lineno).
self.__dict__.update(state)
# Restore the previously opened file's state. To do so, we need to
# reopen it and read from it until the line count is restored.
file=open(self.filename)
for_inrange(self.lineno):
file.readline()
# Finally, save the file.
self.file=file

>>> reader=TextReader("hello.txt")
>>> reader.readline()
'1: Hello world!'
>>> reader.readline()
'2: I am line number two.'
>>> new_reader=pickle.loads(pickle.dumps(reader))
>>> new_reader.readline()
'3: Goodbye!'

>>> importpickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0

importbuiltins
importio
importpickle
safe_builtins={
'range',
'complex',
'set',
'frozenset',
'slice',
}
classRestrictedUnpickler(pickle.Unpickler):
deffind_class(self,module,name):
# Only allow safe classes from builtins.
ifmodule=="builtins"andnameinsafe_builtins:
returngetattr(builtins,name)
# Forbid everything else.
raisepickle.UnpicklingError("global '%s.%s' is forbidden"%
(module,name))
defrestricted_loads(s):
"""Helper function analogous to pickle.loads()."""
returnRestrictedUnpickler(io.BytesIO(s)).load()

>>> restricted_loads(pickle.dumps([1,2,range(15)]))
[1, 2, range(0, 15)]
>>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
Traceback (most recent call last):
...
pickle.UnpicklingError: global 'os.system' is forbidden
>>> restricted_loads(b'cbuiltins\neval\n'
... b'(S\'getattr(__import__("os"), "system")'
... b'("echo hello world")\'\ntR.')
Traceback (most recent call last):
...
pickle.UnpicklingError: global 'builtins.eval' is forbidden

importpickle
# An arbitrary collection of objects supported by pickle.
data={
'a':[1,2.0,3,4+6j],
'b':("character string",b"byte string"),
'c':{None,True,False}
}
withopen('data.pickle','wb')asf:
# Pickle the 'data' dictionary using the highest protocol available.
pickle.dump(data,f,pickle.HIGHEST_PROTOCOL)

importpickle
withopen('data.pickle','rb')asf:
# The protocol version used is detected automatically, so we do not
# have to specify it.
data=pickle.load(f)