Python标准库中的pickle模块



pickle  -  Python对象序列化。

        pickle模块实现了用于序列化和反序列化Python对象结构的二进制协议。“pickle”是将Python对象层次结构转换为一个字节流的过程，而“unpickle”是反向操作，即一个字节流(从二进制文件或字节类对象)转换回对象层次结构。Pickling(和unpickling)也称为“序列化”、“编组”或“扁平化”;然而，为了避免混淆，这里使用的术语是“pickling”和“unpickling”。

        警告:pickle模块不能防止错误或恶意构造的数据。从不从不可信或未经身份验证的源接收数据。

pickle模块不同于marshal的几个重要方式:

        pickle模块跟踪它已经序列化的对象，以便以后对同一对象的引用不会再次被序列化。marshal不是这样做的。

        这对递归对象和对象共享都有影响。递归对象是包含对自己的引用的对象。这些都是marshal不能处理的，事实上，marshal试图序列化递归对象会使Python解释器崩溃；对象共享发生在对象层次结构中不同位置的同一对象有多个引用时。pickle只存储此类对象一次，并确保所有其他引用指向主副本。共享对象仍然共享，这对于可变对象非常重要。

        marshal不能用于序列化用户定义的类及其实例。pickle可以透明地保存和恢复类实例，但是类定义必须是可输入的，并且与存储对象时在同一个模块中共存。

        marshal序列化格式不保证可以跨Python版本移植。因为它的主要工作是支持.pyc文件，因此Python实现者保留在需要时以非向后兼容的方式更改序列化格式的权利。pickle序列化格式保证在Python发行版中向后兼容。  

pickle与json比较

        pickle协议和JSON  (JavaScript对象表示法)之间有基本的区别:
        JSON是一种文本序列化格式(它输出unicode文本，尽管大多数时候它被编码为utf-8)，而pickle是二进制序列化格式;
        JSON是人类可读的，而pickle则不是;
        JSON在Python生态系统之外是可互操作和广泛使用的，而pickle是特定于Python的;
        默认情况下，JSON只能表示Python内置类型的一个子集，并且没有自定义类；pickle可以表示极其大量的Python类型(其中许多是自动的，通过聪明地使用Python的内省设施，复杂的情况可以通过实现特定的对象api来解决)。

数据流格式

        pickle所使用的数据格式是python特有的。这有一个优点，即没有像JSON或XDR这样的外部标准强加的限制(它们不能代表指针共享);然而，这意味着非Python程序可能无法重构pickle的Python对象。

        默认情况下，pickle数据格式使用相对紧凑的二进制表示形式。如果您需要最优的尺寸特性，您可以有效地压缩pickle数据。

        模块pickletools包含用于分析pickle生成的数据流的工具。pickletools源代码对pickle协议使用的操作码有广泛的评论。

        目前有5种不同的协议可以用于pickle。越新的Python版本，使用的pickle协议越高：
        协议版本0是最初的“人类可读”协议，并且向后兼容Python的早期版本。
        协议版本1是一种旧的二进制格式，它也与早期版本的Python兼容。
        在Python  2.3中引入了协议版本2。它提供了更有效的新式类的pickle。参考PEP  307，了解协议2所带来的改进信息。
        在Python  3.0中添加了协议版本3。它对字节对象有明确的支持，并且不能被Python  2.x  unpickle。这是默认的协议，在需要与其他Python  3版本兼容时推荐的协议。
        在Python  3.4中添加了协议版本4。它增加了对非常大的对象的支持，对更多的对象进行pickle，以及一些数据格式的优化。参考PEP  3154，了解第4号协议带来的改进信息。

模块接口         要序列化对象层次结构，只需调用dump()函数。类似地，要反序列化数据流，可以调用load()函数。但是，如果您希望对序列化和反序列化有更多的控制，则可以分别创建一个Pickler或Unpickler对象。 pickle模块提供以下常量:         pickle.HIGHEST_PROTOCOL         一个整数，最高的协议版本可用。这个值可以作为一个协议值传递给函数dump()和dumps()  以及Pickler构造函数。         pickle.DEFAULT_PROTOCOL         一个整数，用于pickle的默认协议版本。可能小于HIGHEST_PROTOCOL。目前默认的协议是3，这是为python3设计的新协议。         pickle模块提供了以下函数，使序列化相关过程更加方便:         pickle.dump(obj,  file,  protocol=None,  *,  fix_imports=True)         将pickle表示的obj写入打开的文件对象文件中。这相当于Pickler(file,  protocol).dump(obj)。         参数：         protocol-一个整数，告诉pickler使用给定的协议;支持的协议是0到HIGHEST_PROTOCOL。如果没有指定，默认是DEFAULT_PROTOCOL。如果指定了负数，则选择HIGHEST_PROTOCOL。         file-必须有一个write()方法，该方法接受单个字节的参数。因此，它可以是一个用于二进制写入的磁盘上的文件、或一个io.BytesIO实例、或任何其他符合该接口的自定义对象。         fix_import-如果是true并且协议小于3,pickle将尝试将新的Python  3名称映射到Python  2中使用的旧模块名，这样pickle数据流就可以通过python2来读取。         pickle.dumps(obj,  protocol=None,  *,  fix_imports=True)         将对象的pickle表示作为一个字节对象返回，而不是将其写入文件。         参数协议和fix_import与dump()的相同。         pickle.load(file,  *,  fix_imports=True,  encoding="ASCII",  errors="strict")         从打开的文件对象文件中读取pickle的对象表示，并返回其中指定的重构对象层次结构。这相当于  Unpickler(file).load()。         该pickle的协议版本是自动检测的，因此不需要任何协议参数。字节经过pickle对象的表示被忽略。         参数file必须有两个方法，一个是读取整数参数的read()方法，另一个是readline()方法，不需要参数。这两种方法都应该返回字节。因此，文件可以是一个打开的磁盘文件，用于二进制读取、或一个io.BytesIO对象、或任何其他符合该接口的自定义对象。         可选的关键字参数是fix_import、encoding和errors，它们用于控制由Python  2生成的pickle流的兼容性支持。如果fix_import是True，pickle将尝试将旧的Python  2名称映射到Python  3中使用的新名称。encoding和errors告诉pickle如何解码由Python  2  pickle的8位字符串实例；这些默认值分别为“ASCII”和“strict”。编码可以是“bytes”来读取这些8位字符串实例作为字节对象。         pickle.loads(bytes_object,  *,  fix_imports=True,  encoding="ASCII",  errors="strict")         从一个字节对象中读取一个pickle的对象层次结构，并返回其中指定的重构对象层次结构。         参数请参考pickle.load。         pickle模块定义了三个异常:         异常pickle.PickleError         其他pickle异常的公共基类。它继承了异常。         异常pickle.PicklingError         在Pickler中遇到不可pickle的对象时引发的错误。它继承了PickleError。         异常pickle.UnpicklingError         当出现问题时，会引发错误，例如数据损坏或安全违规。它继承了PickleError。         注意，在unpickle期间可能还会出现其他异常，包括(但不一定限于)AttributeError、EOFError、ImportError和IndexError。

