Data-Science-For-Beginners 用 pd.read_csv 读取 CSV 报错怎么排查？

在 Data-Science-For-Beginners 课程的 Jupyter Notebook 或 Python 脚本里执行 pd.read_csv(...) 读 CSV 时报错，是这门课练习中常见的一类问题。本项目的 TROUBLESHOOTING.md 在 "Data and File Issues" 一节针对读数据报错给出了三类处理手段：文件找不到（FileNotFoundError）、CSV 读取报错、大文件内存报错（MemoryError），此外 "Package and Dependency Issues" 一节还覆盖了 pandas 未安装导致的 ModuleNotFoundError。本文按这几种报错把文档里的排查步骤串成一条可执行的路径。

前提条件（来自 INSTALLATION.md 与 TROUBLESHOOTING.md）：

• Python 3.7 或更高版本；
• pandas 已安装，建议安装在虚拟环境 venv 中；
• 要读取的数据文件在仓库的 data/ 目录下，例如 data/birds.csv、data/form.csv。

先确认不是 pandas 没装对

如果报错是 ModuleNotFoundError: No module named 'pandas'，问题还不在于 CSV 本身。TROUBLESHOOTING.md 给出的处理方式是：先确认虚拟环境已激活，再安装缺失的包，最后用一条命令验证安装：

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# 安装缺失的包
pip install pandas

# 验证安装
python -c "import pandas; print(pandas.__version__)"

验证成功的判断标准就是这条命令能打印出 pandas 版本号。如果装 pandas 时遇到权限或 SSL 报错，同一文档还给出了 pip install --user、pip install --upgrade pip 等对应处理，可按需对照。

FileNotFoundError：路径写法与 Notebook 位置不匹配

文件找不到是最常见的读取报错。TROUBLESHOOTING.md 给出的排查代码是：先打印当前工作目录，再改用绝对路径或相对路径，并确认文件存在：

import os

# 检查当前工作目录
print(os.getcwd())

# 使用绝对路径
data_path = os.path.join(os.getcwd(), 'data', 'filename.csv')
df = pd.read_csv(data_path)

# 或者使用相对 notebook 位置的相对路径
df = pd.read_csv('../data/filename.csv')

# 验证文件是否存在
print(os.path.exists('data/filename.csv'))

其中 filename.csv 是文档中的占位写法，需要替换成你要读取的实际文件名。这里的关键是路径的参照点：相对路径是相对 Notebook/脚本所在位置，而不是终端所在目录。仓库里的练习都是这个模式，例如 examples/02_loading_data.py 里写的是 pd.read_csv('../data/birds.csv')（脚本位于 examples/ 目录，所以向上一级再进 data/）；08-data-preparation 的 assignment 读取的是 data/form.csv。如果 os.path.exists(...) 打印 False，说明路径指向的位置没有这个文件，需要按上面的两种写法之一修正。

CSV 能打开但读取报错：编码、分隔符与缺失值

对于 TROUBLESHOOTING.md 归为 "CSV Reading Errors"（读取 CSV 文件时出错）的情况，文档没有给出"报错信息 → 原因"的一一对照，而是提供了三类读取参数供逐一尝试：

import pandas as pd

# 尝试不同的编码
df = pd.read_csv('file.csv', encoding='utf-8')
# 或
df = pd.read_csv('file.csv', encoding='latin-1')
# 或
df = pd.read_csv('file.csv', encoding='ISO-8859-1')

# 处理缺失值
df = pd.read_csv('file.csv', na_values=['NA', 'N/A', ''])

# 分隔符不是逗号时指定分隔符
df = pd.read_csv('file.csv', delimiter=';')

file.csv 同样是文档占位写法，替换为你的实际文件。三种手段各有针对对象：encoding 用于换编码读文件；na_values 用于把 NA、N/A、空串识别为缺失值；delimiter 用于文件其实不是以逗号分隔的场景。

课程练习中也有非逗号分隔的真实例子：04-stats-and-probability 的 notebook 读取 TSV 文件时用的是：

df = pd.read_csv("../../data/SOCR_MLB.tsv", sep='\t', header=None, names=['Name','Team','Role','Weight','Height','Age'])

即 .tsv 这类文件需要显式传 sep='\t'。另外 07-python 的 notebook-papers.ipynb 展示了对压缩 CSV 直接读取的写法：pd.read_csv("...metadata.csv.zip", compression='zip')，当你下载到的数据本身就是 .zip 包时可按文档中的方式处理。

大文件报 MemoryError：分块、只读部分列、指定类型

TROUBLESHOOTING.md 把 MemoryError 单列为 "Memory Errors with Large Datasets"，给出的三种手段是：

# 分块读取
chunk_size = 10000
chunks = []
for chunk in pd.read_csv('large_file.csv', chunksize=chunk_size):
    # 处理每个 chunk
    chunks.append(chunk)
df = pd.concat(chunks)

# 只读取需要的列（col1、col2 需替换为文件中的实际列名）
df = pd.read_csv('file.csv', usecols=['col1', 'col2'])

# 使用更高效的数据类型（column_name 需替换为实际列名）
df = pd.read_csv('file.csv', dtype={'column_name': 'int32'})

large_file.csv、col1、col2、column_name 均为文档中的占位写法，使用前要替换成真实文件名与列名（列名可以先看文件首行确认）。三种手段分别对应：文件大到必须分批处理时用 chunksize；只需要其中几列时用 usecols；某些列可以降级为 int32 等更小类型时用 dtype。

验证读取结果

读取成功后，按 examples/02_loading_data.py 的做法做一次快速检查，确认数据结构和内容符合预期：

data = pd.read_csv('../data/birds.csv')

print(data.shape)   # 行数 × 列数
print(data.head())  # 前 5 行预览
print(data.info())  # 各列类型与非空值数量

data.shape、data.head()、data.info() 是该脚本给出的标准检查项；如果 info() 里某列的类型明显不对（比如本该是数字的列变成了 object），通常回到上一节检查 dtype、delimiter 或 na_values 的设置。

排查仍无进展时如何求助

TROUBLESHOOTING.md 的 "How to Ask for Help" 一节要求提交 issue 时附带上这些信息：操作系统及发行版、Python 版本（python --version 的输出）、完整的错误信息、复现步骤、以及已经尝试过的方案。文档同时指出求助前应先看这份排查文档，再参考 INSTALLATION.md 和 USAGE.md。

本项目的 TROUBLESHOOTING.md 对 pd.read_csv 报错覆盖的就是上述四类：pandas 未安装、路径问题、CSV 内容问题（编码/分隔符/缺失值）、内存问题。文档没有给出针对具体报错文本的逐一判定流程，所以实操时建议按"先确认依赖 → 再确认路径与文件存在 → 再调读取参数"的顺序逐项排除，每一步都以文档给出的验证命令（python -c "import pandas; ..."、os.path.exists(...)、data.head()）作为是否继续往下走的判断依据。