Python 调试技巧：从错误现象到根因修复

明确期望
→ 稳定复现
→ 阅读错误与调用栈
→ 提出一个假设
→ 用最小实验验证
→ 修复根因
→ 增加回归测试

输入：一个尚未录入成绩的学生
期望：平均分显示“暂无成绩”
实际：抛出 ZeroDivisionError

def reproduce_empty_scores() -> None:
    student = Student("001", "测试学生", 18, "高一")
    print(student.get_average_score())


reproduce_empty_scores()

Traceback (most recent call last):
  File "student_manager.py", line 196, in main
    avg = student.get_average_score()
  File "student_manager.py", line 29, in get_average_score
    average = total / len(self.scores)
ZeroDivisionError: division by zero

print({
    "scores": self.scores,
    "count": len(self.scores),
})

len(self.scores) == 0

def get_average_score(self) -> float | None:
    """返回平均分；尚无成绩时返回 None。"""
    if not self.scores:
        return None
    return sum(self.scores.values()) / len(self.scores)

average = student.get_average_score()
if average is None:
    print("平均分: 暂无成绩")
else:
    print(f"平均分: {average:.2f}")

def test_empty_scores_have_no_average() -> None:
    student = Student("001", "测试学生", 18, "高一")
    assert student.get_average_score() is None

print(f"student_id={student_id!r}")
print(f"scores={scores!r}, type={type(scores).__name__}")
print(">>> entered calculate_class_average")

import logging

logger = logging.getLogger(__name__)

logging.basicConfig(
    level=logging.DEBUG,
    format=(
        "%(asctime)s %(levelname)s "
        "%(name)s [%(filename)s:%(lineno)d] %(message)s"
    ),
)

logger.debug("calculating average: subject=%s", subject)
logger.info("student added: id=%s", student_id)
logger.warning("duplicate student: id=%s", student_id)
logger.exception("failed to load student data")

logger = logging.getLogger("StudentManager")
logger.setLevel(logging.DEBUG)
logger.propagate = False

file_handler = logging.FileHandler(
    "student_manager.log",
    encoding="utf-8",
)
file_handler.setLevel(logging.DEBUG)

console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)

formatter = logging.Formatter(
    "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
file_handler.setFormatter(formatter)
console_handler.setFormatter(formatter)

logger.addHandler(file_handler)
logger.addHandler(console_handler)

logger.debug("这条只写入文件")
logger.info("这条同时显示在控制台和文件")

def get_average_score(self) -> float | None:
    breakpoint()
    ...

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    }
  ]
}

def get_average_score(self):
    """计算学生平均分"""
    total = sum(self.scores.values())
    # Bug：没有处理 scores 为空的情况
    return total / len(self.scores)

输入：刚创建、尚未录入成绩的学生“赵六”
期望：显示“暂无成绩”
实际：ZeroDivisionError: division by zero

student = Student("001", "赵六", 18, "高一")
print(student.get_average_score())

File "student_manager.py", line 29, in get_average_score
    average = total / len(self.scores)
ZeroDivisionError: division by zero

def get_average_score(self):
    print(f"[DEBUG] scores = {self.scores!r}")
    print(f"[DEBUG] len(scores) = {len(self.scores)}")
    total = sum(self.scores.values())
    return total / len(self.scores)

[DEBUG] scores = {}
[DEBUG] len(scores) = 0

def get_average_score(self) -> float | None:
    """返回平均分；没有任何成绩时返回 None。"""
    if not self.scores:
        return None
    return sum(self.scores.values()) / len(self.scores)

average = student.get_average_score()
if average is None:
    print("平均分：暂无成绩")
else:
    print(f"平均分：{average:.2f}")

def test_empty_scores_have_no_average():
    student = Student("001", "测试学生", 18, "高一")
    assert student.get_average_score() is None


def test_average_score_uses_all_subjects():
    student = Student("002", "测试学生", 18, "高一")
    student.scores = {"数学": 90, "英语": 80}
    assert student.get_average_score() == 85

def load_data(self):
    if os.path.exists(self.data_file):
        with open(self.data_file, "r", encoding="utf-8") as file:
            data = json.load(file)
            for student_data in data:
                student = Student(
                    student_data["student_id"],
                    student_data["name"],
                    student_data["age"],
                    student_data["grade"],
                )
                # Bug：scores 字段可能不存在
                student.scores = student_data["scores"]
                self.students[student.student_id] = student

[
  {
    "student_id": "2024001",
    "name": "张三",
    "age": 18,
    "grade": "高一"
  }
]

KeyError: 'scores'

for student_data in data:
    breakpoint()
    student.scores = student_data["scores"]

(Pdb) p student_data
{'student_id': '2024001', 'name': '张三', 'age': 18, 'grade': '高一'}
(Pdb) p 'scores' in student_data
False
(Pdb) p student_data.get('scores')
None

student.scores = student_data.get("scores", {})

def load_student(student_data: dict) -> Student:
    student = Student(
        student_data["student_id"],
        student_data["name"],
        student_data["age"],
        student_data["grade"],
    )
    student.scores = student_data.get("scores", {})
    return student

