Pandas：文件读写与数据接口

在数据分析实践中，数据通常并不是直接写在程序中的，而是来自外部文件，例如 CSV、Excel、JSON、HTML 表格，或数据库查询结果。与此同时，分析完成后的结果也常常需要重新保存为文件，以便共享、归档或继续处理。

在 Pandas 中，文件读写（input / output，简称 I/O）是非常重要的一部分。

所谓"读取"，是指把外部数据转换为 Pandas 可处理的数据对象，通常是 Series、DataFrame，或由 DataFrame 构成的结果对象；所谓"写出"，是指将 Pandas 中的数据对象保存到外部文件中。

Pandas 提供了一套较为完整的数据输入输出接口。它不仅支持常见的文本文件与表格文件，也支持 JSON、HTML、剪贴板、数据库等多种数据来源，并且通常能够将这些外部数据转换为 DataFrame，或返回由 DataFrame 构成的结果对象，从而与后续的数据清洗、统计分析和可视化流程自然衔接。

需要说明的是，Pandas 的"读"函数大多以 read_ 开头，例如：

go 复制代码

pd.read_csv(...)pd.read_excel(...)pd.read_json(...)

而"写"操作通常由 DataFrame 或 Series 的方法完成，例如：

go 复制代码

df.to_csv(...)df.to_excel(...)df.to_json(...)

一、文本文件读写

文本文件，尤其是 CSV（Comma-Separated Values，逗号分隔值文件），是数据分析中最常见的数据交换格式之一。

read_csv()

读取 CSV 文件，返回 DataFrame。

python 复制代码

pandas.read_csv(    filepath_or_buffer,    sep=",",    header="infer",    names=None,    index_col=None,    usecols=None,    dtype=None,    engine=None,    skiprows=None,    nrows=None,    na_values=None,    parse_dates=False,    encoding=None)

参数说明：

• filepath_or_buffer：文件路径、URL 或文件对象

• sep：分隔符，默认是逗号 ,

• header：哪一行作为列名，默认自动推断

• names：自定义列名列表

• index_col：指定哪一列作为索引

• usecols：只读取部分列

• dtype：指定列的数据类型

• engine：解析引擎

• skiprows：跳过前若干行

• nrows：只读取前若干行

• na_values：指定哪些值视为缺失值

• parse_dates：是否解析日期列

• encoding：文件编码，如 "utf-8"、"gbk" 等

示例 1：读取普通 CSV 文件

bash 复制代码

import pandas as pd
df = pd.read_csv("students.csv")print(df)

示例 2：指定分隔符

ini 复制代码

df = pd.read_csv("data.txt", sep="\t")   # 按制表符分隔

示例 3：只读取部分列

ini 复制代码

df = pd.read_csv("students.csv", usecols=["姓名", "数学", "英语"])

示例 4：指定某列为索引

ini 复制代码

df = pd.read_csv("students.csv", index_col="学号")

示例 5：解析日期列

ini 复制代码

df = pd.read_csv("sales.csv", parse_dates=["日期"])

说明：

read_csv() 是 Pandas 中最常用的数据读取函数之一。

即使文件扩展名不是 .csv，只要本质上是分隔文本，也常可通过调整 sep 参数进行读取。

to_csv()

将 DataFrame 或 Series 写出为 CSV 文件。

python 复制代码

DataFrame.to_csv(    path_or_buf=None,    sep=",",    na_rep="",    columns=None,    header=True,    index=True,    encoding=None)

参数说明：

• path_or_buf：输出路径或文件对象

• sep：分隔符，默认逗号

• na_rep：缺失值写出时的表示形式

• columns：只写出指定列

• header：是否写出列名

• index：是否写出索引

• encoding：文件编码

示例：

perl 复制代码

df.to_csv("output.csv", index=False, encoding="utf-8-sig")

说明：

index=False 很常用，用于避免把行索引额外写出文件；

在中文环境下，为了更好兼容某些表格软件，常使用 encoding="utf-8-sig"。

提示：

若不提供文件路径，to_csv() 可以返回字符串结果。

ini 复制代码

csv_text = df.to_csv(index=False)

延伸阅读：

《Python 文件操作：CSV 格式》

二、Excel 文件读写

