Python内置csv模块读写文件基础教程

Theo
Theo
发布时间:2026-11-17| 11人浏览过
原创

本教程详细介绍Python内置csv模块的核心功能与使用方法,涵盖reader、writer、DictReader与DictWriter的基础读写、换行符处理及常见避坑指南。

处理结构化表格数据是日常编程中的高频需求。在Python生态中,虽然第三方数据分析库功能丰富,但标准库内置的csv模块无需安装任何依赖,能够以极低资源开销完成标准CSV(Comma-Separated Values,逗号分隔值)文件的读取、写入与字段转义解析。本文将直接从核心机制展开,详解基于列表与字典的两种读写路径,并梳理常见编码与格式陷阱。

一、为什么使用内置csv模块而非普通文本操作

CSV文件本质是纯文本文件,每行代表一条数据记录,字段之间默认用逗号分隔。很多初学者倾向于直接使用字符串的split(',')与join(',')进行解析和拼接,但这在实际业务场景中极易崩溃。

根据RFC 4180规范,当字段内部本身含有逗号、双引号或跨行换行符时,该字段必须由一对双引号包裹;若字段文本中包含双引号,则需用两个连续的双引号("")进行转义。普通字符串切分无法感知这种包裹语义,必然造成字段错位与数据损坏。Python内置的csv模块封装了底层语法分析器,能够自动化处理所有符合规范的引号转义与边界换行。

Python内置csv模块读写文件基础教程
图 1: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写入的关键。

Python内置csv模块读写文件基础教程
图 2:Python 读写 CSV 文件的标准 4 步规范流程

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)参数提供了灵活适配能力。

Python内置csv模块读写文件基础教程
图 3:换行控制机制、引号包裹规则与 Excel 编码兼容性对比

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'])

六、技术选型决策与常见错误速查

在面对不同的任务需求时,合理选择工具组合并防范潜在错误,能够大幅减少调试成本。

Python内置csv模块读写文件基础教程
图 4:Python csv 模块技术选型与最佳实践决策树

高频报错与排查建议

报错信息 典型发生场景 排查与解决方法
_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数据处理与交换工作。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。