Pandas Input/Output 完全指南：从 Pickle 到 Iceberg 的官方 I/O API 全解析

Pandas Input/Output 完全指南：从 Pickle 到 Iceberg 的官方 I/O API 全解析

【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas

导读

本文基于 pandas 官方 API 参考文档doc/source/reference/io.rst编写，系统梳理 pandas 数据读写（I/O）的完整 API 面：从最基础的 Pickle、CSV 文本文件，到 Excel、JSON、HTML、XML、LaTeX 等结构化格式，再到 HDF5、Feather、Parquet、Iceberg、ORC 等列式二进制格式，以及 SAS、SPSS、SQL、STATA 等统计与数据库生态。读者将掌握每种格式的入口函数、核心参数、适用场景与底层实现机制，并能在实际项目中按需选择合适的存储与交换方案。

总览：pandas 的 I/O API 版图

pandas 将绝大部分数据读写能力统一收敛到pandas.io包下。以 pandas/io/api.py 中__all__列表为准，顶层可用的读取函数共有：

read_clipboard、read_csv、read_excel、read_feather、read_fwf、read_hdf、read_html、read_iceberg、read_json、read_orc、read_parquet、read_pickle、read_sas、read_spss、read_sql、read_sql_query、read_sql_table、read_stata、read_table、read_xml，以及写入函数to_pickle和类ExcelFile、ExcelWriter、HDFStore。

官方参考文档 doc/source/reference/io.rst 将这些 API 按格式分为 13 个大类，本文逐一展开，并在每节结合仓库源码给出实现层面的补充说明。

Pickling：Python 原生序列化

关联 API：read_pickle、DataFrame.to_pickle

import pandas as pd original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)}) pd.to_pickle(original_df, "./dummy.pkl") # 写入 unpickled_df = pd.read_pickle("./dummy.pkl") # 读回

底层实现位于 pandas/io/pickle.py：

• to_pickle(obj, filepath_or_buffer, compression="infer", protocol=pickle.HIGHEST_PROTOCOL, storage_options=None)通过get_handle打开文件句柄后直接pickle.dump。源码注释明确说明"letting pickle write directly to the buffer is more memory-efficient"，即直接写入缓冲区比中间构造额外对象更省内存。
• protocol支持负值，传入负数时等价于pickle.HIGHEST_PROTOCOL。
• compression="infer"时，会根据扩展名自动推断压缩格式，支持.gz、.bz2、.zip、.xz、.zst、.tar及组合（如.tar.gz）。也可传入字典精细控制，例如compression={"method": "gzip", "compresslevel": 1, "mtime": 1}可生成可复现的 gzip 归档。
• read_pickle还支持从 S3、GCS 等远程 URL 读取（需要s3fs等可选依赖），并通过storage_options传递连接参数。

注意两点：

1. 安全性：文档明确警告"Loading pickled data received from untrusted sources can be unsafe"。pickle 本质是任意代码执行载体，只应读取可信来源的数据。
2. 兼容性：read_pickle只保证与当前或上一大版本创建的 pickle 向后兼容。例如 pandas 3.x 最早可读取 2.0.0 生成的 pickle（见 pandas/io/pickle.py 的 Notes 说明）。

Flat file：CSV 与定宽文本

关联 API：read_table、read_csv、DataFrame.to_csv、read_fwf，以及底层迭代器TextFileReader（含read、get_chunk、close方法）。

read_csv与read_table都定义在 pandas/io/parsers/readers.py 中，前者是 CSV（逗号分隔）的专用入口，后者默认以sep="\t"读取制表符分隔的表格文件，二者共享同一套_read_shared关键字参数。核心参数分组如下：

分块读取：当iterator=True或指定chunksize时，read_csv返回TextFileReader（来自pandas.io.parsers模块）而非DataFrame。随后可用get_chunk(n)逐块获取数据，处理完调用close()释放资源，非常适合超大文件的流式处理。