Excel 是实际业务场景中最常见的表格文件格式之一。Pandas 提供了对 .xls、.xlsx 等格式的读取与写出支持。

read_excel()

读取 Excel 文件中的一个工作表或多个工作表。

python 复制代码

pandas.read_excel(    io,    sheet_name=0,    header=0,    names=None,    index_col=None,    usecols=None,    dtype=None,    engine=None,    skiprows=None,    nrows=None)

参数说明：

• io：文件路径、文件对象或 Excel 文件对象

• sheet_name：工作表名称或编号，默认读取第一个工作表

• header：哪一行作为列名

• names：自定义列名

• index_col：指定索引列

• usecols：指定读取哪些列

• dtype：指定数据类型

• engine：读取引擎

• skiprows：跳过前若干行

• nrows：读取的行数

示例 1：读取第一个工作表

ini 复制代码

df = pd.read_excel("scores.xlsx")

示例 2：读取指定工作表

ini 复制代码

df = pd.read_excel("scores.xlsx", sheet_name="期末成绩")

示例 3：一次读取多个工作表

ini 复制代码

tables = pd.read_excel("scores.xlsx", sheet_name=["一班", "二班"])

说明：

当 sheet_name 是列表时，返回的是一个字典，键为工作表名，值为对应的 DataFrame。

to_excel()

将 DataFrame 写出为 Excel 文件。

python 复制代码

DataFrame.to_excel(    excel_writer,    sheet_name="Sheet1",    na_rep="",    header=True,    index=True)

参数说明：

• excel_writer：输出文件路径或 ExcelWriter 对象

• sheet_name：工作表名称

• na_rep：缺失值表示形式

• header：是否写出列名

• index：是否写出索引

示例：

perl 复制代码

df.to_excel("result.xlsx", sheet_name="统计结果", index=False)

ExcelWriter

ExcelWriter 管理写出上下文，支持 openpyxl / xlsxwriter 引擎。用于将多个 DataFrame 写出同一个 Excel 文件的不同工作表。

python 复制代码

pandas.ExcelWriter(path, engine=None, mode="w")

参数说明：

• path：输出文件路径

• engine：写出引擎，如 openpyxl、xlsxwriter

• mode：写出模式，常见为 "w" 或 "a"

示例：

python 复制代码

with pd.ExcelWriter("report.xlsx") as writer:    df1.to_excel(writer, sheet_name="原始数据", index=False)    df2.to_excel(writer, sheet_name="汇总结果", index=False)

说明：

当需要导出多张表到同一个 Excel 文件时，ExcelWriter 非常常用。

提示：

Excel 文件读写通常依赖额外引擎。例如：

• 读写 .xlsx 常用 openpyxl

• 某些旧格式或特殊场景可能需要其他引擎

因此，如果运行时报缺少依赖，通常需要先安装相应库。

延伸阅读：

《Python 文件操作：Excel 格式（.xlsx）》

三、JSON 文件读写

JSON（JavaScript Object Notation）是一种非常常见的数据交换格式，尤其在 Web 接口、配置文件和前后端数据传输中使用广泛。

read_json()

读取 JSON 数据，返回 Series 或 DataFrame。

python 复制代码

pandas.read_json(    path_or_buf=None,    orient=None,    typ="frame",    dtype=None,    convert_dates=True,    encoding=None,    lines=False)

参数说明：

• path_or_buf：文件路径、URL、字符串或文件对象

• orient：JSON 的组织方式

• typ：返回类型，默认为 "frame"

• dtype：指定数据类型

• convert_dates：是否自动解析日期

• encoding：字符编码

• lines：是否按 JSON Lines 格式读取

示例 1：读取普通 JSON 文件

ini 复制代码

df = pd.read_json("data.json")

示例 2：读取 JSON Lines 文件

ini 复制代码

df = pd.read_json("logs.json", lines=True)

说明：

JSON 的结构形式较多，因此 orient 参数有时很重要。

若 JSON 是列表嵌套字典的形式，通常可以较自然地转换为 DataFrame。

to_json()

将 DataFrame 或 Series 写出为 JSON。

python 复制代码

DataFrame.to_json(    path_or_buf=None,    orient=None,    date_format=None,    force_ascii=True,    lines=False,    indent=None)

