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 个大类本文逐一展开并在每节结合仓库源码给出实现层面的补充说明。PicklingPython 原生序列化关联 APIread_pickle、DataFrame.to_pickleimport 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.pyto_pickle(obj, filepath_or_buffer, compressioninfer, protocolpickle.HIGHEST_PROTOCOL, storage_optionsNone)通过get_handle打开文件句柄后直接pickle.dump。源码注释明确说明letting pickle write directly to the buffer is more memory-efficient即直接写入缓冲区比中间构造额外对象更省内存。protocol支持负值传入负数时等价于pickle.HIGHEST_PROTOCOL。compressioninfer时会根据扩展名自动推断压缩格式支持.gz、.bz2、.zip、.xz、.zst、.tar及组合如.tar.gz。也可传入字典精细控制例如compression{method: gzip, compresslevel: 1, mtime: 1}可生成可复现的 gzip 归档。read_pickle还支持从 S3、GCS 等远程 URL 读取需要s3fs等可选依赖并通过storage_options传递连接参数。注意两点安全性文档明确警告Loading pickled data received from untrusted sources can be unsafe。pickle 本质是任意代码执行载体只应读取可信来源的数据。兼容性read_pickle只保证与当前或上一大版本创建的 pickle 向后兼容。例如 pandas 3.x 最早可读取 2.0.0 生成的 pickle见 pandas/io/pickle.py 的 Notes 说明。Flat fileCSV 与定宽文本关联 APIread_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关键字参数。核心参数分组如下分组参数说明列与索引headerinfer自动推断表头行也支持headerNone或传入行号序列实现多级表头names自定义列名列表index_colNone指定用作行索引的列支持多列形成 MultiIndexusecolsNone只读取部分列可传列名列表或可调用函数通用解析dtypeNone强制指定列类型如{id: int32, score: float64}engineNonecC 解析器默认或python纯 Python功能更全但更慢converters逐列应用转换函数skiprows、skipfooter、nrows跳过头尾行、仅读前 N 行缺失值na_valuesNone自定义哪些值被视为 NaNkeep_default_naTrue表示在自定义基础上保留默认 NA 集合na_filterTrue、skip_blank_linesTrue是否启用缺失值过滤、是否跳过空行日期处理parse_dates、date_format自动解析日期列或按指定格式解析分块读取当iteratorTrue或指定chunksize时read_csv返回TextFileReader来自pandas.io.parsers模块而非DataFrame。随后可用get_chunk(n)逐块获取数据处理完调用close()释放资源非常适合超大文件的流式处理。read_fwf用于读取固定宽度Fixed-Width Format文件例如来自旧式主机系统的导出数据此时需通过colspecs或widths显式声明每列的起止位置。Clipboard系统剪贴板关联 APIread_clipboard、DataFrame.to_clipboarddf.to_clipboard(sep,) # 将 DataFrame 以 CSV 文本复制到剪贴板 new_df pd.read_clipboard() # 从剪贴板文本读回 DataFrame实现位于 pandas/io/clipboards.py底层复用了to_csv/read_csv的解析链路默认以制表符分隔在需要与 Excel、电子表格软件快速交换数据时非常实用。Excel关联 APIread_excel、DataFrame.to_excel、ExcelFile含book、sheet_names、parse、ExcelWriter、Styler.to_excel。df pd.read_excel(data.xlsx, sheet_nameSheet1, index_col0) # 读取指定工作表 df.to_excel(out.xlsx, sheet_name结果, indexFalse) # 写入去掉索引列 with pd.ExcelWriter(multi.xlsx) as writer: # 一个文件写多个工作表 df1.to_excel(writer, sheet_namea) df2.to_excel(writer, sheet_nameb)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关联 APIread_json、json_normalize、DataFrame.to_json、build_table_schema、JsonReader。read_json定义于 pandas/io/json/_json.py支持多种orient布局是理解该 API 的关键orient布局结构适用typsplit{index: [...], columns: [...], data: [...]}frame / seriesrecords[{column: value}, ...]每行一个对象frame / seriesindex{index: {column: value}}frame / seriescolumns{column: {index: value}}framevalues纯值数组frametable{schema: {...}, data: {...}}携带完整表结构 schemaframe默认规则typframe时默认orientcolumnstypseries时默认orientindex且 series 只允许split、records、index三种。注意index与columns两种 orient 要求索引唯一records要求列名唯一。其他常用参数linesTrue按行读取 JSON Lines每行一个 JSON 对象配合chunksize可返回JsonReader迭代器实现流式解析dtypeTrue推断或列名到类型的字典传入False可完全关闭类型推断convert_dates、keep_default_dates日期列自动转换。默认datelike列名特征为以_at、_time结尾或以timestamp开头或名为modified、date两个参数在 3.1.0 起已弃用官方建议改用dtypeFalse或读后pd.to_datetimedate_unit强制指定时间戳单位s/ms/us/nsprecise_floatTrue使用更高精度的strtod解析浮点数engine默认ujson高速 C 实现可切换pyarrow等引擎。json_normalize用于把嵌套 JSON如列表嵌套字典扁平化为记录表build_table_schema来自pandas.io.json生成符合 Table Schema 规范的 JSON 结构与orienttable互通。HTML关联 APIread_html、DataFrame.to_html、Styler.to_html。read_htmlpandas/io/html.py利用lxml/bs4html5lib等解析器从 HTML 页面中提取table表格并返回DataFrame列表一个页面往往含多张表通过match参数用正则筛选目标表。to_html将 DataFrame 渲染为 HTML 表格字符串或文件Styler.to_html则输出带 CSS 样式的完整可发布报表。XML关联 APIread_xml、DataFrame.to_xml。df pd.read_xml(data.xml, xpath.//record) # 用 XPath 定位要解析的节点 df.to_xml(out.xml, root_namedata, row_namerecord)read_xmlpandas/io/xml.py基于lxml或etree用 XPath 表达式从 XML 文档提取数据to_xml反向将 DataFrame 序列化为 XML支持自定义根节点名root_name与行节点名row_name。LaTeX关联 APIDataFrame.to_latex、Styler.to_latex。print(df.to_latex(indexFalse)) # 生成可直接插入 .tex 文档的表格代码to_latex输出 LaTeXtabular/longtable环境代码Styler.to_latex还能把样式如高亮、加粗一并转换为 LaTeX 命令适合学术论文表格自动化生成。HDFStorePyTablesHDF5关联 APIread_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。HDFStorepandas/io/pytables.py提供类字典风格的 HDF5 文件接口with pd.HDFStore(store.h5) as store: store.put(df1, df1, formattable) # 写入键-对象存储 store.append(df1, df_more) # 追加行 df2 store[df1] # 读取 store.remove(df1) # 删除formattable对应append/select支持条件查询、追加与索引create_table_indexformatfixed对应put写入更快但不可追加。HDFStore的方法如select_as_coordinates返回行坐标、select_column只取单列、walk遍历键层级、info输出文件结构摘要适合管理大规模分块存储的时序数据。文档警告可以将DataFrame或Series的子类存入 HDF5但子类类型会在存储时丢失读回得到的是基类序列化前请确认不依赖子类特有行为。Feather关联 APIread_feather、DataFrame.to_feather。Feather 是 Apache Arrow 生态下的轻量列式二进制格式pandas/io/feather_format.py写入极快且与 R 的feather包互通。适合进程间快速交换与语言间共享数据但不保留索引索引会被当作普通列处理。Parquet关联 APIread_parquet、DataFrame.to_parquet。df.to_parquet(data.parquet, compressionzstd) # 写入压缩 df2 pd.read_parquet(data.parquet) # 读回Parquetpandas/io/parquet.py是 Hadoop/Spark 生态标准的列式存储支持嵌套结构、谓词下推与高压缩比是大数据分析的首选格式。engine可选pyarrow推荐功能最全或fastparquetcompression支持snappy、gzip、zstd等。它能完整保留索引与数据类型相比 Feather 更适合长期归档。Iceberg实验性关联 APIread_iceberg、DataFrame.to_iceberg。df.to_iceberg(catalog.db.table, catalogmy_catalog) # 写入 Iceberg 表 df2 pd.read_iceberg(catalog.db.table, catalogmy_catalog)Iceberg 是面向数据湖的高性能表格式支持 ACID 事务、快照与时间旅行。实现位于 pandas/io/iceberg.py。注意文档警告read_iceberg目前为实验性功能experimentalAPI 可能在后续版本无预警地变化生产环境使用需谨慎评估。ORC关联 APIread_orc、DataFrame.to_orc。ORCOptimized Row Columnarpandas/io/orc.py是 Hive 生态的列式格式压缩效率高与 Hive/Spark 集成密切。pandas 中读写 ORC 依赖pyarrow。SAS关联 APIread_sas。read_saspandas/io/sas/sasreader.py读取 SAS 的.sas7bdat数据库文件与.xpt传输格式是读取统计分析软件 SAS 数据的标准入口只读无写入 API。SPSS关联 APIread_spss。read_spsspandas/io/spss.py读取 SPSS 的.sav文件支持转换变量标签与值标签。仓库中内置了.sav测试样本见pandas/tests/io目录可验证读取行为。SQL关联 APIread_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_existsreplace) # 整表写入 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_tableSQL 走 read_sql_query三者均定义于 pandas/io/sql.pyread_sql_table整表读取支持columns、index_col、parse_dates、chunksize分块迭代read_sql_query执行任意 SQL 查询并返回 DataFrameread_sql根据第一个参数是表名还是 SQL 字符串自动分发到上述两者to_sql支持if_existsfail/replace/append、index、dtype指定 SQL 列类型等参数可通过methodmulti批量插入提升效率。STATA关联 APIread_stata、DataFrame.to_stata以及StataReader.data_label、StataReader.value_labels、StataReader.variable_labels、StataWriter.write_file。read_statapandas/io/stata.py读取.dta文件关键参数convert_datesTrueStata 内部日期整数自动转 pandas 时间戳convert_categoricalsTrue将带值标签的变量还原为category类型convert_missingFalse是否保留 Stata 的扩展缺失值.a~.zpreserve_dtypesTrue、order_categoricalsTrue保持原始数据类型与类别顺序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_hdfpandas/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 对象、速度快但不可跨语言且需注意安全与版本兼容文本交换 / 通用性CSVread_csv生态最广但无类型信息跨语言列式存储Parquet大数据生态标准压缩与谓词下推好、Feather轻量快速、与 Arrow/R 互通、ORCHive 生态数据湖表格式Iceberg实验性支持 ACID 与快照统计软件互操作STATA.dta、SAS.sas7bdat、SPSS.sav数据库持久化SQLto_sqlread_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考