read_fwf用于读取固定宽度（Fixed-Width Format）文件，例如来自旧式主机系统的导出数据，此时需通过colspecs或widths显式声明每列的起止位置。

Clipboard：系统剪贴板

关联 API：read_clipboard、DataFrame.to_clipboard

df.to_clipboard(sep=",") # 将 DataFrame 以 CSV 文本复制到剪贴板 new_df = pd.read_clipboard() # 从剪贴板文本读回 DataFrame

实现位于 pandas/io/clipboards.py，底层复用了to_csv/read_csv的解析链路（默认以制表符分隔），在需要与 Excel、电子表格软件快速交换数据时非常实用。

Excel

关联 API：read_excel、DataFrame.to_excel、ExcelFile（含book、sheet_names、parse）、ExcelWriter、Styler.to_excel。

df = pd.read_excel("data.xlsx", sheet_name="Sheet1", index_col=0) # 读取指定工作表 df.to_excel("out.xlsx", sheet_name="结果", index=False) # 写入，去掉索引列 with pd.ExcelWriter("multi.xlsx") as writer: # 一个文件写多个工作表 df1.to_excel(writer, sheet_name="a") df2.to_excel(writer, sheet_name="b")

• ExcelFile（定义于 pandas/io/excel/_base.py）用于惰性打开工作簿，sheet_names列出全部工作表名，parse(sheet_name, ...)解析指定表；book暴露底层引擎对象（如openpyxl的Workbook）。
• read_excel支持sheet_name传字符串、整数（从 0 开始的下标）、列表或None（读取全部工作表，返回dict[str, DataFrame]）。
• 引擎自动按扩展名选择：.xlsx用openpyxl、.xls用xlrd、.ods用odf，也可通过engine参数强制指定。
• Styler.to_excel可将带样式（单元格格式、条件格式、列宽等）的 Styler 对象写出，实现"所见即所得"的报表导出。

JSON

关联 API：read_json、json_normalize、DataFrame.to_json、build_table_schema、JsonReader。

read_json定义于 pandas/io/json/_json.py，支持多种orient布局，是理解该 API 的关键：

默认规则：typ="frame"时默认orient="columns"；typ="series"时默认orient="index"，且 series 只允许split、records、index三种。注意index与columns两种 orient 要求索引唯一，records要求列名唯一。

其他常用参数：

• lines=True：按行读取 JSON Lines（每行一个 JSON 对象），配合chunksize可返回JsonReader迭代器实现流式解析；
• dtype：True（推断）或列名到类型的字典；传入False可完全关闭类型推断；
• convert_dates、keep_default_dates：日期列自动转换。默认"datelike"列名特征为以_at、_time结尾，或以timestamp开头，或名为modified、date（两个参数在 3.1.0 起已弃用，官方建议改用dtype=False或读后pd.to_datetime）；
• date_unit：强制指定时间戳单位s/ms/us/ns；
• precise_float=True：使用更高精度的strtod解析浮点数；
• engine：默认"ujson"（高速 C 实现），可切换"pyarrow"等引擎。

json_normalize用于把嵌套 JSON（如列表嵌套字典）扁平化为记录表；build_table_schema（来自pandas.io.json）生成符合 Table Schema 规范的 JSON 结构，与orient="table"互通。

HTML

关联 API：read_html、DataFrame.to_html、Styler.to_html。

read_html（pandas/io/html.py）利用lxml/bs4+html5lib等解析器从 HTML 页面中提取<table>表格并返回DataFrame列表（一个页面往往含多张表，通过match参数用正则筛选目标表）。to_html将 DataFrame 渲染为 HTML 表格字符串或文件，Styler.to_html则输出带 CSS 样式的完整可发布报表。

XML

关联 API：read_xml、DataFrame.to_xml。

