Python内置csv模块读写文件基础教程
本教程详细介绍Python内置csv模块的核心功能与使用方法,涵盖reader、writer、DictReader与DictWriter的基础读写、换行符处理及常见避坑指南。
处理结构化表格数据是日常编程中的高频需求。在Python生态中,虽然第三方数据分析库功能丰富,但标准库内置的csv模块无需安装任何依赖,能够以极低资源开销完成标准CSV(Comma-Separated Values,逗号分隔值)文件的读取、写入与字段转义解析。本文将直接从核心机制展开,详解基于列表与字典的两种读写路径,并梳理常见编码与格式陷阱。
一、为什么使用内置csv模块而非普通文本操作
CSV文件本质是纯文本文件,每行代表一条数据记录,字段之间默认用逗号分隔。很多初学者倾向于直接使用字符串的split(',')与join(',')进行解析和拼接,但这在实际业务场景中极易崩溃。
根据RFC 4180规范,当字段内部本身含有逗号、双引号或跨行换行符时,该字段必须由一对双引号包裹;若字段文本中包含双引号,则需用两个连续的双引号("")进行转义。普通字符串切分无法感知这种包裹语义,必然造成字段错位与数据损坏。Python内置的csv模块封装了底层语法分析器,能够自动化处理所有符合规范的引号转义与边界换行。
二、使用 csv.reader 读取文件
csv.reader接受一个已经打开的文本文件对象,并返回一个行迭代器。每次迭代读取一行,返回由字符串元素组成的列表。
1. 基础读取与行遍历
import csv
# 读取已有 CSV 文件
with open('users.csv', 'r', encoding='utf-8') as f:
reader = csv.reader(f)
for row in reader:
print(row)
假设users.csv内容如下:
姓名,年龄,城市
张三,25,北京
李四,30,"上海,浦东"
程序控制台将输出解析后的Python列表:
['姓名', '年龄', '城市']
['张三', '25', '北京']
['李四', '30', '上海,浦东']
可以看到,虽然第三行中“上海,浦东”内部含有逗号,但csv.reader正确识别了外部引号,将其完整保留在单个列表项中。
2. 提取表头与按列索引访问
由于csv.reader返回的是迭代器,可以利用内置函数next()提前提取首行表头:
import csv
with open('users.csv', 'r', encoding='utf-8') as f:
reader = csv.reader(f)
header = next(reader) # 消费掉第一行并提取为列表
print("表头信息:", header)
for row in reader:
# 通过数字索引获取特定列,注意数据类型默认为字符串
name = row[0]
age = int(row[1])
city = row[2]
print(f"用户: {name}, 年龄: {age}, 城市: {city}")
三、使用 csv.writer 写入文件与 newline 参数
使用csv.writer将Python数据写入CSV文件时,最容易出现的问题是文件在某些系统(尤其是Windows)中每行数据之间产生不必要的空行。理解并正确设置newline=''是掌握CSV写入的关键。
1. 空行产生的根本原因
标准CSV规范采用\r\n作为行结束符。csv.writer在构造每行记录时,会自动在其末尾附加\r\n并写入底层文件对象。然而在Python的文本模式下,如果未指定newline='',底层I/O层会对换行符执行通用换行转换(Universal Newlines):在Windows上,所有\n会被系统再次映射为\r\n。这样一来,\r\n中的\n被二次转换,最终实际落盘为\r\r\n,大多数编辑器识别后都会渲染为一个空行。
因此,在调用open()打开准备写入的CSV文件时,必须显式传入newline='',通知底层I/O层不对换行符做任何二次转义,由csv模块全权掌控。
2. 单行写入与批量写入代码
import csv
header = ['产品ID', '产品名称', '单价', '库存']
rows = [
['P1001', '无线鼠标', 89.5, 120],
['P1002', '机械键盘', 299.0, 45],
['P1003', '4K显示器', 1899.0, 15]
]
# 写入操作标准范式
with open('products.csv', 'w', encoding='utf-8', newline='') as f:
writer = csv.writer(f)
# 写入单行(通常用于写入表头)
writer.writerow(header)
# 写入多行(直接传入包含多个行列表的二维结构)
writer.writerows(rows)
四、基于字典映射读写:DictReader 与 DictWriter
使用基于索引的列表读写虽然高效,但在实际工程中存在明显脆弱性:只要表格列顺序发生调整,或者增加了新的列,所有按索引取值的代码(如row[3])都会产生数据错位。为了提高代码的可读性与健壮性,内置模块提供了DictReader与DictWriter。
1. 使用 DictReader 自动映射表头
DictReader在实例化后,默认会将CSV文件的第一行读取并解析为字段名序列(fieldnames)。从第二行开始,每行数据都会被自动封装为一个Python字典,键为列名,值为对应单元格内容。
import csv
with open('products.csv', 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
print("识别到的字段名:", reader.fieldnames)
for row in reader:
# 直接通过字段名访问,不再依赖索引顺序
pid = row['产品ID']
name = row['产品名称']
price = float(row['单价'])
print(f"[{pid}] {name} - 售价: ¥{price}")
如果读取的文件本身没有表头行,可以在初始化DictReader时手动传入fieldnames参数,例如:csv.DictReader(f, fieldnames=['id', 'name', 'price', 'stock']),此时模块会将第一行当作普通数据行处理。
2. 使用 DictWriter 进行结构化写入
与读取不同,DictWriter在创建时必须显式指定fieldnames参数,以便模块知晓生成CSV文件时的列顺序和表头内容。
import csv
# 准备字典格式数据
fieldnames = ['id', 'username', 'email', 'status']
user_data = [
{'id': 1, 'username': 'admin', 'email': 'admin@example.com', 'status': 'active'},
{'id': 2, 'username': 'guest', 'email': 'guest@example.com', 'status': 'pending'}
]
with open('accounts.csv', 'w', encoding='utf-8', newline='') as f:
# 必须传入 fieldnames
writer = csv.DictWriter(f, fieldnames=fieldnames)
# 第一步:显式调用 writeheader() 写入首行表头
writer.writeheader()
# 第二步:单行写入或批量写入字典列表
for user in user_data:
writer.writerow(user)
# 也可以使用 writerows() 批量写入:
# writer.writerows(user_data)
五、常用参数配置与格式陷阱
在跨平台、跨工具(如Microsoft Excel)交换数据时,常常会遇到分隔符非逗号、引号策略不一致或中文乱码问题。内置csv模块通过一系列方言(Dialect)参数提供了灵活适配能力。
1. 自定义分隔符 delimiter
部分数据源使用制表符\t(TSV文件)或分号;作为分隔符。在创建reader或writer时传入delimiter参数即可适配:
import csv
# 读取以制表符分隔的 TSV 文件
with open('data.tsv', 'r', encoding='utf-8') as f:
reader = csv.reader(f, delimiter='\t')
for row in reader:
print(row)
2. 控制引号包裹行为 quoting
csv模块提供了4种主要引号常量(需通过import csv访问):
- csv.QUOTE_MINIMAL(默认):仅当字段包含分隔符、引号或换行符等特殊字符时才添加双引号。
- csv.QUOTE_ALL:所有字段无论是什么内容,写入时一律用双引号包裹。
- csv.QUOTE_NONNUMERIC:对非数字字段添加引号;在读取时,未加引号的字段会自动被转换为浮点数(float)。
- csv.QUOTE_NONE:不使用任何引号,遇到特殊字符时必须配置
escapechar转义符,否则写入报错。
3. Windows Excel 打开中文乱码解决方案
许多用户用Python写入UTF-8编码的CSV文件后,使用Windows系统上的Microsoft Excel双击打开会出现中文乱码。这是由于Windows版Excel在默认情况下,并不把没有BOM标记的文本识别为UTF-8,而是以系统本地编码(如GBK)解析。
解决方案非常直接:在打开文件准备写入时,将编码指定为encoding='utf-8-sig'。这会在文件最开头写入3个字节的BOM头(\xef\xbb\xbf),通知Excel以UTF-8解码:
with open('report_for_excel.csv', 'w', encoding='utf-8-sig', newline='') as f:
writer = csv.writer(f)
writer.writerow(['姓名', '部门', '绩效评分'])
writer.writerow(['张三', '技术部', 'A'])
六、技术选型决策与常见错误速查
在面对不同的任务需求时,合理选择工具组合并防范潜在错误,能够大幅减少调试成本。
高频报错与排查建议
| 报错信息 | 典型发生场景 | 排查与解决方法 |
|---|---|---|
_csv.Error: iterator should return strings, not bytes |
以二进制模式'rb'或'wb'打开文件 |
必须使用文本模式'r'或'w'打开,并显式指定字符集。 |
UnicodeDecodeError: 'utf-8' codec can't decode byte... |
读取的文件实际为GBK或ANSI编码 | 将open(..., encoding='utf-8')调整为实际源文件编码(如encoding='gbk')。 |
ValueError: dict contains fields not in fieldnames |
DictWriter写入时,传入字典包含了未在fieldnames中声明的键 | 检查传入字典是否包含多余键;若允许忽略多余字段,可在初始化时设置extrasaction='ignore'。 |
通过掌握reader/writer的基本操作规范、深入理解newline=''的底层机制,以及在复杂业务中善用DictReader/DictWriter,便可以在不引入任何外部庞大依赖的前提下,高效而可靠地完成各类CSV数据处理与交换工作。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









