Pandas 数据导入与导出

本章目标

1. 掌握 read_csv / to_csv 的核心参数与格式控制
2. 掌握 read_excel / to_excel 的多工作表读写
3. 掌握 read_json / to_json 的 orient 格式选择
4. 理解 .csv / .xlsx / .json / .parquet 四种格式的适用场景

重点方法与概念速览

名称	类型	作用
pd.read_csv(...)	函数	从 CSV/文本文件读取 DataFrame
df.to_csv(...)	方法	将 DataFrame 保存为 CSV 文件
pd.read_excel(...)	函数	从 Excel 文件读取 DataFrame
df.to_excel(...)	方法	将 DataFrame 保存为 Excel 文件
pd.read_json(...)	函数	从 JSON 字符串/文件读取 DataFrame
df.to_json(...)	方法	将 DataFrame 保存为 JSON 字符串/文件
df.to_string(...)	方法	转 DataFrame 为对齐文本（打印用）

1. CSV 读写

pd.read_csv

作用

从 CSV 文件或文本流读取数据为 DataFrame——Pandas 最常用的数据入口。支持自定义分隔符、表头位置、跳过行、指定列类型、缺失值标记等。

重点方法

pd.read_csv(filepath_or_buffer, *, sep=',', delimiter=None, header='infer',
            names=None, index_col=None, usecols=None, dtype=None,
            skiprows=None, nrows=None, na_values=None, parse_dates=False,
            encoding=None, skipinitialspace=False, skipfooter=0)

参数（核心 12 个）

参数名	类型	说明	示例取值
filepath_or_buffer	str、pathlib.Path、file-like	文件路径或可读对象	"data.csv"、StringIO(s)
sep	str	字段分隔符，默认为 ','	";"、"\t"、"\s+"
header	int、list[int]、None	用作列名的行号；None 表示无表头，默认为 'infer'	0、[0, 1]（多层列名）
names	list[str]	手动指定列名（覆盖表头），需配合 header=None	["col1", "col2"]
index_col	int、str、False 或 None	用作行索引的列，默认为 None	0、"ID"
usecols	list[int]、list[str]、函数	指定读取哪些列	[0, 1, 3]、["Name", "Age"]
dtype	dict、type	指定列的数据类型	{"Age": int}
skiprows	int、list[int]、函数	跳过文件开头的行数	2、[0, 2, 3]
nrows	int	只读取前 N 行（预览大文件）	100
na_values	str、list[str]、dict	哪些字符串识别为 NaN	["NA", "N/A", "missing"]
parse_dates	bool、list[int]、list[str]	是否自动解析日期列	True、["date_col"]
encoding	str	文件编码	"utf-8"、"gbk"

DataFrame.to_csv

作用

将 DataFrame 保存为 CSV 文本文件。

重点方法

df.to_csv(path_or_buf=None, *, sep=',', na_rep='', header=True,
          index=True, index_label=None, columns=None, encoding=None)

参数

参数名	类型	说明	示例取值
path_or_buf	str、pathlib.Path 或 None	文件路径；None 时返回字符串，默认为 None	"output.csv"
sep	str	字段分隔符，默认为 ','	";"、"\t"
na_rep	str	缺失值的文本表示，默认为 ''（空）	"NaN"、"NULL"
header	bool、list[str]	是否写入列名，默认为 True	False
index	bool	是否写入行索引，默认为 True	False
columns	list[str]	只写入指定列，默认为 None（全部）	["col1", "col2"]
encoding	str	写入编码	"utf-8"

综合示例

示例代码

import pandas as pd
import numpy as np
from io import StringIO

np.random.seed(42)
df = pd.DataFrame({
    "Name": ["Alice", "Bob", "Charlie", "David"],
    "Age": [25, 30, 35, 28],
    "Score": np.random.uniform(60, 100, 4).round(2),
    "City": ["Beijing", "Shanghai", None, "Guangzhou"],
})

# to_csv：index=False 避免写入行号
csvStr = df.to_csv(index=False)
print("生成的 CSV:")
print(csvStr)

# read_csv：从字符串读回
dfLoaded = pd.read_csv(StringIO(csvStr))
print(f"\n从 CSV 读取:\n{dfLoaded}")
print(f"往返一致: {df.drop(columns=['City']).equals(dfLoaded.drop(columns=['City']))}")

输出