df = pd.read_xml("data.xml", xpath=".//record") # 用 XPath 定位要解析的节点 df.to_xml("out.xml", root_name="data", row_name="record")

read_xml（pandas/io/xml.py）基于lxml（或etree），用 XPath 表达式从 XML 文档提取数据；to_xml反向将 DataFrame 序列化为 XML，支持自定义根节点名root_name与行节点名row_name。

LaTeX

关联 API：DataFrame.to_latex、Styler.to_latex。

print(df.to_latex(index=False)) # 生成可直接插入 .tex 文档的表格代码

to_latex输出 LaTeXtabular/longtable环境代码；Styler.to_latex还能把样式（如高亮、加粗）一并转换为 LaTeX 命令，适合学术论文表格自动化生成。

HDFStore：PyTables（HDF5）

关联 API：read_hdf、HDFStore全家族方法：put、append、append_to_multiple、get、select、select_as_coordinates、select_as_multiple、select_column、remove、create_table_index、copy、flush、info、is_open、keys、groups、get_storer、walk。

HDFStore（pandas/io/pytables.py）提供类字典风格的 HDF5 文件接口：

with pd.HDFStore("store.h5") as store: store.put("df1", df1, format="table") # 写入（键-对象存储） store.append("df1", df_more) # 追加行 df2 = store["df1"] # 读取 store.remove("df1") # 删除

format="table"（对应append/select）支持条件查询、追加与索引（create_table_index）；format="fixed"（对应put）写入更快但不可追加。HDFStore的方法如select_as_coordinates返回行坐标、select_column只取单列、walk遍历键层级、info输出文件结构摘要，适合管理大规模分块存储的时序数据。

文档警告：可以将DataFrame或Series的子类存入 HDF5，但子类类型会在存储时丢失（读回得到的是基类），序列化前请确认不依赖子类特有行为。

Feather

关联 API：read_feather、DataFrame.to_feather。

Feather 是 Apache Arrow 生态下的轻量列式二进制格式（pandas/io/feather_format.py），写入极快且与 R 的feather包互通。适合进程间快速交换与语言间共享数据，但不保留索引（索引会被当作普通列处理）。

Parquet

关联 API：read_parquet、DataFrame.to_parquet。

df.to_parquet("data.parquet", compression="zstd") # 写入，压缩 df2 = pd.read_parquet("data.parquet") # 读回

Parquet（pandas/io/parquet.py）是 Hadoop/Spark 生态标准的列式存储，支持嵌套结构、谓词下推与高压缩比，是大数据分析的首选格式。engine可选"pyarrow"（推荐，功能最全）或"fastparquet"；compression支持snappy、gzip、zstd等。它能完整保留索引与数据类型，相比 Feather 更适合长期归档。

Iceberg（实验性）

关联 API：read_iceberg、DataFrame.to_iceberg。

df.to_iceberg("catalog.db.table", catalog=my_catalog) # 写入 Iceberg 表 df2 = pd.read_iceberg("catalog.db.table", catalog=my_catalog)

Iceberg 是面向数据湖的高性能表格式，支持 ACID 事务、快照与时间旅行。实现位于 pandas/io/iceberg.py。注意文档警告：read_iceberg目前为实验性功能（experimental），API 可能在后续版本无预警地变化，生产环境使用需谨慎评估。

ORC

关联 API：read_orc、DataFrame.to_orc。

ORC（Optimized Row Columnar，pandas/io/orc.py）是 Hive 生态的列式格式，压缩效率高，与 Hive/Spark 集成密切。pandas 中读写 ORC 依赖pyarrow。

SAS

关联 API：read_sas。

read_sas（pandas/io/sas/sasreader.py）读取 SAS 的.sas7bdat数据库文件与.xpt传输格式，是读取统计分析软件 SAS 数据的标准入口（只读，无写入 API）。

SPSS

关联 API：read_spss。

