dill

序列化所有的Python对象

关于Dill

dill扩展了Python的pickle模块,用于序列化和反序列化大多数内置Python类型的Python对象。序列化是将对象转换为字节流的过程,而反序列化则是将字节流转换回Python对象层次结构的逆过程。

dill为用户提供了与pickle模块相同的接口,还包含一些额外的功能。除了pickle Python对象外,dill还提供了通过单个命令保存解释器会话状态的能力。因此,可以保存一个解释器会话,关闭解释器,将pickle文件发送到另一台计算机,打开新的解释器,解pickle会话,从而继续原始解释器会话的"保存"状态。

dill可用于将Python对象存储到文件中,但主要用途是将Python对象作为字节流通过网络发送。dill非常灵活,允许序列化任意用户定义的类和函数。因此,dill并非旨在针对错误或恶意构造的数据提供安全保护。由用户决定他们解pickle的数据是否来自可信来源。

dill是pathos的一部分,pathos是一个用于异构计算的Python框架。dill正在积极开发中,因此非常欢迎任何用户反馈、错误报告、评论或建议。问题列表位于https://github.com/uqfoundation/dill/issues,旧版列表维护在https://uqfoundation.github.io/project/pathos/query。

主要特性

dill可以pickle以下标准类型:

none, type, bool, int, float, complex, bytes, str,
tuple, list, dict, file, buffer, builtin,
Python类, namedtuples, dataclasses, metaclasses,
类的实例,
set, frozenset, array, functions, exceptions

dill还可以pickle更多"特殊"的标准类型:

带yield的函数, 嵌套函数, lambdas,
cell, method, unboundmethod, module, code, methodwrapper,
methoddescriptor, getsetdescriptor, memberdescriptor, wrapperdescriptor,
dictproxy, slice, notimplemented, ellipsis, quit

dill目前还不能pickle这些标准类型:

frame, generator, traceback

dill还提供以下功能:

保存和加载Python解释器会话
保存和提取函数和类的源代码
交互式诊断pickling错误

当前版本

dill的最新发布版本可从以下地址获得: https://pypi.org/project/dill

dill以3条款BSD许可证分发。

开发版本

您可以从以下地址获得具有所有新功能的最新开发版本: https://github.com/uqfoundation

如果您有新的贡献,请提交拉取请求。

安装

可以使用pip安装dill:

$ pip install dill

要在安装中可选包含objgraph诊断工具:

$ pip install dill[graph]

要在安装中可选包含gprof2dot诊断工具:

$ pip install dill[profile]

对于Windows用户,可选安装会话历史工具:

$ pip install dill[readline]

要求

dill需要:

python (或 pypy), >=3.8
setuptools, >=42

可选要求:

objgraph, >=1.7.2
gprof2dot, >=2022.7.29
pyreadline, >=1.7.1 (在Windows上)

基本用法

dill是pickle的直接替代品。可以使用以下方式更新现有代码以允许完全pickling:

>>> import dill as pickle

或:

>>> from dill import dumps, loads

dumps将对象转换为唯一的字节字符串,loads执行逆操作:

>>> squared = lambda x: x**2
>>> loads(dumps(squared))(3)
9

有一些选项可以控制序列化,这些选项作为关键字参数提供给几个dill函数:

使用 protocol 可以设置 pickle 协议级别。这使用与 pickle 模块相同的值 DEFAULT_PROTOCOL。
使用 byref=True 时，dill 在处理某些对象(如模块)时会更像 pickle，通过引用进行序列化而不是尝试序列化对象本身。
使用 recurse=True 时，全局字典中引用的对象会被递归追踪和序列化，而不是默认行为中尝试存储整个全局字典。
使用 fmode 时，文件内容可以与文件句柄一起序列化，这在对象被发送到没有原始文件的远程系统时很有用。选项包括仅句柄的 HANDLE_FMODE、文件内容的 CONTENTS_FMODE 和内容加句柄的 FILE_FMODE。
使用 ignore=False 时，使用顶级脚本环境中定义的类型重建的对象会使用环境中现有的类型，而不是可能不同的重建类型。

默认序列化也可以在 dill.settings 中全局设置。因此，我们可以在本地或全局修改 dill 处理全局字典引用的方式::

>>> import dill.settings
>>> dumps(absolute) == dumps(absolute, recurse=True)
False
>>> dill.settings['recurse'] = True
>>> dumps(absolute) == dumps(absolute, recurse=True)
True

dill 还包括源代码检查，作为序列化的替代方法::

>>> import dill.source
>>> print(dill.source.getsource(squared))
squared = lambda x:x**2

为了帮助调试序列化问题，使用 dill.detect 提供的工具，如序列化跟踪::

>>> import dill.detect
>>> with dill.detect.trace():
>>>     dumps(squared)
┬ F1: <function <lambda> at 0x7fe074f8c280>
├┬ F2: <function _create_function at 0x7fe074c49c10>
│└ # F2 [34 B]
├┬ Co: <code object <lambda> at 0x7fe07501eb30, file "<stdin>", line 1>
│├┬ F2: <function _create_code at 0x7fe074c49ca0>
││└ # F2 [19 B]
│└ # Co [87 B]
├┬ D1: <dict object at 0x7fe0750d4680>
│└ # D1 [22 B]
├┬ D2: <dict object at 0x7fe074c5a1c0>
│└ # D2 [2 B]
├┬ D2: <dict object at 0x7fe074f903c0>
│├┬ D2: <dict object at 0x7fe074f8ebc0>
││└ # D2 [2 B]
│└ # D2 [23 B]
└ # F1 [180 B]

通过跟踪，我们可以看到 dill 如何存储 lambda (F1)：首先存储 _create_function、底层代码对象 (Co) 和 _create_code (用于处理代码对象)，然后处理全局字典的引用 (D2) 以及其他保存 lambda 对象状态的字典 (D1 和 D2)。# 标记表示对象实际被存储的时刻。

引用

如果你使用 dill 进行研究并发表论文，我们请求你通过在出版物中引用以下内容来确认使用 dill::

M.M. McKerns, L. Strand, T. Sullivan, A. Fang, M.A.G. Aivazis,
"Building a framework for predictive science", Proceedings of
the 10th Python in Science Conference, 2011;
http://arxiv.org/pdf/1202.1056

Michael McKerns and Michael Aivazis,
"pathos: a framework for heterogeneous computing", 2010- ;
https://uqfoundation.github.io/project/pathos