dill 0.3.9

关于Dill

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

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

dill 可用于将 Python 对象存储到文件中，但其主要用途是将 Python 对象作为字节流通过网络发送。 dill 非常灵活，允许任意用户定义的类和函数进行序列化。因此，dill 并未旨在防止错误构造或恶意构造的数据。用户需要自行决定他们反序列化的数据是否来自可信源。

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

主要特性

dill 可以序列化以下标准类型

• none, type, bool, int, float, complex, bytes, str,

• tuple, list, dict, file, buffer, builtin,

• Python 类，namedtuples，dataclasses，metaclasses，

• 类的实例，

• set，frozenset，array，函数，异常

dill 还可以序列化更多“奇特”的标准类型

• 带 yields 的函数，嵌套函数，lambda，

• cell，method，unboundmethod，module，code，methodwrapper，

• methoddescriptor，getsetdescriptor，memberdescriptor，wrapperdescriptor，

• dictproxy，slice，notimplemented，ellipsis，quit

dill 目前还不能序列化以下标准类型

• frame，generator，traceback

dill 还提供了以下功能

• 保存和加载 Python 解释器会话

• 保存和从函数和类中提取源代码

• 交互式诊断序列化错误

当前版本

dill 的最新发布版本可在以下网址获取

http://pypi.ac.cn/project/dill

dill 根据 3-clause BSD 许可证分发。

开发版本

您可以在以下网址获取包含所有最新功能的最新开发版本

https://github.com/uqfoundation

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

安装

dill 可以使用 pip 安装

$ 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 的替代品。现有代码可以通过以下方式更新为允许完全序列化

>>> 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，它提供了如 pickle 跟踪等工具。

>>> 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 如何通过首先存储 _create_function（底层代码对象 Co）和 _create_code（用于处理代码对象）来存储 lambda（F1），然后处理全局字典的引用（D2）以及其他字典（D1 和 D2），这些字典保存 lambda 对象的状态。# 标记对象实际存储的时间。

更多信息

开始使用最好的方式是查看 http://dill.rtfd.io 的文档。还可以查看 dill.tests，其中包含一系列脚本，展示了 dill 如何序列化不同的 Python 对象。您可以使用 python -m dill.tests 运行测试套件。任何 pickle 文件的内容都可以使用 undill 检查。由于 dill 遵循 pickle 接口，因此 http://docs.pythonlang.cn/library/pickle.html 中的示例和文档也适用于 dill（如果使用 import dill as pickle）。源代码也通常有很好的文档，因此可以通过检查代码本身来解决进一步的问题。请随时在 github 上提交问题，或在 stackoverflow 上提问（@Mike McKerns）。如果您想分享您如何在工作中使用 dill，请发送电子邮件（至 mmckerns at uqfoundation dot org）。

引用

如果您使用 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

请参阅 https://uqfoundation.github.io/project/pathos 或 http://arxiv.org/pdf/1202.1056 获取更多信息。