参数说明：

• path_or_buf：输出目标

• orient：JSON 结构形式

javascript 复制代码

--"records"：列表字典形式--"columns"：列优先--"index"：索引优先--"table"：包含模式信息（schema）

• date_format：日期格式

• force_ascii：是否将非 ASCII 字符转义

• lines：是否写为 JSON Lines 格式

• indent：缩进空格数

示例：

apache 复制代码

df.to_json("output.json", orient="records", force_ascii=False, indent=2)

说明：

orient="records" 常用于导出"列表 + 字典"形式的数据；

force_ascii=False 可避免中文被转义为 Unicode 编码。

延伸阅读：

《Python 文件操作：JSON 格式》

四、二进制与序列化

在某些场景下，我们并不需要把数据保存为供人直接阅读的文本格式，而是希望将 Pandas 对象以更接近程序内部结构的方式保存到磁盘中。这类做法通常称为序列化（serialization）。

在 Python 中，pickle 是一种常见的对象序列化机制。Pandas 提供了相应的读写接口，可用于保存和恢复 DataFrame 或 Series 对象。

需要注意的是，pickle 更适合 Python 程序之间的临时保存、缓存和本地恢复，而不适合作为通用的数据交换格式。

read_pickle()

读取 pickle 文件，返回反序列化后的对象。

python 复制代码

pandas.read_pickle(filepath_or_buffer, compression="infer", storage_options=None)

参数说明：

• filepath_or_buffer：文件路径、URL 或文件对象

• compression：压缩方式，默认自动推断

• storage_options：远程存储相关配置

示例：

bash 复制代码

import pandas as pd
df = pd.read_pickle("students.pkl")print(df)

说明：

read_pickle() 可读取由 Pandas 或 Python pickle 机制保存的对象。

它通常用于恢复先前保存的 DataFrame、Series 或其他 Python 对象。

但要注意，不要读取来自不可信来源的 pickle 文件，因为反序列化过程可能存在安全风险。

to_pickle()

将 DataFrame 或 Series 序列化保存为 pickle 文件。

apache 复制代码

DataFrame.to_pickle(path, compression="infer", protocol=5, storage_options=None)

参数说明：

• path：输出路径

• compression：压缩方式

• protocol：pickle 协议版本

• storage_options：远程存储相关配置

示例：

javascript 复制代码

df.to_pickle("students.pkl")

说明：

to_pickle() 会将对象按 Python pickle 格式保存。

这种方式通常比文本格式更适合完整保留对象结构，读写也较方便。

如果只是用于本地 Python 环境中的中间结果保存，它往往比 CSV 更直接。read_pickle() 与 to_pickle() 也支持若干压缩格式。

提示

pickle 的优点是保存和恢复方便，能够较完整地保留对象结构；

但它的缺点也很明显：

• 不适合跨语言交换数据

• 可读性差，不便人工查看

• 不应读取不可信来源的文件

• 在长期存档或跨版本共享场景下，通常不如 CSV、JSON、Parquet 更稳妥

五、Parquet 文件读写

Parquet 是一种面向列存储（columnar storage）的文件格式，在数据分析与数据工程中非常常见。在实际项目中，Parquet 常用于保存清洗后的结构化数据、中间分析结果，或作为数据仓库中的交换格式。

read_parquet()

读取 Parquet 文件，返回 DataFrame。

python 复制代码

pandas.read_parquet(path, engine="auto", columns=None)

常用参数说明：

• path：文件路径、URL，或支持的文件对象

• engine：读取引擎，默认 "auto"，通常使用 pyarrow 或 fastparquet

• columns：指定只读取哪些列

其他参数会随 Pandas 版本与底层引擎而变化，初学阶段重点掌握常用参数即可。

示例 1：读取 Parquet 文件

bash 复制代码

import pandas as pd
df = pd.read_parquet("students.parquet")print(df)

示例 2：只读取部分列

bash 复制代码

df = pd.read_parquet("students.parquet", columns=["姓名", "数学"])print(df)

说明：

Parquet 是列式存储格式，因此只读取部分列时通常更高效。这也是它相较于 CSV 的一个重要优势。

to_parquet()

将 DataFrame 或 Series 写出为 Parquet。

perl 复制代码