def test_load_student_without_optional_scores():
    student = load_student({
        "student_id": "001",
        "name": "张三",
        "age": 18,
        "grade": "高一",
    })
    assert student.scores == {}


def test_load_student_without_required_id_fails():
    try:
        load_student({"name": "张三", "age": 18, "grade": "高一"})
    except KeyError as exc:
        assert exc.args[0] == "student_id"
    else:
        raise AssertionError("缺少必填字段时应该失败")

def add_student(self, student_id, name, age, grade):
    # Bug：没有检查学号是否已经存在
    student = Student(student_id, name, age, grade)
    self.students[student_id] = student
    print(f"成功添加学生：{name}")
    return student

【第一次添加】成功添加学生：张三
【第二次添加同一学号】成功添加学生：重复学生
结果：张三被重复学生覆盖

logger.debug("尝试添加学生：id=%s, name=%s", student_id, name)
logger.debug("当前学生 ID：%s", list(self.students))

student = Student(student_id, name, age, grade)
self.students[student_id] = student

DEBUG 当前学生 ID：['2024001']

class DuplicateStudentError(ValueError):
    pass


def add_student(
    self,
    student_id: str,
    name: str,
    age: int,
    grade: str,
) -> Student:
    if student_id in self.students:
        raise DuplicateStudentError(
            f"学号 {student_id} 已存在"
        )

    student = Student(student_id, name, age, grade)
    self.students[student_id] = student
    return student

def test_duplicate_student_id_is_rejected():
    manager = StudentManager()
    manager.add_student("001", "张三", 18, "高一")

    try:
        manager.add_student("001", "重复学生", 18, "高一")
    except DuplicateStudentError:
        pass
    else:
        raise AssertionError("重复学号应该被拒绝")

    assert manager.students["001"].name == "张三"

def get_student(self, student_id):
    # Bug：直接访问未知键
    return self.students[student_id]

查询学号 9999999
KeyError: '9999999'

student_id: "9999999"
self.students: {"2024001": <Student>, "2024002": <Student>}
student_id in self.students: False

d = {"a": 1}
d["b"]          # KeyError
d.get("b")       # None
d.get("b", "不存在")  # "不存在"

def get_student(self, student_id: str) -> Student | None:
    return self.students.get(student_id)

class StudentNotFoundError(LookupError):
    pass


def require_student(self, student_id: str) -> Student:
    try:
        return self.students[student_id]
    except KeyError as exc:
        raise StudentNotFoundError(
            f"学号 {student_id} 不存在"
        ) from exc

def test_unknown_student_returns_none():
    manager = StudentManager()
    assert manager.get_student("9999999") is None

def calculate_class_average(self, subject):
    total = 0
    count = 0
    for student in self.students.values():
        # Bug：假设每个学生都有该科成绩
        total += student.scores[subject]
        count += 1
    return total / count

张三：{'数学': 95, '英语': 88, '物理': 92}
李四：{'数学': 78, '英语': 85}
计算物理平均分
KeyError: '物理'

for student in self.students.values():
    logger.debug("检查学生 %s：%r", student.name, student.scores)
    total += student.scores[subject]

(Pdb) p student.name
'李四'
(Pdb) p subject
'物理'
(Pdb) p student.scores
{'数学': 78, '英语': 85}
(Pdb) p subject in student.scores
False

def calculate_class_average(
    self,
    subject: str,
) -> float | None:
    scores = [
        student.scores[subject]
        for student in self.students.values()
        if subject in student.scores
    ]
    if not scores:
        return None
    return sum(scores) / len(scores)

def test_class_average_ignores_missing_subject_scores():
    manager = StudentManager()
    first = manager.add_student("001", "张三", 18, "高一")
    second = manager.add_student("002", "李四", 18, "高一")
    first.scores = {"物理": 92}
    second.scores = {"数学": 78}
    assert manager.calculate_class_average("物理") == 92

manager = StudentManager()
manager.calculate_class_average("数学")  # ZeroDivisionError

manager.add_student("001", "张三", 18, "高一")
# 学生存在，但没有任何数学成绩
manager.calculate_class_average("数学")  # 仍然是 ZeroDivisionError

print({"total": total, "count": count})

{'total': 0, 'count': 0}

if count == 0:
    return None
return total / count

def test_empty_class_has_no_average():
    manager = StudentManager()
    assert manager.calculate_class_average("数学") is None


def test_class_with_no_scores_has_no_average():
    manager = StudentManager()
    manager.add_student("001", "张三", 18, "高一")
    assert manager.calculate_class_average("数学") is None

def get_top_students(self, subject, n=3):
    students_with_scores = [
        student
        for student in self.students.values()
        if subject in student.scores
    ]
    # Bug：sorted 默认升序
    sorted_students = sorted(
        students_with_scores,
        key=lambda student: student.scores[subject],
    )
    return sorted_students[:n]

输入成绩：[95, 78, 90]
期望排名：[95, 90, 78]
实际排名：[78, 90, 95]

>>> sorted([3, 1, 4])
[1, 3, 4]
>>> sorted([3, 1, 4], reverse=True)
[4, 3, 1]