pickle模块包含两个类，Pickler和Unpickler:

        class  pickle.Pickler(file,  protocol=None,  *,  fix_imports=True)
        这需要一个二进制文件来编写pickle数据流。
        参数参考pickle.dump。

        dump(obj)
        将pickle表示的obj写入构造函数中给定的打开文件对象。

        persistent_id(obj)  #持久ID
        默认不做任何事。它存在是为了子类可以覆盖它。
        如果persistent_id()返回None，那么obj就像往常一样被pickle。任何其他值都会导致Pickler将返回的值释放为obj的持久ID。这个持久ID的含义应该由Unpickler.persistent_load()定义。请注意，persistent_id()返回的值本身不能具有持久ID。
        有关详细信息和使用示例参见外部对象的持久化。

        dispatch_table  #分派表  3.3版本中新增
        pickler对象的分派表是一种可以使用copyreg.pickle()声明的简化函数的注册表。它是一个映射，其键是类，其值是还原函数。reduce函数接受关联类的单个参数，并应遵循与__reduce__()方法相同的接口。
        默认情况下，pickler对象将没有dispatch_table属性，它将使用copyreg模块管理的全局调度表。但是，要为特定的pickler对象定制pickle，可以将dispatch_table属性设置为类似于dict的对象。或者，如果Pickler的子类具有dispatch_table属性，那么它将作为该类的实例的默认调度表。
        请参阅调度表以获得使用示例。

        fast
        已弃用。如果设置为真值，启用快速模式。快速模式禁用了备忘录的使用，因此加快了序列化过程，而不是产生多余的PUT操作码。它不应该与自引用对象一起使用，否则将会导致Pickler无限地递归。
        如果你需要更紧凑的序列化，可以使用pickletools.optimize()。

        class  pickle.Unpickler(file,  *,  fix_imports=True,  encoding="ASCII",  errors="strict")
        从一个二进制文件来读取pickle数据流。
        参数参考pickle.load

        load()
        从构造函数中给出的打开文件对象中读取pickle对象表示，并返回其中指定的重构对象层次结构。字节经过pickle对象的表示被忽略。

        persistent_load(pid)
        在默认情况下增加一个UnpicklingError。
        如果定义了，persistent_load()应该返回持久ID  pid指定的对象。如果遇到一个无效的持久ID，就应该抛出一个UnpicklingError。
        有关详细信息和使用示例的外部对象的持久化。

        find_class(module,  name)
        如果需要，导入模块，并返回名为name的对象，其中模块和名称参数是str对象。注意，与它同名函数find_class()也用于查找函数。

        子类重写以获得对对象类型的控制、以及如何加载它们从而可能降低安全风险。详细信息请参阅限制全局变量。

下列类型可以序列化：
None,  True,  and  False
integers,  floating  point  numbers,  complex  numbers
strings,  bytes,  bytearrays
tuples,  lists,  sets,  and  dictionaries  containing  only  picklable  objects
functions  defined  at  the  top  level  of  a  module  (using  def,  not  lambda)
#在模块的顶层定义的函数(使用def，而不是lambda)
built-in  functions  defined  at  the  top  level  of  a  module
#内置函数定义在模块的顶层。
classes  that  are  defined  at  the  top  level  of  a  module
#在模块的顶层定义的类。
instances  of  such  classes  whose  __dict__  or  the  result  of  calling  __getstate__()  is  picklable  (see  section  Pickling  Class  Instances  for  details).
#此类类的实例，其__dict__或调用__getstate__()的结果是可选的(详细信息请参见pickle类实例)。

        pickle  unpicklable对象的尝试有可能引发PicklingError异常。当发生这种情况时，可能已经向底层文件写入了一些字节。尝试pickle一个高度递归的数据结构可能会超过最大递归深度，在这种情况下会出现一个递归错误。您可以使用sys.setrecursionlimit()小心地提高这个限制。

        注意，函数(内置的和用户定义的)是通过“完全限定”的名称引用而不是由值来pickle的。这意味着只有函数名被pickle。函数被定义的模块的名称、函数的代码和函数的任何属性都没有被pickle。因此，在unpickle环境中，定义模块必须是可输入的，并且模块必须包含指定的对象，否则将会引发异常。

        类似地，类通过命名引用进行pickle，因此在unpickle环境中也适用相同的限制。注意，所有类的代码或数据都没有被pickle，因此在以下示例中，在unpickle环境中没有恢复class属性attr:

class  Foo:
        attr  =  'A  class  attribute'

picklestring  =  pickle.dumps(Foo)

        这些限制是为什么在模块的顶层中必须定义可选的函数和类。

        类似地，当pickle类实例时，它们的类的代码和数据不会与它们一起pickle。只有实例数据被pickle。这样做是有目的的，这样您就可以在类中修复bug，或者向类添加方法，并且仍然可以使用类的早期版本创建的对象。如果您计划使用长时间的对象，将会看到一个类的多个版本，那么在对象中放置一个版本号可能是值得的，这样可以通过类的__setstate__()方法来实现适当的转换。