DataFrame.to_parquet(    path,    engine="auto",    compression="snappy",    index=None)

参数说明：

• path：输出路径

• engine：写出引擎，如 pyarrow、fastparquet

• compression：压缩方式，如 "snappy"

• index：是否写出索引

示例：

perl 复制代码

df.to_parquet("students.parquet", index=False)

说明：

to_parquet() 用于将 DataFrame 保存为 Parquet 文件。Parquet 采用列式存储，通常更适合中大型数据集的高效保存与读取。

read_parquet() 通常依赖额外库支持。常见引擎包括：

• pyarrow

• fastparquet

如果运行时报错提示缺少依赖，通常需要先安装相应库。

例如，很多环境中更常见的是安装 pyarrow 后再读取 Parquet 文件。

延伸阅读：

《Python 文件操作：Parquet 文件》

六、HTML 表格读写

在网页数据采集或报表展示中，Pandas 也支持 HTML 表格的读取与生成。

read_html()

从 HTML 页面或 HTML 字符串中读取表格。

python 复制代码

pandas.read_html(    io,    match=".+",    flavor=None,    header=None,    index_col=None,    encoding=None)

参数说明：

• io：网页地址、HTML 字符串或文件对象

• match：匹配表格内容的正则表达式

• flavor：HTML 解析器

• header：哪一行作为列名

• index_col：指定索引列

• encoding：字符编码

示例：

ini 复制代码

tables = pd.read_html("tables.html")df = tables[0]   # 取第一个表格

说明：

read_html() 返回的是 DataFrame 列表，因为一个 HTML 页面可能包含多个表格。

to_html()

将 DataFrame 写出为 HTML 表格。

python 复制代码

DataFrame.to_html(    buf=None,    columns=None,    header=True,    index=True,    na_rep="NaN",    border=None)

参数说明：

• buf：输出目标

• columns：输出哪些列

• header：是否输出列名

• index：是否输出索引

• na_rep：缺失值显示方式

• border：表格边框宽度

示例：

ini 复制代码

html = df.to_html(index=False)

说明：

to_html() 常用于快速生成网页表格、报告片段或调试查看结果。

七、剪贴板读写

在日常办公场景中，有时数据来自表格软件、网页或文本编辑器的复制操作。Pandas 提供了与系统剪贴板交互的接口。

read_clipboard()

从剪贴板读取表格数据。

python 复制代码

pandas.read_clipboard(sep=r"\s+")

参数说明：

• sep：分隔规则，默认按空白字符分隔

示例：

ini 复制代码

df = pd.read_clipboard()

说明：

如果用户先从 Excel、网页表格或文本中复制了一段表格数据，再调用 read_clipboard()，Pandas 往往可以直接识别为 DataFrame。

to_clipboard()

将 DataFrame 或 Series 写入系统剪贴板。

python 复制代码

DataFrame.to_clipboard(excel=True, sep=None, **kwargs)

参数说明：

• excel：是否以适合表格软件粘贴的格式输出

• sep：分隔符

示例：

perl 复制代码

df.to_clipboard(index=False)

说明：

写入剪贴板后，可以直接粘贴到 Excel、文本编辑器或其他应用中。

八、数据库读写

在更正式的数据分析工作流中，数据往往存储在关系型数据库中。Pandas 提供了与 SQL 数据库交互的常用函数。

read_sql()

从 SQL 查询结果或数据库表中读取数据。

sql 复制代码

pandas.read_sql(sql, con, index_col=None, coerce_float=True, params=None, parse_dates=None)

参数说明：

• sql：SQL 查询语句或表名

• con：数据库连接对象

• index_col：指定索引列

• coerce_float：是否将数字自动转为浮点数

• params：SQL 参数

• parse_dates：日期列解析

示例 1：读取查询结果

javascript 复制代码

import sqlite3import pandas as pd
conn = sqlite3.connect("school.db")df = pd.read_sql("SELECT * FROM students", conn)

示例 2：读取并解析日期

bash 复制代码

df = pd.read_sql(    "SELECT * FROM sales",    conn,    parse_dates=["sale_date"])

read_sql_query()

从 SQL 查询语句读取结果。

sql 复制代码

pandas.read_sql_query(sql, con, index_col=None, params=None, parse_dates=None)

