Python 居然能监听每一行代码的执行,调试器和覆盖率工具原来是这样做到的

有一次我在用 pytest-cov 跑覆盖率，看着那个百分比一行行出来，突然想到一个问题：它怎么知道哪行被执行了？

又有一次我在用 pdb 调试，设了断点，程序停在那一行不动了。这件事我用了三年，从来没想过背后是怎么实现的。

然后有一天我翻文档，翻到了 sys.settrace。

Python 有一个追踪钩子

Python 解释器在执行代码的时候，有一个内置的追踪机制。你可以注册一个回调函数，解释器每执行一行代码、每调用一个函数、每抛出一个异常，都会来调你这个函数。

这不是什么野路子，是官方提供的接口：

import sys

def tracer(frame, event, arg):
    print(f"[{event}] {frame.f_code.co_filename}:{frame.f_lineno}")
    return tracer  # 必须返回自身，才能继续追踪子调用

sys.settrace(tracer)

def add(a, b):
    result = a + b
    return result

x = add(3, 4)
print(x)

sys.settrace(None)  # 关闭追踪

输出：

[call] test.py:10
[line] test.py:11
[line] test.py:12
[return] test.py:12
[call] test.py:14
[line] test.py:14
7

每一行代码执行前，追踪函数都被调用了一次。frame 是当前栈帧，里面有文件名、行号、局部变量；event 是事件类型；arg 因事件而不同。

这就是 pdb、coverage.py、pytest-cov 的底层基础。

event 有哪些类型

主要有四种：

| event | 触发时机 | arg 的值 |

|-------|----------|----------|

| call | 函数被调用 | None |

| line | 将要执行某一行 | None |

| return | 函数即将返回 | 返回值 |

| exception | 抛出了异常 | (type, value, traceback) |

用它写一个迷你覆盖率工具

知道了原理，自己写一个玩玩非常有趣：

import sys
from collections import defaultdict

# 记录每个文件的哪些行被执行了
executed_lines = defaultdict(set)

def coverage_tracer(frame, event, arg):
    if event == "line":
        filename = frame.f_code.co_filename
        lineno = frame.f_lineno
        executed_lines[filename].add(lineno)
    return coverage_tracer

def show_coverage(filename):
    import ast, textwrap

    with open(filename) as f:
        source = f.read()

    lines = source.splitlines()
    executed = executed_lines.get(filename, set())

    print(f"\n--- 覆盖率报告: {filename} ---")
    for i, line in enumerate(lines, start=1):
        marker = "+" if i in executed else " "
        print(f"  {marker} {i:3d} | {line}")


# 被追踪的代码
def compute(numbers):
    total = 0
    for n in numbers:
        if n > 0:
            total += n
        else:
            total -= n  # 这行会不会被覆盖到？
    return total


sys.settrace(coverage_tracer)

result = compute([1, 2, 3])   # 只传了正数

sys.settrace(None)

print(f"结果: {result}")
show_coverage(__file__)

输出（关键部分）：

结果: 6

--- 覆盖率报告: demo.py ---
    ...
  + 17 |     total = 0
  + 18 |     for n in numbers:
  + 19 |         if n > 0:
  + 20 |             total += n
    21 |         else:
    22 |             total -= n  # 这行没被执行到
  + 23 |     return total

第 22 行没被覆盖到，因为传进去的都是正数，else 分支从没走过。这就是覆盖率工具做的事情，不过是 C 实现的，快很多。

用它写一个迷你调试器

更好玩的来了。我们可以在特定条件下暂停执行，让用户查看当前状态：

import sys

breakpoints_set = set()

def mini_debugger(frame, event, arg):
    lineno = frame.f_lineno
    filename = frame.f_code.co_filename

    if event == "line" and lineno in breakpoints_set:
        print(f"\n[断点] {filename}:{lineno}")
        print(f"局部变量: {frame.f_locals}")

        while True:
            cmd = input("(debug) > ").strip()
            if cmd == "c":   # continue
                break
            elif cmd == "q":  # quit
                sys.settrace(None)
                raise SystemExit("用户退出调试")
            elif cmd.startswith("p "):   # print variable
                var_name = cmd[2:]
                val = frame.f_locals.get(var_name, "<未定义>")
                print(f"{var_name} = {val!r}")
            else:
                print("命令：c(继续) / q(退出) / p <变量名>")

    return mini_debugger


def process_data(data):
    result = []
    for item in data:         # 在这里设断点
        processed = item * 2
        result.append(processed)
    return result


# 设置断点在第几行（import 之后从实际行号算）
import inspect
src_lines = inspect.getsourcelines(process_data)
start_line = src_lines[1]
breakpoints_set.add(start_line + 2)  # for 循环体第一行

sys.settrace(mini_debugger)
output = process_data([10, 20, 30])
sys.settrace(None)

print(f"最终结果: {output}")

运行后，每次循环体被执行，程序都会停下来等用户输入：

[断点] demo.py:35
局部变量: {'data': [10, 20, 30], 'result': [], 'item': 10}
(debug) > p item
item = 10
(debug) > c

[断点] demo.py:35
局部变量: {'data': [10, 20, 30], 'result': [20], 'item': 20}
(debug) > c
...
最终结果: [20, 40, 60]

这就是 pdb 最核心的运作方式。当然 pdb 做了更多——处理多线程、管理调用栈、支持单步执行，但基础原理就是 sys.settrace。

用它做函数调用追踪

有时候我想知道一段代码究竟调用了哪些函数、顺序是什么，打日志太麻烦，用追踪一行搞定：

import sys

call_stack = []
depth = 0

def call_tracer(frame, event, arg):
    global depth
    if event == "call":
        func_name = frame.f_code.co_name
        filename = frame.f_code.co_filename.split("/")[-1]
        indent = "  " * depth
        print(f"{indent}-> {func_name} ({filename}:{frame.f_lineno})")
        depth += 1
    elif event == "return":
        depth -= 1
    return call_tracer


def c():
    return 42

def b():
    return c() + 1

def a():
    return b() * 2


sys.settrace(call_tracer)
result = a()
sys.settrace(None)

print(f"\n结果: {result}")

输出：

-> a (demo.py:20)
  -> b (demo.py:16)
    -> c (demo.py:13)

结果: 86

层级清晰，调用链一目了然。在排查复杂的嵌套调用问题时，这种方式比打 print 日志强多了。

有几个需要知道的点

性能开销很大。sys.settrace 在每一行执行时都会调用 Python 函数，开销极高。生产环境不要用，专门用于调试和开发阶段。

多线程要用 threading.settrace。sys.settrace 只对当前线程生效，如果要追踪所有线程，需要用 threading.settrace(tracer) 加上 sys.settrace。

追踪函数必须返回自身。如果你想继续追踪子函数调用，call 事件时返回的追踪函数会被用于子调用。如果返回 None，子调用不会被追踪。

为什么这东西值得了解

不是说你要自己写调试器。而是当你下次看到 coverage 报告里的百分比，或者 pdb 在某一行停住了，你知道背后发生了什么——Python 在每一行执行前都会问一句：有人要监听吗？

这种透明度是 Python 的设计哲学之一。语言把自己的运行机制暴露出来，让你可以在上面构建工具。

理解这一层，不是为了炫技，是为了在遇到奇怪的调试问题时，你有多一种角度去思考它。

最后，别忘了关注「有为大青年」，我们下期见~

看完如果有收获，点个赞，让更多人看到这篇文章。欢迎在评论区聊聊你有没有用过 settrace 做过什么有趣的事。