生成的 CSV:
Name,Age,Score,City
Alice,25,82.38,Beijing
Bob,30,86.21,Shanghai
Charlie,35,72.0,
David,28,96.39,Guangzhou

从 CSV 读取:
      Name  Age  Score        City
0    Alice   25  82.38     Beijing
1      Bob   30  86.21    Shanghai
2  Charlie   35  72.00          NaN
3    David   28  96.39  Guangzhou

往返一致: True

理解重点

• index=False 几乎总是该加——避免把自动行号写入文件，再读取时多一列 Unnamed: 0
• pd.read_csv(StringIO(s)) 是测试 CSV 逻辑的便捷方式——无需写磁盘文件
• nrows 预览大文件结构：pd.read_csv("big.csv", nrows=5) 先看列名和类型
• CSV 中空字符串回读后对象列保持空字符串、数值列变 NaN——行为因列类型而异

2. Excel 读写

pd.read_excel

作用

从 Excel 文件（.xlsx / .xls）读取 DataFrame。支持多工作表、按列范围选取。

重点方法

pd.read_excel(io, sheet_name=0, *, header=0, names=None, index_col=None,
              usecols=None, dtype=None, skiprows=None, nrows=None, na_values=None)

参数

参数名	类型	说明	示例取值
io	str、pathlib.Path、file-like	Excel 文件路径	"data.xlsx"
sheet_name	int、str、list、None	工作表；0 第一个、"Sheet1" 指定名、None 全读（返回 dict），默认为 0	"Sheet2"、[0, 1]
header	int、list[int]	用作列名的行号，默认为 0	1
names	list[str]	手动指定列名	["A", "B", "C"]
index_col	int、str	用作行索引的列	0
usecols	list[int]、list[str]、str	指定列；支持 Excel 风格 "A:C"	"A:C"、[0, 2]
dtype	dict	列类型映射	{"Age": int}
skiprows	int、list[int]	跳过行数	2
nrows	int	读取前 N 行	50
na_values	list[str]	缺失值标记	["N/A"]

DataFrame.to_excel

作用

将 DataFrame 保存为 Excel 文件。多工作表写入需配合 ExcelWriter。

重点方法

df.to_excel(excel_writer, *, sheet_name='Sheet1', na_rep='',
            header=True, index=True, index_label=None, columns=None)

参数

参数名	类型	说明	示例取值
excel_writer	str、pathlib.Path、ExcelWriter	文件路径或写入器	"output.xlsx"
sheet_name	str	工作表名，默认为 'Sheet1'	"Results"
na_rep	str	缺失值的文本表示，默认为 ''	"N/A"
header	bool、list[str]	是否写入列名，默认为 True	False
index	bool	是否写入行索引，默认为 True	False
columns	list[str]	只写入指定列	["col1", "col2"]

理解重点

• sheet_name=None 返回 dict[str, DataFrame]——每个键是一个工作表名
• usecols="A:C" 是 Excel 风格的列范围——比数字索引更直观
• Excel 需要安装 openpyxl（.xlsx 读写）或 xlrd（旧 .xls 读）
• 多工作表写入用 with pd.ExcelWriter("out.xlsx") as w: df1.to_excel(w, sheet_name="A")

3. JSON 读写

pd.read_json

作用

从 JSON 字符串或文件读取 DataFrame。支持多种 JSON 结构方向（orient）。

重点方法

pd.read_json(path_or_buf, *, orient=None, typ='frame', dtype=None,
             convert_dates=True, lines=False, encoding=None)

参数

参数名	类型	说明	示例取值
path_or_buf	str、pathlib.Path、str	JSON 文件路径或 JSON 字符串	"data.json"、jsonStr
orient	str 或 None	JSON 结构方向；常见值自动推断，默认为 None	"records"、"columns"、"index"
typ	str	返回类型：'frame' / 'series'，默认为 'frame'	"series"
lines	bool	True 时每行是一个 JSON 对象（JSON Lines），默认为 False	True
encoding	str	文件编码	"utf-8"

DataFrame.to_json

作用

将 DataFrame 导出为 JSON 字符串或文件。

重点方法

df.to_json(path_or_buf=None, *, orient=None, date_format=None,
           double_precision=10, force_ascii=True, indent=None, lines=False)

参数