print("排序前：", [s.scores[subject] for s in students_with_scores])
print("排序后：", [s.scores[subject] for s in sorted_students])

def get_top_students(
    self,
    subject: str,
    n: int = 3,
) -> list[Student]:
    candidates = [
        student
        for student in self.students.values()
        if subject in student.scores
    ]
    return sorted(
        candidates,
        key=lambda student: student.scores[subject],
        reverse=True,
    )[:n]

def test_top_students_order():
    # 构造 95、78、90 三个成绩
    top = manager.get_top_students("数学", 3)
    scores = [student.scores["数学"] for student in top]
    assert scores == [95, 90, 78]

def generate_report(self):
    for student_id, student in self.students.items():
        print(f"学号：{student_id}")
        for subject, score in student.scores.items():
            print(f"  {subject}: {score} 分")

        # Bug：无成绩学生会在这里触发 Bug 1
        average = student.get_average_score()
        print(f"平均分：{average:.2f}")

main()
└─ generate_report()
   └─ get_average_score()
      └─ 空 scores 导致除零

import pdb
import sys


def debug_excepthook(exc_type, exc_value, traceback):
    pdb.post_mortem(traceback)


sys.excepthook = debug_excepthook

(Pdb) p student.name
'赵六'
(Pdb) p student.scores
{}
(Pdb) w

def generate_report(self):
    for student_id, student in self.students.items():
        print(f"\n学号：{student_id}")
        print(f"姓名：{student.name}")

        if not student.scores:
            print("成绩：暂无")
            print("平均分：暂无")
            continue

        print("成绩：")
        for subject, score in student.scores.items():
            print(f"  {subject}: {score} 分")

        average = student.get_average_score()
        if average is None:
            print("平均分：暂无")
        else:
            print(f"平均分：{average:.2f}")

def test_report_includes_student_without_scores(capsys):
    manager = StudentManager()
    manager.add_student("001", "赵六", 18, "高一")
    manager.generate_report()
    output = capsys.readouterr().out
    assert "成绩：暂无" in output
    assert "平均分：暂无" in output

student_id == "2024001"
subject not in student.scores
len(self.scores) == 0

type(value)
repr(value)
len(items)
key in mapping
vars(obj)
id(obj)

main()
└─ generate_report()
   └─ get_average_score()
      └─ ZeroDivisionError

step1()
step2()
check_state("after step2")
step3()
step4()
check_state("after step4")
step5()

先收集成绩
→ 再计算长度
→ 如果长度为零……

import timeit

elapsed = timeit.timeit(
    "sum(range(1000))",
    number=10_000,
)
print(f"总耗时: {elapsed:.6f}s")

# 错误
def normalize_scores(scores={}):
    scores["数学"] = 95
    return scores

def normalize_scores(
    scores: dict[str, float] | None = None,
) -> dict[str, float]:
    if scores is None:
        scores = {}
    scores["数学"] = 95
    return scores

import copy

original = {"scores": {"数学": 95}}

shallow = original.copy()
shallow["scores"]["数学"] = 100
print(original)  # 内层字典也变成 100

deep = copy.deepcopy(original)
deep["scores"]["数学"] = 60
print(original)  # 不受这次修改影响

functions = []
for index in range(3):
    functions.append(lambda: index)

print([func() for func in functions])  # [2, 2, 2]

functions = [
    (lambda value=index: value)
    for index in range(3)
]

data = json.loads('{"age": "18"}')
age = data["age"]
print(repr(age), type(age))  # '18' <class 'str'>

score = get_score("001")

if score is None:
    print("学生或成绩不存在")
elif score == 0:
    print("成绩确实为 0 分")

def calculate_average(scores: list[float]) -> float:
    if not scores:
        raise ValueError("scores 不能为空")
    if not all(0 <= score <= 100 for score in scores):
        raise ValueError("分数必须在 0～100 之间")

    average = sum(scores) / len(scores)
    assert 0 <= average <= 100
    return average

# 不推荐
try:
    load_data()
except Exception as exc:
    print(exc)

try:
    load_data()
except (OSError, json.JSONDecodeError):
    logger.exception("failed to load data")
    raise

import functools
import logging


def debug_log(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        logging.debug(
            "调用 %s，参数：args=%r, kwargs=%r",
            func.__name__,
            args,
            kwargs,
        )
        result = func(*args, **kwargs)
        logging.debug(
            "%s 返回：%r",
            func.__name__,
            result,
        )
        return result

    return wrapper

@debug_log
def add(a: int, b: int) -> int:
    return a + b

1. 先复现，不要先修改。
2. Traceback 从最后一行开始读，再沿调用栈向上找输入来源。
3. 把猜测写成可验证假设。
4. 小问题用 print，大流程用 logging，状态变化用断点。
5. 检查值、类型、长度、成员关系和对象引用。
6. 空值、0、False、None 是不同业务状态。
7. 修复函数契约和根因，不要在所有调用方重复捕获。
8. 修复后增加回归测试。
9. 性能问题用 profiler，不靠感觉。
10. 不要用 assert 校验外部输入，不要用宽泛 except 隐藏错误。