API · Pandas
Pandas DataFrame DataFrame.to_csv() 函数
Pandas DataFrame to_csv() 函数可将 DataFrame 导出为 CSV:未指定目标位置时返回 CSV 文本;指定路径或可写文本缓冲区时写入 CSV 并返回 None。
本页内容
Python Pandas DataFrame.to_csv() 可将 DataFrame 导出为 CSV。未指定目标位置时,它会返回 CSV 文本;指定路径或可写文本缓冲区时,则会将 CSV 写入该位置并返回 None。
DataFrame.to_csv() 会写出什么内容
CSV 将各行的值用分隔符隔开,通常使用逗号,也可以带有标题行。默认情况下,to_csv() 会写出所有列,并将行索引作为第一个字段。索引与 DataFrame 的列不同,因此即使它只是默认序列 0, 1, 2, ...,也会出现在 CSV 中。如果接收系统只需要数据列,请设置 index=False。
DataFrame.to_csv() 的语法和返回值
常用参数包括 path_or_buf=None、sep=","、na_rep=""、columns=None、header=True、index=True、index_label=None、encoding=None 和 compression="infer"。其他格式参数包括 float_format、date_format、decimal、quoting 和行终止符。完整签名及特定版本的详细信息,请参阅链接中的 pandas API 参考。
path_or_buf 可以是路径,也可以是可写文本缓冲区。省略该参数时,to_csv() 会返回字符串,而不会创建文件。指定目标位置时,返回值为 None。columns 用于选择要导出的列并确定其顺序。将 header 设为 False 可以省略列名,也可以传入替代名称;index_label 用于命名索引字段。na_rep 控制缺失值的表示方式。写入文本文件时,encoding 用于指定编码;compression 可以选择压缩输出格式。数值和日期格式选项控制值的呈现方式;引号选项则处理包含分隔符、引号或换行符的字段。
将 DataFrame 写入 CSV 字符串或文件
下面的完整示例展示默认 CSV 字符串、将同一数据帧写入临时文件、选择并重命名列,以及更改分隔符。打印出的字符串末尾保留了换行符,因此每个提示标签都会从新的一行开始。代码和输出中的提示标签保持英文,分别标示默认 CSV 文本、文件写入的返回值、所选列以及使用分号分隔的输出。
运行此示例:
本节中的代码以及显示的标签或输出仍为英文。
import tempfile
import sys
from pathlib import Path
import pandas as pd
frame = pd.DataFrame(
{
"Attendance": [60, 100, 80, 78, 95],
"Name": ["Olivia", "John", "Laura", "Ben", "Kevin"],
"Obtained Marks": [90, 75, 82, 64, 45],
}
)
print("CSV text:")
sys.stdout.write(frame.to_csv())
with tempfile.TemporaryDirectory() as directory:
destination = Path(directory) / "students.csv"
print("File write returns:", frame.to_csv(destination))
print("Selected columns:")
sys.stdout.write(
frame.to_csv(columns=["Name", "Obtained Marks"], header=["Full Name", "Marks"])
)
print("Semicolon separator:")
sys.stdout.write(frame.to_csv(columns=["Name", "Obtained Marks"], sep=";"))
CSV text:
,Attendance,Name,Obtained Marks
0,60,Olivia,90
1,100,John,75
2,80,Laura,82
3,78,Ben,64
4,95,Kevin,45
File write returns: None
Selected columns:
,Full Name,Marks
0,Olivia,90
1,John,75
2,Laura,82
3,Ben,64
4,Kevin,45
Semicolon separator:
;Name;Obtained Marks
0;Olivia;90
1;John;75
2;Laura;82
3;Ben;64
4;Kevin;45
如果传入 students.csv 这样的相对文件名,Python 会相对于进程的当前工作目录解析它;该目录可能与脚本所在目录不同。如果需要明确指定目标位置,请使用完整路径。文件写入演示结束后,示例会删除临时目录。
在 CSV 中选择列、标题和索引
使用 columns 选择要导出的字段及其顺序。在示例中,导出的 Name 和 Obtained Marks 列会分别重命名为 Full Name 和 Marks;原始 DataFrame 列名不会改变。上方可选中复制的输出将索引显示为第一个没有名称的字段。设置 index=False 可省略索引;如果希望索引具有明确的标题,可以提供 index_label。
导出的 Name 和 Obtained Marks 列分别标记为 Full Name 和 Marks。该表格补充展示了上方可选中复制的 CSV 输出。
自定义分隔符和其他 CSV 输出选项
将 sep 设为接收应用所需的分隔符。示例使用分号,输出中各字段之间都以分号分隔。由于索引也包含在输出中,第一个数据列之前也会有分号。如果不需要开头的索引字段,请设置 index=False。
对于缺失值,可以将 na_rep 设为 "NA" 这样的标记;如果接收系统要求特定的数值表示方式,可以使用 float_format 或 decimal。写入文件时,encoding 很有用;选择压缩格式或根据文件名推断压缩方式时,compression 可以写出 gzip 等格式。引号选项有助于保留包含分隔符或换行符的值。请根据读取 CSV 的程序所要求的格式选择选项。