Pickling  Class实例

        在本节中，我们将描述可用于定义、自定义和控制类实例如何被pickle和未pickle的通用机制。

        在大多数情况下，不需要额外的代码来让实例变得可pickle。默认情况下，pickle将通过内省检索类和实例的属性。当一个类实例被unpickle时，它的__init__()方法通常不会被调用。默认行为首先创建一个未初始化的实例，然后恢复保存的属性。下面的代码显示了这种行为的实现:

def  save(obj):         return  (obj.__class__,  obj.__dict__) def  load(cls,  attributes):         obj  =  cls.__new__(cls)         obj.__dict__.update(attributes)         return  obj

        类可以通过提供一种或几种特殊方法来改变默认行为:
        object.__getnewargs_ex__()
        在协议2和更新中，实现__getnewargs_ex__()方法的类可以指定在unpickle时传递给__new__()方法的值。该方法必须返回一对(args,  kwargs)，其中args是位置参数的元组，kwargs是一个用于构造对象的命名参数的字典。这些将被传递到unpickle的__new__()方法。
如果类的__new__()方法需要关键字参数，则应该实现此方法。否则，建议兼容实现__getnewargs__()。
        在版本3.6中更改:__getnewargs_ex__()现在在协议2和3中使用。

        object.__getnewargs__()
        此方法与__getnewargs_ex__()类似，但只支持位置参数。它必须返回一组参数args，这些参数将被传递给unpickle的__new__()方法。
        如果定义__getnewargs_ex__()，则不会调用__getnewargs__()。
        版本3.6:在Python  3.6之前，__getnewargs__()在协议2和3中被调用而不是__getnewargs_ex__()。

        object.__getstate__()
        类可以进一步影响其实例的pickle方式;如果类定义了__getstate__()方法，则调用它，将返回的对象作为实例的内容进行pickle，而不是实例字典的内容。如果缺少__getstate__()方法，那么实例的__dict__将像往常一样被pickle。

        object.__setstate__(state)
        在unpickle中，如果类定义__setstate__()，则调用unpickle状态。在这种情况下，状态对象不需要是字典。否则，pickle状态必须是一个字典，它的条目被分配给新实例的字典。

        object.__reduce__()
        接口目前定义如下。__reduce__()方法不接受任何参数，并返回一个字符串，或者最好是一个tuple(返回的对象通常被称为“reduce值”)。

        如果返回一个字符串，则该字符串应该被解释为全局变量的名称。它应该是对象的本地名称相对于它的模块；pickle模块搜索模块名称空间以确定对象的模块。这种行为通常适用于单身者。
当一个元组被返回时，它必须在2到5个项目之间。可选项可以省略，也可以不作为其值提供。每一项的语义学顺序如下:
        一个可调用的对象，它将被调用来创建对象的初始版本。
        可调用对象的一组参数。如果调用方不接受任何参数，则必须给出空元组。
        可选地，对象的状态，将被传递到对象的__setstate__()方法，如前所述。如果对象没有这样的方法，那么该值必须是一个字典，它将被添加到对象的__dict__属性中。
        可选地，一个迭代器(而不是一个序列)产生连续的项。这些项将被追加到对象中，或者使用object  .append(项)，或者在批处理中使用object  .extend(list_of_items)。这主要用于列表子类，但是其他类可以使用它，只要它们有附加()和扩展()方法并具有适当的签名。(是否使用append()或extend()取决于使用哪个pickle协议版本以及要附加的项的数量，因此必须支持这两者。)
        可选地，迭代器(不是序列)产生连续的键值对。这些项将使用obj[key]  =值存储到对象中。这主要用于字典子类，但只要实现__setitem__()，其他类就可以使用它。

        object.__reduce_ex__(protocol)
        另外，一个__reduce_ex__()方法可以定义。唯一的区别是这个方法应该使用一个整型参数协议版本。在定义时，pickle将更喜欢它而不是__reduce__()方法。此外，__reduce__()自动成为扩展版本的同义词。此方法的主要用途是为较老的Python版本提供向后兼容的reduce值。