跟踪

跟踪会生成关于调用、返回、异常、执行的源代码行以及在某些情况下执行的指令的事件。

本 PEP 仅涵盖行事件。

当跟踪开启时，会在以下情况生成行事件：

• 到达新的源代码行。
• 发生向后跳转，即使它跳转到同一行，例如在列表推导中可能发生的情况。

此外，绝不会为未执行的源代码行生成行事件。

出于跟踪目的，什么是被认为是代码

所有表达式和表达式的一部分都被认为是可执行代码。

一般来说，所有语句也都被认为是可执行代码。但是，当一个语句跨越几行时，我们必须考虑语句的哪些部分被认为是可执行代码。

语句由关键字和表达式组成。并非所有关键字都具有直接的运行时效果，因此并非所有关键字都被视为可执行代码。例如，else 是 if 语句的必要部分，但 else 没有关联的运行时效果。

出于追踪目的，以下关键字将*不*被视为可执行代码

• del – 待删除的表达式被视为可执行代码。
• else – 无运行时效果
• finally – 无运行时效果
• global – 纯粹的声明性
• nonlocal – 纯粹的声明性

所有其他关键字都被认为是可执行代码。

事件序列示例

在以下示例中，事件以“名称”、f_lineno 对的形式列出。

代码

1.     global x
2.     x = a

生成以下事件

"line" 2

代码

1.     try:
2.        pass
3.     finally:
4.        pass

生成以下事件

"line" 1
"line" 2
"line" 4

代码

1.      for (
2.          x) in [1]:
3.          pass
4.      return

生成以下事件

"line" 2       # evaluate [1]
"line" 1       # for
"line" 2       # store to x
"line" 3       # pass
"line" 1       # for
"line" 4       # return
"return" 1

f_lineno 属性

• 创建帧对象时，f_lineno 属性将被设置为函数或类定义的行；即 def 或 class 关键字所在的行。对于模块，它将被设置为零。
• 即使跟踪关闭且未生成事件，f_lineno 属性也将更新以匹配即将执行的行号。

代码对象的新 co_lines() 方法

co_lines() 方法将返回一个迭代器，它生成值元组，每个元组表示一系列字节码的行号。每个元组将由三个值组成

• start – 字节码范围开始的偏移量（包含）
• end – 字节码范围结束的偏移量（不包含）
• line – 行号，如果给定范围内的字节码没有行号，则为 None。

生成的序列将具有以下属性

• 序列中的第一个范围的 start 将为 0
• (start, end) 范围将是非递减且连续的。也就是说，对于任何一对元组，第二个元组的 start 将等于第一个元组的 end。
• 没有范围是向后的，也就是说对于所有三元组，end >= start。
• 序列中的最后一个范围的 end 将等于字节码的大小。
• line 将是正整数，或 None

co_linetable 属性

co_linetable 属性将包含行号信息。格式不透明、未指定，可能会在不通知的情况下更改。该属性仅为支持创建新的代码对象而公开。

co_lnotab 属性

历史上，co_lnotab 属性保存了字节码偏移量到行号的映射，但不支持没有行号的字节码。为了向后兼容，co_lnotab 字节对象将在需要时延迟创建。对于没有行号的字节码范围，将使用前一个字节码范围的行号。

解析 co_lnotab 表的工具应尽快迁移到使用新的 co_lines() 方法。

跟踪事件序列将改变的代码示例

在以下示例中，事件以“名称”、f_lineno 对的形式列出。

0.  def spam(a):
1.      if a:
2.          eggs()
3.      else:
4.          pass

"line" 1
"line" 2
"line" 4
"return" 4

"line" 1
"line" 2
"return" 2

0.  def bar():
1.      pass
2.      pass
3.      pass

"line" 3
"return" 3

"line" 1
"line" 2
"line" 3
"return" 3

C API

通过 C API 函数访问帧对象的 f_lineno 属性不变。f_lineno 可以通过 PyFrame_GetLineNumber 读取。f_lineno 只能通过 PyObject_SetAttr 和类似函数设置。

严禁直接通过底层数据结构访问 f_lineno。

进程外调试器和分析器

进程外工具，例如 py-spy [1]，无法使用 C-API，必须自行解析行号表。尽管行号表格式可能会在没有警告的情况下更改，但除非绝对必要用于错误修复，否则在发布期间不会更改。

为了减少实现这些工具所需的工作，提供了以下 C 结构和实用函数。请注意，这些函数不属于 C-API，因此需要链接到任何需要使用它们的代码中。

typedef struct addressrange {
    int ar_start;
    int ar_end;
    int ar_line;
    struct _opaque opaque;
} PyCodeAddressRange;

void PyLineTable_InitAddressRange(char *linetable, Py_ssize_t length, int firstlineno, PyCodeAddressRange *range);
int PyLineTable_NextAddressRange(PyCodeAddressRange *range);
int PyLineTable_PreviousAddressRange(PyCodeAddressRange *range);

PyLineTable_InitAddressRange 从行号表和第一行号初始化 PyCodeAddressRange 结构体。

PyLineTable_NextAddressRange 将范围推进到下一个条目，如果有效则返回非零值。

PyLineTable_PreviousAddressRange 将范围回退到前一个条目，如果有效则返回非零值。

尽管这些函数不属于 C-API，但它们将由 CPython 的所有未来版本提供。PyLineTable_ 函数不调用 C-API，因此可以安全地复制到任何需要使用它们的工具中。PyCodeAddressRange 结构不会改变，但 _opaque 结构不属于规范的一部分，可能会改变。

例如，以下代码打印出所有地址范围

void print_address_ranges(char *linetable, Py_ssize_t length, int firstlineno)
{
    PyCodeAddressRange range;
    PyLineTable_InitAddressRange(linetable, length, firstlineno, &range);
    while (PyLineTable_NextAddressRange(&range)) {
        printf("Bytecodes from %d (inclusive) to %d (exclusive) ",
               range.start, range.end);
        if (range.line < 0) {
            /* line < 0 means no line number */
            printf("have no line number\n");
        }
        else {
            printf("have line number %d\n", range.line);
        }
    }
}