pandas df.to_pickle() 序列化为 pickle 文件

pandas 的 DataFrame.to_pickle 方法用于将 DataFrame 对象序列化并保存为 pickle 文件。Pickle 是 Python 的一种用于序列化和反序列化对象的二进制格式，适用于保存和加载 Python 对象，包括 DataFrame。

支持的数据类型

DataFrame.to_pickle 方法主要用于 pandas.DataFrame 对象，但实际上也可以用于其他 pandas 对象如 Series 等，因为它们也是可序列化的。保存的数据类型必须是可以被 pickle 序列化的 Python 对象。

语法

如果参数较多，代码可以分行显示：

DataFrame.to_pickle(
    path, 
    *, 
    compression='infer', 
    storage_options=None
)

参数说明

• path (str 或类似路径对象)：保存 pickle 文件的路径，可以是本地文件路径或支持的远程存储路径（如 S3、HDFS 等）。

• compression (str 或 None, 可选)：指定压缩方式。默认值为 'infer'，即根据文件扩展名自动推断是否需要压缩和使用何种压缩算法。可选的压缩方式包括 'gzip'、'bz2'、'zip'、'xz' 或 None（不压缩）。

• storage_options (dict, 可选)：用于指定存储后端的额外参数，如远程存储的凭证信息等。具体取决于存储后端的实现。

返回值

该方法没有返回值。它会将 DataFrame 对象序列化并保存到指定的 path。

使用场景

1. 数据持久化：将处理后的 DataFrame 保存为 pickle 文件，以便后续快速加载，避免重复计算。

2. 数据传输：在不同 Python 环境之间传输 DataFrame 对象。

3. 备份和恢复：作为数据备份的一种方式，可以在需要时恢复数据。

4. 跨版本使用：在支持 pickle 的情况下，可以在不同的 pandas 版本之间保存和加载数据。

示例说明

以下示例展示了如何使用 DataFrame.to_pickle 方法保存和加载 DataFrame 对象。

示例 1：基本使用

import pandas as pd

# 构造示例数据
data = {
    '姓名': ['张三', '李四', '王五'],
    '年龄': [28, 34, 29],
    '城市': ['北京', '上海', '广州']
}
df = pd.DataFrame(data)

# 保存为 pickle 文件
df.to_pickle('dataframe.pkl')

# 加载 pickle 文件
loaded_df = pd.read_pickle('dataframe.pkl')

print(loaded_df)

输出内容：

   姓名  年龄 城市
0  张三   28  北京
1  李四   34  上海
2  王五   29  广州

示例 2：使用压缩

import pandas as pd

# 构造示例数据
data = {
    '产品': ['A', 'B', 'C'],
    '价格': [100, 200, 150],
    '库存': [50, 80, 65]
}
df = pd.DataFrame(data)

# 保存为压缩的 pickle 文件（使用 gzip 压缩）
df.to_pickle('products.pkl.gz', compression='gzip')

# 加载压缩的 pickle 文件
loaded_df = pd.read_pickle('products.pkl.gz', compression='gzip')

print(loaded_df)

输出内容：

  产品   价格  库存
0  A  100   50
1  B  200   80
2  C  150   65

示例 3：指定协议版本

import pandas as pd

# 构造示例数据
data = {
    '日期': pd.date_range(start='2023-01-01', periods=5, freq='D'),
    '值': [10, 20, 30, 40, 50]
}
df = pd.DataFrame(data)

# 保存为 pickle 文件，使用协议版本 4
df.to_pickle('dates.pkl', protocol=4)

# 加载 pickle 文件
loaded_df = pd.read_pickle('dates.pkl')

print(loaded_df)

输出内容：

         日期  值
0 2023-01-01  10
1 2023-01-02  20
2 2023-01-03  30
3 2023-01-04  40
4 2023-01-05  50

示例 4：使用远程存储（假设使用 S3）

import pandas as pd

# 构造示例数据
data = {
    '用户': ['Alice', 'Bob', 'Charlie'],
    '积分': [1200, 1500, 900]
}
df = pd.DataFrame(data)

# 保存到 S3，假设已经配置了 AWS 凭证
df.to_pickle('s3://my-bucket/dataframe_s3.pkl', storage_options={
    'key': 'YOUR_AWS_ACCESS_KEY',
    'secret': 'YOUR_AWS_SECRET_KEY'
})

# 加载 S3 上的 pickle 文件
loaded_df = pd.read_pickle('s3://my-bucket/dataframe_s3.pkl', storage_options={
    'key': 'YOUR_AWS_ACCESS_KEY',
    'secret': 'YOUR_AWS_SECRET_KEY'
})

print(loaded_df)

输出内容：

        用户    积分
0    Alice  1200
1      Bob  1500
2  Charlie   900

注意事项

• 安全性：Pickle 文件可以执行任意代码，因此仅应加载来自可信来源的 pickle 文件，以避免安全风险。

• 兼容性：不同版本的 Python 或 pandas 可能导致 pickle 文件的不兼容，特别是当使用较新的协议版本时。

• 文件大小：虽然 pickle 文件通常比 CSV 等文本格式更紧凑，但在处理大型 DataFrame 时，仍需注意文件大小和存储空间。

总结

DataFrame.to_pickle 是一个高效的序列化方法，适用于需要快速保存和加载 DataFrame 对象的场景。通过合理使用压缩和协议选项，可以优化存储和加载性能。然而，需注意其安全性和兼容性问题，确保在可信环境中使用。

参考

• https://pandas.pydata.org/docs/reference/api/pandas.read_pickle.html

更新时间：Oct. 10, 2024, 9:11 a.m. 标签：pandas python pickle 序列化