read_spss（pandas/io/spss.py）读取 SPSS 的.sav文件，支持转换变量标签与值标签。仓库中内置了.sav测试样本（见pandas/tests/io目录），可验证读取行为。

SQL

关联 API：read_sql_table、read_sql_query、read_sql、DataFrame.to_sql。

import sqlalchemy engine = sqlalchemy.create_engine("sqlite:///mydb.sqlite") df.to_sql("mytable", engine, if_exists="replace") # 整表写入 df2 = pd.read_sql_table("mytable", engine) # 整表读取 df3 = pd.read_sql_query("SELECT * FROM mytable WHERE x > 10", engine) df4 = pd.read_sql("mytable", engine) # 智能分发：表名走 read_sql_table，SQL 走 read_sql_query

三者均定义于 pandas/io/sql.py：

• read_sql_table：整表读取，支持columns、index_col、parse_dates、chunksize分块迭代；
• read_sql_query：执行任意 SQL 查询并返回 DataFrame；
• read_sql：根据第一个参数是表名还是 SQL 字符串自动分发到上述两者；
• to_sql：支持if_exists（fail/replace/append）、index、dtype（指定 SQL 列类型）等参数，可通过method="multi"批量插入提升效率。

STATA

关联 API：read_stata、DataFrame.to_stata，以及StataReader.data_label、StataReader.value_labels、StataReader.variable_labels、StataWriter.write_file。

read_stata（pandas/io/stata.py）读取.dta文件，关键参数：

• convert_dates=True：Stata 内部日期整数自动转 pandas 时间戳；
• convert_categoricals=True：将带值标签的变量还原为category类型；
• convert_missing=False：是否保留 Stata 的扩展缺失值（.a~.z）；
• preserve_dtypes=True、order_categoricals=True：保持原始数据类型与类别顺序；
• index_col、columns：选择索引列与子集列；
• chunksize/iterator：分块读取返回StataReader。

StataReader还暴露data_label（数据集标签）、variable_labels（变量标签字典）、value_labels（值标签字典）等元数据访问属性；StataWriter.write_file完成写出。pandas 同样提供to_stata以 DataFrame 写出.dta，方便 R 等 Stata 用户回读。

写入端的统一视角：to_*系列

文档中所有格式几乎都成对提供读/写入口。除了上述to_pickle、to_csv、to_excel、to_json、to_html、to_xml、to_latex、to_hdf（pandas/io/pytables.py）、to_feather、to_parquet、to_orc、to_iceberg、to_sql、to_stata、to_clipboard之外，仓库中 pandas/io/api.py 显示to_pickle是顶层独立导出的通用序列化函数，而 DataFrame 方法DataFrame.to_*与模块级pd.to_*通常共享同一底层实现。

选型建议（依据各格式在仓库中的实现定位与文档说明）：

• 临时缓存 / 对象保真：Pickle（任意 Python 对象、速度快，但不可跨语言且需注意安全与版本兼容）；
• 文本交换 / 通用性：CSV（read_csv，生态最广，但无类型信息）；
• 跨语言列式存储：Parquet（大数据生态标准，压缩与谓词下推好）、Feather（轻量快速、与 Arrow/R 互通）、ORC（Hive 生态）；
• 数据湖表格式：Iceberg（实验性，支持 ACID 与快照）；
• 统计软件互操作：STATA（.dta）、SAS（.sas7bdat）、SPSS（.sav）；
• 数据库持久化：SQL（to_sql+read_sql，配合 SQLAlchemy）；
• 报表发布：Excel（多工作表 + 样式）、HTML、LaTeX。

进一步阅读

• 用户指南doc/source/user_guide/io.rst提供各格式的详细教程与完整参数示例；
• API 参考的完整索引见 doc/source/reference/index.rst；
• 各格式均有配套测试样本与用例，例如pandas/tests/io下的csv、excel、parquet、json、stata等子目录，可作为理解边界行为的第一手资料。

【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas