Python 库手册：pickle 对象序列化模块

pickle 是 Python 标准库中用于对象序列化与反序列化的模块。它可以将 Python 中的任意对象转换为字节流（序列化），以便保存到文件或通过网络传输。也可将字节流恢复为原始对象（反序列化）。

常见应用场景：

（1）将模型、数据结构、配置对象保存到本地文件中。

（2）在分布式任务中传输对象。

（3）缓存复杂计算结果。

（4）存储 Python 原生数据类型（列表、字典、自定义类等）。

◆ ◆ ◆

核心概念

1、序列化（Pickling）

将 Python 对象转为可存储或传输的二进制格式。

2、反序列化（Unpickling）

将二进制数据恢复为原始对象。

3、pickle 模块只适用于 Python 内部使用，不能跨语言或长期存储（因协议版本可能变化）。

4、对象必须是“可 picklable”的，函数、打开的文件句柄、线程等不可直接序列化。

◆ ◆ ◆

应用举例

例 1： 将对象保存到文件

import pickle

data = {"name": "mediaTEA", "age": 7, "score": [95, 88, 92]}

with open("data.pkl", "wb") as f:
    pickle.dump(data, f)

例 2：从文件中加载对象

import pickle

with open("data.pkl", "rb") as f:
    loaded_data = pickle.load(f)

print(loaded_data)

例 3：序列化为字节流（不写入文件）

import pickle

numbers = [1, 2, 3, 4]
binary_data = pickle.dumps(numbers)  # 转为字节串

restored = pickle.loads(binary_data)  # 恢复为原对象
print(restored)

例 4：自定义类对象的序列化

import pickle

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

p = Person("mediaTEA", 7)

# 保存对象
with open("person.pkl", "wb") as f:
    pickle.dump(p, f)

# 读取对象
with open("person.pkl", "rb") as f:
    new_p = pickle.load(f)
print(new_p.name, new_p.age)

例 5：指定协议版本保存对象

import pickle

data = {"x": 1, "y": 2}
binary = pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL)  # 使用最新协议

◆ ◆ ◆

常用函数速览

pickle.dump(obj, file, protocol=None)

将对象序列化并写入二进制文件。

参数：

obj：要序列化的 Python 对象

file：类文件对象（以 'wb' 打开）

protocol：序列化协议版本（默认自动选择）

返回：无

pickle.load(file)

从二进制文件中读取并反序列化对象。

参数：

file：类文件对象（以 'rb' 打开）

返回：Python 对象

pickle.dumps(obj, protocol=None)

将对象序列化为字节串（不写入文件）。

参数：

obj：要序列化的对象

protocol：可选协议版本

返回：bytes 类型

pickle.loads(bytes_obj)

将字节串反序列化为 Python 对象。

参数：

bytes_obj：字节数据（由 dumps() 得到）

返回：Python 对象

pickle.HIGHEST_PROTOCOL

返回当前 Python 版本支持的最高协议号（整数），建议用于最大兼容性与性能。

◆ ◆ ◆

补充说明

1、安全性警告：pickle.load() 执行过程中可能执行任意代码，不要反序列化不可信的数据来源。

2、推荐仅用于 Python 内部程序之间的数据持久化，不建议作为通用数据交换格式。

3、若需跨语言兼容性，建议使用 或 protobuf 等格式。

4、有些对象（如文件、数据库连接、线程、生成器等）不能被 pickle 序列化。

5、使用 protocol=pickle.HIGHEST_PROTOCOL 可获得更高效的存储性能。

“点赞有美意，赞赏是鼓励”