参数名	类型	说明	示例取值
path_or_buf	str 或 None	文件路径；None 返回字符串，默认为 None	"output.json"
orient	str	JSON 结构方向，下见表，默认为 None（即 'columns'）	"records"、"split"
force_ascii	bool	是否将非 ASCII 字符转义为 \uXXXX，默认为 True	False
indent	int 或 None	缩进空格数；None 紧凑输出，默认为 None	2
lines	bool	True 时写为 JSON Lines，默认为 False	True

orient 常用取值

orient	JSON 结构	适用场景
"columns"（默认）	{col: {index: value}}	数值矩阵
"records"	[{col: value}, ...]	前端 API / 数据库交互
"index"	{index: {col: value}}	索引优先结构
"split"	{columns: [...], index: [...], data: [...]}	紧凑传输（分离元数据）
"table"	含 schema 的完整描述	精度要求最高的往返

综合示例

示例代码

import pandas as pd

df = pd.DataFrame({
    "Name": ["Alice", "Bob", "Charlie"],
    "Age": [25, 30, 35],
    "City": ["Beijing", "Shanghai", "Guangzhou"],
})

# records 方向（前端友好）
jsonRecords = df.to_json(orient="records", force_ascii=False, indent=2)
print(f"records 格式:\n{jsonRecords}")

# 读回
dfRestored = pd.read_json(jsonRecords, orient="records")
print(f"\n读回:\n{dfRestored}")

# JSON Lines 格式
jsonLines = df.to_json(orient="records", lines=True)
print(f"\nJSON Lines:\n{jsonLines}")

输出

records 格式:
[
  {
    "Name":"Alice",
    "Age":25,
    "City":"Beijing"
  },
  {
    "Name":"Bob",
    "Age":30,
    "City":"Shanghai"
  },
  {
    "Name":"Charlie",
    "Age":35,
    "City":"Guangzhou"
  }
]

读回:
      Name  Age        City
0    Alice   25     Beijing
1      Bob   30    Shanghai
2  Charlie   35  Guangzhou

JSON Lines:
{"Name":"Alice","Age":25,"City":"Beijing"}
{"Name":"Bob","Age":30,"City":"Shanghai"}
{"Name":"Charlie","Age":35,"City":"Guangzhou"}

理解重点

• orient="records" 返回 [{col: val}, ...]——最接近前端 API 的 JSON 数组格式
• force_ascii=False 保留中文可读性；写对外 API 时一般设 True
• lines=True（JSON Lines）适合大数据——每行独立，可逐行追加/流式处理
• 读写 orient 必须一致：写 "records" 读不指定 orient 会解析错误

4. 其他导出格式

方法	格式	适用场景
df.to_string(...)	对齐文本	打印 DataFrame 到控制台/日志
df.to_html(...)	HTML 表格	嵌入网页或 Jupyter Notebook 渲染
df.to_sql(...)	数据库表	写入 SQL 数据库（需 SQLAlchemy 引擎）
df.to_pickle(...)	Python pickle	Python 内部快速序列化（不可跨版本/语言）
df.to_parquet(...)	Parquet 列存	大数据高效压缩+列裁剪（需 pyarrow）

格式选择指南

场景	格式	API
内部实验中间结果	.pkl	to_pickle / read_pickle
跨语言/跨工具交换	.csv	to_csv / read_csv
业务报表/人工编辑	.xlsx	to_excel / read_excel
Web API 数据交换	.json	to_json / read_json
大数据/列存分析	.parquet	to_parquet / read_parquet

常见坑

1. read_csv 遇到表头行会误读为数据——确认 header 参数与文件实际结构一致
2. to_csv(index=False) 忘了加会导致行号写入文件——再读取多一列 Unnamed: 0
3. CSV 中特殊字符串（"NA"、"NULL"、"N/A"）可能被自动识别为 NaN——用 na_values 和 keep_default_na=False 控制
4. Excel 读写需额外库：openpyxl（.xlsx）或 xlrd（.xls）——先 pip install
5. JSON 读写 orient 必须一致——写 records 但读不指定 orient 会解析失败或形状错乱
6. 中文 CSV 编码不一致是 Windows 常见问题——utf-8 / gbk / gb2312，用 encoding 参数逐个尝试

小结

• 数据入口优先 read_csv——参数最丰富、最通用；出口优先 to_csv(index=False)
• Excel 适合人工编辑的报告；JSON 适合 Web API 交换；Parquet 适合大数据分析
• 读写参数必须匹配：sep / encoding / orient 在写入端和读取端保持一致
• 大文件操作：先 nrows=100 预览结构，确认后再全量加载