示例：

bash 复制代码

df = pd.read_sql_query(    "SELECT name, score FROM students WHERE score >= 80",    conn)

read_sql_table()

从数据库表中直接读取数据。

python 复制代码

pandas.read_sql_table(table_name, con, schema=None, index_col=None, columns=None)

说明：

read_sql_table() 用于直接按表名读取数据库表，通常需要配合 SQLAlchemy 连接对象使用；若需要执行查询语句或进行更灵活的筛选，read_sql_query() 更常用。

to_sql()

将 DataFrame 写入数据库表。

python 复制代码

DataFrame.to_sql(    name,    con,    schema=None,    if_exists="fail",    index=True,    index_label=None,    chunksize=None,    dtype=None)

参数说明：

• name：表名

• con：数据库连接对象

• schema：数据库模式

• if_exists：表已存在时的处理方式，可取 "fail"、"replace"、"append"

• index：是否将索引写出数据库

• index_label：索引列名

• chunksize：分批写出行数

• dtype：指定数据库字段类型

示例：

perl 复制代码

df.to_sql("students", conn, if_exists="replace", index=False)

说明：

to_sql() 在数据导入数据库、批量写出分析结果、构建简单数据仓库时十分常用。

九、通用保存参数

虽然 Pandas 不同格式的写出函数名称不同，但很多保存参数具有相似含义，值得统一理解。

index

是否保存索引。

perl 复制代码

df.to_csv("a.csv", index=False)df.to_excel("a.xlsx", index=False)

说明：

若索引只是默认整数索引，通常不必写出；

若索引本身有实际意义（如日期索引、学号索引），则可考虑保留。

columns

只保存部分列。

javascript 复制代码

df.to_csv("a.csv", columns=["姓名", "数学"])

说明：

适用于导出子集结果，避免输出整张表。

na_rep

指定缺失值在文件中的表示形式。

javascript 复制代码

df.to_csv("a.csv", na_rep="缺失")

说明：

在与人工查看、报表导出结合时，常常需要把 NaN 替换为更直观的文字。

encoding

指定编码格式。

javascript 复制代码

df.to_csv("a.csv", encoding="utf-8-sig")

说明：

编码问题在中文环境中尤其重要。若读取时出现乱码，常常需要检查：

• 文件原始编码

• read_*() 中的 encoding

• 保存时的编码设置是否一致

十、文件读写中的常见注意事项

1、读入后应先查看数据基本情况

无论使用哪种读取函数，通常都建议先查看：

bash 复制代码

print(df.head())print(df.info())print(df.shape)

这有助于确认：

• 列名是否正确

• 数据类型是否合理

• 缺失值是否存在

• 行列数量是否符合预期

2、列名、索引与数据类型需要特别留意

例如：

• 日期列是否真正被解析为日期类型

• 数字列是否因混入非数字字符而变成字符串类型

• 本应作为索引的列是否仍留在普通列中

这些问题会直接影响后续排序、分组、绘图和建模。

3、缺失值与空字符串并不完全相同

读入文件时，有些空白单元格会被识别为 NaN，但有些文本字段中的空字符串 "" 并不会自动变成缺失值。因此在清洗数据前，常常需要进一步检查数据内容。

4、大文件读取应考虑分块处理

对于很大的文本文件，可以结合 chunksize 分块读取，而不是一次全部载入内存。

示例：

apache 复制代码

for chunk in pd.read_csv("big_data.csv", chunksize=10000):    print(chunk.shape)

说明：

这种方式适合处理超大规模日志、交易记录或监控数据。

5、写出前应考虑目标软件的兼容性

例如：

• 导出给 Excel 使用时，CSV 编码常选 utf-8-sig

• 导出给 Web 接口使用时，JSON 的 orient 形式要与接口约定一致

• 导出数据库时，要注意表结构与字段类型是否匹配

📘 小结

Pandas 提供了面向多种数据来源与存储格式的读写接口，包括文本、表格、JSON、序列化对象、列式存储和数据库等，可在外部数据与 DataFrame 之间高效转换。掌握常见 I/O 函数及其关键参数，是数据获取、保存、共享与后续分析的重要基础。

"点赞有美意，赞赏是鼓励"